Metadata-Version: 2.4
Name: parking-booking-engine
Version: 0.1.1
Summary: AWS-backed parking management library used by the Cloud Parking System
Author: Cloud Parking Maintainers
License-Expression: MIT
Project-URL: Homepage, https://github.com/Jaipalreddy2/parking-booking-engine
Project-URL: Repository, https://github.com/Jaipalreddy2/parking-booking-engine
Keywords: parking,aws,flask,dynamodb
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: boto3<2,>=1.42
Requires-Dist: Werkzeug<4,>=3.1

# 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

```bash
pip install parking-booking-engine
```

## Quick Start

```python
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

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

### Create a booking

```python
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

```python
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

```python
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

```python
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:

```bash
PYTHONPATH=. pytest -q tests/
```

Build and validate package metadata:

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

## License

MIT
