seatlock 0.1.0__tar.gz

seatlock-0.1.0/License

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [2026] [AdityaKatyal]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

seatlock-0.1.0/PKG-INFO

@@ -0,0 +1,331 @@
+Metadata-Version: 2.4
+Name: seatlock
+Version: 0.1.0
+Summary: A concurrency-safe seat allocation and booking engine
+Author: Aditya
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: License
+Dynamic: license-file
+
+# Seat Allocation Engine – Working Cycle
+
+This document explains **how the Seat Allocation Engine works internally**, step by step. It focuses on the **lifecycle of a seat**, **locking rules**, **bulk operations**, and **cleanup mechanics**. No UI, API, or framework concepts are involved here—this is purely the domain engine.
+
+---
+
+## 1. Core Purpose
+
+The engine is designed to solve one problem **correctly**:
+
+> Allocate seats to users in a safe, fair, and deterministic way.
+
+It guarantees:
+- No double booking
+- No permanent locks
+- No partial group bookings
+- No lock stealing
+
+---
+
+## 2. Core Concepts
+
+### 2.1 Seat as a Resource
+Each seat is treated as an **independent resource**.
+
+A seat has exactly one of three states:
+- `AVAILABLE`
+- `LOCKED`
+- `BOOKED`
+
+Once a seat is `BOOKED`, it is **terminal** and cannot change state.
+
+---
+
+### 2.2 Seat Ownership
+
+When a seat is locked:
+- It is owned by exactly **one user**
+- Only that user can book it
+- Other users are rejected
+
+Ownership is enforced strictly at all times.
+
+---
+
+## 3. Seat Lifecycle
+
+The lifecycle of a seat follows this strict state machine:
+
+```
+AVAILABLE → LOCKED → BOOKED
+     ↑        |
+     └────────┘  (lock expiry)
+```
+
+Invalid transitions are never allowed.
+
+---
+
+## 4. Locking Mechanism
+
+### 4.1 Single Seat Locking
+
+When a user requests to lock a seat:
+
+1. The engine checks if the seat exists
+2. If the seat is `BOOKED` → reject
+3. If the seat is `LOCKED` → reject
+4. If the seat is `AVAILABLE` → lock it
+
+A successful lock records:
+- `locked_by` (user id)
+- `lock_time` (timestamp)
+
+---
+
+### 4.2 Bulk Seat Locking (Group Selection)
+
+Bulk locking is **atomic**.
+
+This means:
+> Either all seats are locked, or none are.
+
+#### Working cycle:
+
+**Phase 1 – Validation (read-only)**
+- All seats must exist
+- All seats must be `AVAILABLE`
+- If any seat fails → abort immediately
+
+**Phase 2 – Commit (write)**
+- All seats are locked together
+- Same user
+- Same lock timestamp
+
+No partial locking is ever possible.
+
+---
+
+## 5. Booking Mechanism
+
+### 5.1 Single Seat Booking
+
+To book a seat:
+
+1. Seat must exist
+2. Seat must be `LOCKED`
+3. Seat must be locked by the same user
+
+If all checks pass:
+- Seat transitions to `BOOKED`
+- Lock metadata is cleared
+
+---
+
+### 5.2 Bulk Seat Booking
+
+Bulk booking follows the same atomic principle as bulk locking.
+
+**Validation phase:**
+- All seats must exist
+- All seats must be `LOCKED`
+- All seats must be locked by the same user
+
+**Commit phase:**
+- All seats transition to `BOOKED`
+
+If any seat fails validation → **no seat is booked**.
+
+---
+
+## 6. Lock Expiry (Auto Release)
+
+Locks are **temporary by design**.
+
+### 6.1 Timeout Rule
+
+- Each lock has a maximum lifetime (`LOCK_TIMEOUT`)
+- Default: 10 seconds
+
+---
+
+### 6.2 Cleanup Mechanism
+
+Lock expiry is handled by a **system-level cleanup function**:
+
+```
+cleanup_expired_locks()
+```
+
+This function:
+- Iterates over all seats
+- Releases locks that exceeded the timeout
+- Never depends on user actions
+
+Important rule:
+
+> A lock may expire, but it is never stolen by another user.
+
+---
+
+## 7. Concurrency Safety
+
+All operations run inside a **global lock**.
+
+This guarantees:
+- Atomic operations
+- No race conditions
+- Deterministic behavior
+
+The engine prioritizes **correctness over performance**.
+
+---
+
+## 8. Separation of Responsibilities
+
+| Layer | Responsibility |
+|-----|--------------|
+| Seat | State + truth checks |
+| SeatManager | Transitions + rules |
+| Cleanup | Time-based expiry |
+| UI / API | Input & presentation only |
+
+The engine does **not** know about:
+- Clicks
+- HTTP
+- UI state
+- Databases
+
+---
+
+## 9. What This Engine Guarantees
+
+✔ No double booking
+✔ No permanent locks
+✔ No partial group bookings
+✔ Strong ownership enforcement
+✔ Deterministic outcomes
+
+---
+
+## 10. What This Engine Intentionally Does NOT Do
+
+- No UI rendering
+- No HTTP / REST handling
+- No persistence
+- No background threads
+
+These are integration concerns and belong outside the engine.
+
+---
+
+## 11. Intended Usage
+
+This engine is designed to be:
+- Packaged as a reusable library
+- Called from event-driven systems
+- Used under web, desktop, or CLI interfaces
+
+The engine remains unchanged while integrations evolve.
+
+---
+
+## 12. Final Note
+
+This is a **domain-correct seat allocation engine**.
+
+All future work (UI, APIs, persistence, scaling) should be built **on top of this logic**, not mixed into it.
+
+This separation is intentional and fundamental.
+
+
+
+---
+
+# Public API Reference
+
+This section lists **all public methods exposed by the SeatLock engine**, with a one-line explanation of what each does. These are the only methods consumers should rely on.
+
+---
+
+## Importing the Engine
+
+```python
+from seatlock import Seat, SeatManager
+```
+
+---
+
+## Core Classes
+
+### `Seat`
+Represents a single seat as an independent resource.
+
+- `Seat(seat_id)` → Create a new seat with a unique identifier
+- `is_available()` → Returns `True` if the seat is free
+- `is_locked()` → Returns `True` if the seat is temporarily reserved
+- `is_booked()` → Returns `True` if the seat is permanently booked
+
+---
+
+### `SeatManager`
+Central engine that enforces all locking, booking, cancellation, and cleanup rules.
+
+---
+
+## Locking Methods
+
+- `lock_seat(seat_id, user_id)`  
+  Locks a single available seat for a user
+
+- `lock_seats_bulk(seat_ids, user_id)`  
+  Atomically locks multiple seats for a user (all-or-nothing)
+
+---
+
+## Booking Methods
+
+- `book_a_seat(seat_id, user_id)`  
+  Permanently books a single seat previously locked by the same user
+
+- `book_seats_bulk(seat_ids, user_id)`  
+  Atomically books multiple seats previously locked by the same user
+
+---
+
+## Cancellation Methods
+
+- `cancel_lock(seat_id, user_id)`  
+  Releases a lock held by the user on a single seat
+
+- `cancel_locks_bulk(seat_ids, user_id)`  
+  Atomically releases locks held by the user on multiple seats
+
+---
+
+## Cleanup / System Methods
+
+- `cleanup_expired_locks()`  
+  System-level method that releases all locks exceeding the configured timeout
+
+---
+
+## Notes on Usage
+
+- All methods are **thread-safe**
+- All bulk operations are **atomic**
+- Only the lock owner may book or cancel seats
+- Booked seats are **final and immutable**
+- Time-based lock expiry is handled **only** by `cleanup_expired_locks`
+
+---
+
+This API is intentionally minimal and stable. All UI, event handling, persistence, and networking should be built **on top of these methods**, not mixe

seatlock-0.1.0/README.md

@@ -0,0 +1,314 @@
+# Seat Allocation Engine – Working Cycle
+
+This document explains **how the Seat Allocation Engine works internally**, step by step. It focuses on the **lifecycle of a seat**, **locking rules**, **bulk operations**, and **cleanup mechanics**. No UI, API, or framework concepts are involved here—this is purely the domain engine.
+
+---
+
+## 1. Core Purpose
+
+The engine is designed to solve one problem **correctly**:
+
+> Allocate seats to users in a safe, fair, and deterministic way.
+
+It guarantees:
+- No double booking
+- No permanent locks
+- No partial group bookings
+- No lock stealing
+
+---
+
+## 2. Core Concepts
+
+### 2.1 Seat as a Resource
+Each seat is treated as an **independent resource**.
+
+A seat has exactly one of three states:
+- `AVAILABLE`
+- `LOCKED`
+- `BOOKED`
+
+Once a seat is `BOOKED`, it is **terminal** and cannot change state.
+
+---
+
+### 2.2 Seat Ownership
+
+When a seat is locked:
+- It is owned by exactly **one user**
+- Only that user can book it
+- Other users are rejected
+
+Ownership is enforced strictly at all times.
+
+---
+
+## 3. Seat Lifecycle
+
+The lifecycle of a seat follows this strict state machine:
+
+```
+AVAILABLE → LOCKED → BOOKED
+     ↑        |
+     └────────┘  (lock expiry)
+```
+
+Invalid transitions are never allowed.
+
+---
+
+## 4. Locking Mechanism
+
+### 4.1 Single Seat Locking
+
+When a user requests to lock a seat:
+
+1. The engine checks if the seat exists
+2. If the seat is `BOOKED` → reject
+3. If the seat is `LOCKED` → reject
+4. If the seat is `AVAILABLE` → lock it
+
+A successful lock records:
+- `locked_by` (user id)
+- `lock_time` (timestamp)
+
+---
+
+### 4.2 Bulk Seat Locking (Group Selection)
+
+Bulk locking is **atomic**.
+
+This means:
+> Either all seats are locked, or none are.
+
+#### Working cycle:
+
+**Phase 1 – Validation (read-only)**
+- All seats must exist
+- All seats must be `AVAILABLE`
+- If any seat fails → abort immediately
+
+**Phase 2 – Commit (write)**
+- All seats are locked together
+- Same user
+- Same lock timestamp
+
+No partial locking is ever possible.
+
+---
+
+## 5. Booking Mechanism
+
+### 5.1 Single Seat Booking
+
+To book a seat:
+
+1. Seat must exist
+2. Seat must be `LOCKED`
+3. Seat must be locked by the same user
+
+If all checks pass:
+- Seat transitions to `BOOKED`
+- Lock metadata is cleared
+
+---
+
+### 5.2 Bulk Seat Booking
+
+Bulk booking follows the same atomic principle as bulk locking.
+
+**Validation phase:**
+- All seats must exist
+- All seats must be `LOCKED`
+- All seats must be locked by the same user
+
+**Commit phase:**
+- All seats transition to `BOOKED`
+
+If any seat fails validation → **no seat is booked**.
+
+---
+
+## 6. Lock Expiry (Auto Release)
+
+Locks are **temporary by design**.
+
+### 6.1 Timeout Rule
+
+- Each lock has a maximum lifetime (`LOCK_TIMEOUT`)
+- Default: 10 seconds
+
+---
+
+### 6.2 Cleanup Mechanism
+
+Lock expiry is handled by a **system-level cleanup function**:
+
+```
+cleanup_expired_locks()
+```
+
+This function:
+- Iterates over all seats
+- Releases locks that exceeded the timeout
+- Never depends on user actions
+
+Important rule:
+
+> A lock may expire, but it is never stolen by another user.
+
+---
+
+## 7. Concurrency Safety
+
+All operations run inside a **global lock**.
+
+This guarantees:
+- Atomic operations
+- No race conditions
+- Deterministic behavior
+
+The engine prioritizes **correctness over performance**.
+
+---
+
+## 8. Separation of Responsibilities
+
+| Layer | Responsibility |
+|-----|--------------|
+| Seat | State + truth checks |
+| SeatManager | Transitions + rules |
+| Cleanup | Time-based expiry |
+| UI / API | Input & presentation only |
+
+The engine does **not** know about:
+- Clicks
+- HTTP
+- UI state
+- Databases
+
+---
+
+## 9. What This Engine Guarantees
+
+✔ No double booking
+✔ No permanent locks
+✔ No partial group bookings
+✔ Strong ownership enforcement
+✔ Deterministic outcomes
+
+---
+
+## 10. What This Engine Intentionally Does NOT Do
+
+- No UI rendering
+- No HTTP / REST handling
+- No persistence
+- No background threads
+
+These are integration concerns and belong outside the engine.
+
+---
+
+## 11. Intended Usage
+
+This engine is designed to be:
+- Packaged as a reusable library
+- Called from event-driven systems
+- Used under web, desktop, or CLI interfaces
+
+The engine remains unchanged while integrations evolve.
+
+---
+
+## 12. Final Note
+
+This is a **domain-correct seat allocation engine**.
+
+All future work (UI, APIs, persistence, scaling) should be built **on top of this logic**, not mixed into it.
+
+This separation is intentional and fundamental.
+
+
+
+---
+
+# Public API Reference
+
+This section lists **all public methods exposed by the SeatLock engine**, with a one-line explanation of what each does. These are the only methods consumers should rely on.
+
+---
+
+## Importing the Engine
+
+```python
+from seatlock import Seat, SeatManager
+```
+
+---
+
+## Core Classes
+
+### `Seat`
+Represents a single seat as an independent resource.
+
+- `Seat(seat_id)` → Create a new seat with a unique identifier
+- `is_available()` → Returns `True` if the seat is free
+- `is_locked()` → Returns `True` if the seat is temporarily reserved
+- `is_booked()` → Returns `True` if the seat is permanently booked
+
+---
+
+### `SeatManager`
+Central engine that enforces all locking, booking, cancellation, and cleanup rules.
+
+---
+
+## Locking Methods
+
+- `lock_seat(seat_id, user_id)`  
+  Locks a single available seat for a user
+
+- `lock_seats_bulk(seat_ids, user_id)`  
+  Atomically locks multiple seats for a user (all-or-nothing)
+
+---
+
+## Booking Methods
+
+- `book_a_seat(seat_id, user_id)`  
+  Permanently books a single seat previously locked by the same user
+
+- `book_seats_bulk(seat_ids, user_id)`  
+  Atomically books multiple seats previously locked by the same user
+
+---
+
+## Cancellation Methods
+
+- `cancel_lock(seat_id, user_id)`  
+  Releases a lock held by the user on a single seat
+
+- `cancel_locks_bulk(seat_ids, user_id)`  
+  Atomically releases locks held by the user on multiple seats
+
+---
+
+## Cleanup / System Methods
+
+- `cleanup_expired_locks()`  
+  System-level method that releases all locks exceeding the configured timeout
+
+---
+
+## Notes on Usage
+
+- All methods are **thread-safe**
+- All bulk operations are **atomic**
+- Only the lock owner may book or cancel seats
+- Booked seats are **final and immutable**
+- Time-based lock expiry is handled **only** by `cleanup_expired_locks`
+
+---
+
+This API is intentionally minimal and stable. All UI, event handling, persistence, and networking should be built **on top of these methods**, not mixe

seatlock-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+
+[project]
+name = "seatlock"
+version = "0.1.0"
+description = "A concurrency-safe seat allocation and booking engine"
+readme = "README.md"
+requires-python = ">=3.8"
+
+authors = [
+    { name = "Aditya" }
+]
+
+license = { text = "MIT" }
+
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Operating System :: OS Independent",
+    "License :: OSI Approved :: MIT License",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries"
+]
+
+dependencies = []
+
+
+[tool.setuptools]
+packages = ["seatlock"]

seatlock-0.1.0/seatlock/__init__.py

@@ -0,0 +1,2 @@
+from .seat import Seat
+from .manager import SeatManager

seatlock-0.1.0/seatlock/manager.py

@@ -0,0 +1,177 @@
+import threading, time
+from .states import AVAILABLE, BOOKED, LOCKED
+
+
+class SeatManager:
+    LOCK_TIMEOUT = 10  # seconds
+
+    def __init__(self, seats):
+        self.seats = {seat.seat_id: seat for seat in seats}
+        self.global_lock = threading.Lock()
+
+
+    def cleanup_expired_locks(self):
+        with self.global_lock:
+            now = time.time()
+
+            for seat in self.seats.values():
+                if seat.is_locked():
+                    if now - seat.lock_time > self.LOCK_TIMEOUT:
+                        self._release_lock(seat)
+
+
+    def lock_seat(self, seat_id, user_id):
+        with self.global_lock:
+            seat = self.seats.get(seat_id)
+
+            if not seat:
+                return f"Seat {seat_id} does not exist"
+
+            # Expire old lock if timeout passed
+            if seat.is_locked():
+                if time.time() - seat.lock_time > self.LOCK_TIMEOUT:
+                    self._release_lock(seat)
+
+            if seat.is_booked():
+                return f"Seat {seat_id} is already booked"
+
+            if seat.is_locked():
+                return f"Seat {seat_id} is currently locked by {seat.locked_by}"
+
+            seat.status = LOCKED
+            seat.locked_by = user_id
+            seat.lock_time = time.time()
+
+            return f"Seat {seat_id} is locked by {user_id}"
+
+
+    def lock_seats_bulk(self, seat_ids, user_id):
+        with self.global_lock:
+            seats_to_lock = []
+
+            # Phase 1: validation (READ-ONLY)
+            for seat_id in seat_ids:
+                seat = self.seats.get(seat_id)
+
+                if not seat:
+                    return f"Seat {seat_id} does not exist"
+
+                if seat.is_booked():
+                    return f"Seat {seat_id} is already booked"
+
+                if seat.is_locked():
+                    # If locked by someone else, reject
+                    return f"Seat {seat_id} is locked by {seat.locked_by}"
+
+                seats_to_lock.append(seat)
+
+            # Phase 2: commit (WRITE)
+            lock_time = time.time()
+            for seat in seats_to_lock:
+                seat.status = LOCKED
+                seat.locked_by = user_id
+                seat.lock_time = lock_time
+
+            return f"Seats {seat_ids} locked by {user_id}"
+        
+
+    def book_a_seat(self, seat_id, user_id):
+        with self.global_lock:
+            seat = self.seats.get(seat_id)
+
+            if not seat:
+                return f"Seat {seat_id} does not exist"
+
+            if not seat.is_locked():
+                return f"Seat {seat_id} is not locked"
+
+            if seat.locked_by != user_id:
+                return f"Seat {seat_id} is locked by another user"
+
+            seat.status = BOOKED
+            seat.locked_by = None
+            seat.lock_time = None
+
+            return f"Seat {seat_id} is now booked by {user_id}"
+        
+
+    def book_seats_bulk(self, seat_ids, user_id):
+          with self.global_lock:
+            seats_to_book = []
+
+            # Validation
+            for seat_id in seat_ids:
+                seat = self.seats.get(seat_id)
+
+                if not seat:
+                    return f"Seat {seat_id} does not exist"
+
+                if not seat.is_locked():
+                    return f"Seat {seat_id} is not locked"
+
+                if seat.locked_by != user_id:
+                    return f"Seat {seat_id} is locked by another user"
+
+                seats_to_book.append(seat)
+
+            # Commit booking
+            for seat in seats_to_book:
+                seat.status = BOOKED
+                seat.locked_by = None
+                seat.lock_time = None
+
+            return f"Seats {seat_ids} successfully booked by {user_id}"
+    def cancel_lock(self, seat_id, user_id):
+        with self.global_lock:
+            seat = self.seats.get(seat_id)
+
+            if not seat:
+                return f"Seat {seat_id} does not exist"
+
+            if seat.is_booked():
+                return f"Seat {seat_id} is already booked and cannot be cancelled"
+
+            if not seat.is_locked():
+                return f"Seat {seat_id} is not locked"
+
+            if seat.locked_by != user_id:
+                return f"Seat {seat_id} is locked by another user"
+
+            self._release_lock(seat)
+            return f"Seat {seat_id} lock cancelled by {user_id}"
+    
+    def cancel_locks_bulk(self, seat_ids, user_id):
+        with self.global_lock:
+            seats_to_cancel = []
+
+            # Validation phase
+            for seat_id in seat_ids:
+                seat = self.seats.get(seat_id)
+
+                if not seat:
+                    return f"Seat {seat_id} does not exist"
+
+                if seat.is_booked():
+                    return f"Seat {seat_id} is already booked and cannot be cancelled"
+
+                if not seat.is_locked():
+                    return f"Seat {seat_id} is not locked"
+
+                if seat.locked_by != user_id:
+                    return f"Seat {seat_id} is locked by another user"
+
+                seats_to_cancel.append(seat)
+
+            # Commit phase
+            for seat in seats_to_cancel:
+                self._release_lock(seat)
+
+            return f"Locks for seats {seat_ids} cancelled by {user_id}"
+
+
+
+
+    def _release_lock(self, seat):
+        seat.status = AVAILABLE
+        seat.locked_by = None
+        seat.lock_time = None

seatlock-0.1.0/seatlock/seat.py

@@ -0,0 +1,20 @@
+
+from .states import AVAILABLE, LOCKED, BOOKED
+
+
+class Seat:
+    def __init__(self, seat_id):
+        self.seat_id = seat_id
+        self.status = AVAILABLE
+        self.locked_by = None
+        self.lock_time = None
+
+    def is_locked(self):
+        return self.status == LOCKED
+    
+    def is_available(self):
+        return self.status == AVAILABLE
+
+    def is_booked(self):
+        return self.status == BOOKED    
+

seatlock-0.1.0/seatlock/states.py

@@ -0,0 +1,3 @@
+AVAILABLE = "AVAILABLE"
+LOCKED = "LOCKED"
+BOOKED = "BOOKED"

seatlock-0.1.0/seatlock.egg-info/PKG-INFO

@@ -0,0 +1,331 @@
+Metadata-Version: 2.4
+Name: seatlock
+Version: 0.1.0
+Summary: A concurrency-safe seat allocation and booking engine
+Author: Aditya
+License: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Intended Audience :: Developers
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: License
+Dynamic: license-file
+
+# Seat Allocation Engine – Working Cycle
+
+This document explains **how the Seat Allocation Engine works internally**, step by step. It focuses on the **lifecycle of a seat**, **locking rules**, **bulk operations**, and **cleanup mechanics**. No UI, API, or framework concepts are involved here—this is purely the domain engine.
+
+---
+
+## 1. Core Purpose
+
+The engine is designed to solve one problem **correctly**:
+
+> Allocate seats to users in a safe, fair, and deterministic way.
+
+It guarantees:
+- No double booking
+- No permanent locks
+- No partial group bookings
+- No lock stealing
+
+---
+
+## 2. Core Concepts
+
+### 2.1 Seat as a Resource
+Each seat is treated as an **independent resource**.
+
+A seat has exactly one of three states:
+- `AVAILABLE`
+- `LOCKED`
+- `BOOKED`
+
+Once a seat is `BOOKED`, it is **terminal** and cannot change state.
+
+---
+
+### 2.2 Seat Ownership
+
+When a seat is locked:
+- It is owned by exactly **one user**
+- Only that user can book it
+- Other users are rejected
+
+Ownership is enforced strictly at all times.
+
+---
+
+## 3. Seat Lifecycle
+
+The lifecycle of a seat follows this strict state machine:
+
+```
+AVAILABLE → LOCKED → BOOKED
+     ↑        |
+     └────────┘  (lock expiry)
+```
+
+Invalid transitions are never allowed.
+
+---
+
+## 4. Locking Mechanism
+
+### 4.1 Single Seat Locking
+
+When a user requests to lock a seat:
+
+1. The engine checks if the seat exists
+2. If the seat is `BOOKED` → reject
+3. If the seat is `LOCKED` → reject
+4. If the seat is `AVAILABLE` → lock it
+
+A successful lock records:
+- `locked_by` (user id)
+- `lock_time` (timestamp)
+
+---
+
+### 4.2 Bulk Seat Locking (Group Selection)
+
+Bulk locking is **atomic**.
+
+This means:
+> Either all seats are locked, or none are.
+
+#### Working cycle:
+
+**Phase 1 – Validation (read-only)**
+- All seats must exist
+- All seats must be `AVAILABLE`
+- If any seat fails → abort immediately
+
+**Phase 2 – Commit (write)**
+- All seats are locked together
+- Same user
+- Same lock timestamp
+
+No partial locking is ever possible.
+
+---
+
+## 5. Booking Mechanism
+
+### 5.1 Single Seat Booking
+
+To book a seat:
+
+1. Seat must exist
+2. Seat must be `LOCKED`
+3. Seat must be locked by the same user
+
+If all checks pass:
+- Seat transitions to `BOOKED`
+- Lock metadata is cleared
+
+---
+
+### 5.2 Bulk Seat Booking
+
+Bulk booking follows the same atomic principle as bulk locking.
+
+**Validation phase:**
+- All seats must exist
+- All seats must be `LOCKED`
+- All seats must be locked by the same user
+
+**Commit phase:**
+- All seats transition to `BOOKED`
+
+If any seat fails validation → **no seat is booked**.
+
+---
+
+## 6. Lock Expiry (Auto Release)
+
+Locks are **temporary by design**.
+
+### 6.1 Timeout Rule
+
+- Each lock has a maximum lifetime (`LOCK_TIMEOUT`)
+- Default: 10 seconds
+
+---
+
+### 6.2 Cleanup Mechanism
+
+Lock expiry is handled by a **system-level cleanup function**:
+
+```
+cleanup_expired_locks()
+```
+
+This function:
+- Iterates over all seats
+- Releases locks that exceeded the timeout
+- Never depends on user actions
+
+Important rule:
+
+> A lock may expire, but it is never stolen by another user.
+
+---
+
+## 7. Concurrency Safety
+
+All operations run inside a **global lock**.
+
+This guarantees:
+- Atomic operations
+- No race conditions
+- Deterministic behavior
+
+The engine prioritizes **correctness over performance**.
+
+---
+
+## 8. Separation of Responsibilities
+
+| Layer | Responsibility |
+|-----|--------------|
+| Seat | State + truth checks |
+| SeatManager | Transitions + rules |
+| Cleanup | Time-based expiry |
+| UI / API | Input & presentation only |
+
+The engine does **not** know about:
+- Clicks
+- HTTP
+- UI state
+- Databases
+
+---
+
+## 9. What This Engine Guarantees
+
+✔ No double booking
+✔ No permanent locks
+✔ No partial group bookings
+✔ Strong ownership enforcement
+✔ Deterministic outcomes
+
+---
+
+## 10. What This Engine Intentionally Does NOT Do
+
+- No UI rendering
+- No HTTP / REST handling
+- No persistence
+- No background threads
+
+These are integration concerns and belong outside the engine.
+
+---
+
+## 11. Intended Usage
+
+This engine is designed to be:
+- Packaged as a reusable library
+- Called from event-driven systems
+- Used under web, desktop, or CLI interfaces
+
+The engine remains unchanged while integrations evolve.
+
+---
+
+## 12. Final Note
+
+This is a **domain-correct seat allocation engine**.
+
+All future work (UI, APIs, persistence, scaling) should be built **on top of this logic**, not mixed into it.
+
+This separation is intentional and fundamental.
+
+
+
+---
+
+# Public API Reference
+
+This section lists **all public methods exposed by the SeatLock engine**, with a one-line explanation of what each does. These are the only methods consumers should rely on.
+
+---
+
+## Importing the Engine
+
+```python
+from seatlock import Seat, SeatManager
+```
+
+---
+
+## Core Classes
+
+### `Seat`
+Represents a single seat as an independent resource.
+
+- `Seat(seat_id)` → Create a new seat with a unique identifier
+- `is_available()` → Returns `True` if the seat is free
+- `is_locked()` → Returns `True` if the seat is temporarily reserved
+- `is_booked()` → Returns `True` if the seat is permanently booked
+
+---
+
+### `SeatManager`
+Central engine that enforces all locking, booking, cancellation, and cleanup rules.
+
+---
+
+## Locking Methods
+
+- `lock_seat(seat_id, user_id)`  
+  Locks a single available seat for a user
+
+- `lock_seats_bulk(seat_ids, user_id)`  
+  Atomically locks multiple seats for a user (all-or-nothing)
+
+---
+
+## Booking Methods
+
+- `book_a_seat(seat_id, user_id)`  
+  Permanently books a single seat previously locked by the same user
+
+- `book_seats_bulk(seat_ids, user_id)`  
+  Atomically books multiple seats previously locked by the same user
+
+---
+
+## Cancellation Methods
+
+- `cancel_lock(seat_id, user_id)`  
+  Releases a lock held by the user on a single seat
+
+- `cancel_locks_bulk(seat_ids, user_id)`  
+  Atomically releases locks held by the user on multiple seats
+
+---
+
+## Cleanup / System Methods
+
+- `cleanup_expired_locks()`  
+  System-level method that releases all locks exceeding the configured timeout
+
+---
+
+## Notes on Usage
+
+- All methods are **thread-safe**
+- All bulk operations are **atomic**
+- Only the lock owner may book or cancel seats
+- Booked seats are **final and immutable**
+- Time-based lock expiry is handled **only** by `cleanup_expired_locks`
+
+---
+
+This API is intentionally minimal and stable. All UI, event handling, persistence, and networking should be built **on top of these methods**, not mixe

seatlock-0.1.0/seatlock.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+License
+README.md
+pyproject.toml
+seatlock/__init__.py
+seatlock/manager.py
+seatlock/seat.py
+seatlock/states.py
+seatlock.egg-info/PKG-INFO
+seatlock.egg-info/SOURCES.txt
+seatlock.egg-info/dependency_links.txt
+seatlock.egg-info/top_level.txt

seatlock-0.1.0/seatlock.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

seatlock-0.1.0/seatlock.egg-info/top_level.txt

@@ -0,0 +1 @@
+seatlock

seatlock-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+