parking-booking-engine 0.1.1

AWS-backed parking management library used by the Cloud Parking System

parking-booking-engine

A reusable Python library for parking operations backed by AWS services.

parking-booking-engine provides ready-to-use managers for parking slots, bookings, evidence photo upload, event logging, and CloudWatch monitoring.

Features

• DynamoDB-backed slot management
• Booking lifecycle management with conflict checks
• S3 evidence photo upload and retrieval links
• SNS notifications and SQS event publishing
• Booking audit/event logs
• Occupancy and activity metrics to CloudWatch

Requirements

• Python 3.9+
• AWS credentials configured
• AWS resources in your target region

Required AWS resources:

• DynamoDB table: ParkingSlots
• DynamoDB table: ParkingBookings
• DynamoDB table for event logs (example: ParkingEventLogs)
• S3 bucket for booking photos
• Optional SNS topic ARN
• Optional SQS queue URL

Installation

pip install parking-booking-engine

Quick Start

import boto3
from parking_lib import SlotManager, BookingManager, AwsServiceManager, ParkingMonitor, EventLogManager

region = "us-east-1"
dynamodb = boto3.resource("dynamodb", region_name=region)

slot_manager = SlotManager(dynamodb_resource=dynamodb, region_name=region)
booking_manager = BookingManager(dynamodb_resource=dynamodb, region_name=region)
aws_services = AwsServiceManager(
    region_name=region,
    s3_bucket="your-s3-bucket",
    s3_prefix="booking-car-photos",
    sns_topic_arn="arn:aws:sns:us-east-1:123456789012:parking-bookings",
    sqs_queue_url="https://sqs.us-east-1.amazonaws.com/123456789012/parking-events",
)
monitor = ParkingMonitor(region_name=region)
event_log_manager = EventLogManager(table_name="ParkingEventLogs", region_name=region)

Common Usage

Create a slot

slot = slot_manager.add_slot(slot_number="A-101", location="Ground Floor")

Create a booking

booking = booking_manager.create_booking(
    user_id="user-123",
    slot_id=slot.slot_id,
    slot_number=slot.slot_number,
    start_time="2026-04-13T09:00",
    end_time="2026-04-13T12:00",
    vehicle_reg="141 D 123",
    timezone_name="Europe/Dublin",
)

Upload booking photo

photo_key = aws_services.upload_booking_car_photo(
    file_obj=file_obj,
    booking_id=booking.booking_id,
    user_id="user-123",
)

if photo_key:
    booking_manager.attach_evidence(booking.booking_id, photo_key)

Emit event + metrics

aws_services.queue_booking_event("BOOKING_CREATED", {
    "booking_id": booking.booking_id,
    "slot_id": booking.slot_id,
    "slot_number": booking.slot_number,
    "user_id": booking.user_id,
    "status": booking.status,
})

event_log_manager.create_event(
    event_type="BOOKING_CREATED",
    booking_id=booking.booking_id,
    user_id=booking.user_id,
    slot_number=booking.slot_number,
    actor_user_id=booking.user_id,
    status=booking.status,
)

monitor.log_booking_created()
monitor.log_occupancy(total=120, occupied=84)

Public API

from parking_lib import (
    ParkingSlot,
    SlotManager,
    Booking,
    BookingManager,
    AwsServiceManager,
    ParkingMonitor,
    EventLog,
    EventLogManager,
)

Error Handling

• ValueError: booking conflicts / invalid booking state
• PermissionError: unauthorized cancel/update operations
• Generic exceptions include underlying AWS service error details

Development

Run tests:

PYTHONPATH=. pytest -q tests/

Build and validate package metadata:

python -m build
python -m twine check dist/*

License

MIT