Fixed formatting

Author: fischmrl

README.md

@@ -1,10 +1,10 @@
 # Symbology Server
 
-A Python FastAPI Symbology Server that maintains persistent mappings between human-readable symbols (e.g. `NVDA`) and numeric identifiers via an HTTP API for querying/updating mappings over time.
+A Python FastAPI Symbology Server that maintains persistent mappings between human-readable symbols (e.g. `NVDA`) and numeric identifiers via an HTTP API for querying/updating symbol and identifier mappings over time.
 
 ## Features
 - HTTP API to register, terminate, and query symbology mappings
-- Enforces:
+- Enforces the following domain constraints:
   - One identifier per symbol per date
   - One symbol per identifier per date
   - Persistent mappings until explicit termination
@@ -13,26 +13,26 @@ A Python FastAPI Symbology Server that maintains persistent mappings between hum
   - Symbol for an identifier on a specified date
   - All mappings overlapping a specific half-open date range `[begin, end)`
 - In-memory `MappingStorage` by default
-- Fully automated test suite with `pytest`
+- Fully automated test suite using `pytest`
 
 ## Requirements
 - Python ≥ 3.10
-- Dependencies listed in `requirements.txt`
+- Dependencies listed in `requirements.txt` and `pyproject.toml`
 
 ## Design Notes
 - **Temporal Semantics**: A symbol’s assignment to an identifier is **persistent**. A mapping becomes active
 on its `start_date` and remains active until it is explicitly terminated. All dates are ISO-8601 (`YYYY-MM-DD`) and independent of wall-clock time.
 - **Reassignment Behavior**: If a symbol is reassigned to a new identifier, the previously active mapping is
-then terminated at the new mapping’s start date. This behavior applies to same-day and future-dated reassignments. At any point in time, a symbol and an identifier may be in at most one active mapping.
-- **Conflict Handling**: The following invariants are enforced:
+then terminated at the new mapping’s start date. Each symbol and identifier can only appear in one active mapping at a time.
+- **Conflict Handling**: Violations of the following invariants raise explicit domain-level exceptions (surfaced as HTTP errors):
   - A symbol may have only one active identifier on a given date
   - An identifier may be assigned to only one symbol on a given date
-  Violations raise explicit domain-level exceptions which are surfaced as HTTP errors at the API layer.
-- **Storage Model**: The storage layer is implemented as an in-memory collection, which is optimal for clarity and correctness rather than performance or persistence. This helps to keep the focus on symbology semantics and temporal reasoning.
-- **Scope and Limitations**: This symbology server implementation intentionally omits database persistence, concurrency control, and timezone normalization. These concerns are independent from the core problem and
-can be layered on without changing the domain model.
-- **Extensibility**: The domain model is intentionally decoupled from the storage layer, which allows alternative backends (e.g. database-backed, append-only log-based storage) to be introduced without changing any symbology semantics.
-- **Determinism**: All query results are deterministic functions of the input date parameters and stored mappings.
+- **Storage Model**: Uses an **in-memory storage layer** for clarity and correctness. Alternative storage backends (database, append-only log, etc.) can be introduced without changing the domain model.
+- **Scope and Limitations**: This implementation omits:
+  - Database persistence
+  - Concurrency control
+  - Timezone normalization
+- **Determinism**: All query results are deterministic functions of input dates and stored mappings.
 
 ## Setup
 
@@ -44,20 +44,43 @@ pip install -r requirements.txt
 
 ## Running the Server
 
+```bash
 uvicorn src.main:app --reload --port 8000
+```
+
+- The API will be available at http://localhost:8000.
 
 ## Running Tests
 
 pytest tests/
 
-## Example Usage of API
+## Example API Usage
+
+### Add a mapping
 
 curl -X POST http://localhost:8000/mapping \
   -H "Content-Type: application/json" \
   -d '{"symbol":"AAPL","identifier":1,"start_date":"2024-01-01"}'
 
+
+### Query identifier for a symbol
+
+curl "http://localhost:8000/symbol/AAPL?date=2024-01-02"
+
+
+### Terminate a mapping
+
+curl -X POST http://localhost:8000/mapping/terminate \
+  -H "Content-Type: application/json" \
+  -d '{"symbol":"AAPL","end_date":"2024-01-05"}'
+
+
+### Query mappings in a date range
+
+curl "http://localhost:8000/mappings?begin=2024-01-01&end=2024-01-10"
+
 ## Notes
 
 - Dependencies are defined in pyproject.toml.
-- requirements.txt is provided for convenience (pip install -r requirements.txt).
-- This project focuses on clarity and correctness of symbology semantics rather than concerns at a production scale.
+- requirements.txt is provided for convenience.
+- Focus is on clarity and correctness of symbology semantics rather than production-scale performance.

src/domain.py

@@ -12,6 +12,8 @@
 
 
 class SymbologyServer:
+    """Domain layer for symbology server."""
+    
     def __init__(self, storage: MappingStorage) -> None:
         self.storage = storage
 
@@ -44,6 +46,7 @@ def add_mapping(self, symbol: str, identifier: int, start_date: date) -> None:
         )
 
     def terminate_mapping(self, symbol: str, end_date: date) -> None:
+        """Terminate an active mapping for the given symbol on end_date."""
         try:
             self.storage.terminate(symbol, end_date)
         except KeyError:
@@ -52,16 +55,19 @@ def terminate_mapping(self, symbol: str, end_date: date) -> None:
             )
 
     def get_identifier(self, symbol: str, on: date) -> int:
+        """Get the identifier for a symbol on a given date."""
         m = self.storage.find_active_by_symbol(symbol, on)
         if not m:
             raise NotFoundError(f"No mapping for symbol '{symbol}' on {on}")
         return m.identifier
 
     def get_symbol(self, identifier: int, on: date) -> str:
+        """Get the symbol for an identifier on a given date."""
         m = self.storage.find_active_by_identifier(identifier, on)
         if not m:
             raise NotFoundError(f"No mapping for identifier '{identifier}' on {on}")
         return m.symbol
 
     def get_mappings_between(self, begin: date, end: date) -> List[Mapping]:
+        """Get all mappings overlapping the given date range [begin, end)."""
         return self.storage.find_range(begin, end)

src/routes.py

@@ -17,6 +17,7 @@ def create_router(domain: SymbologyServer) -> APIRouter:
 
     @router.post("/mapping")
     def add_mapping(request: MappingCreate):
+        """Add a new symbology mapping."""
         try:
             domain.add_mapping(
                 request.symbol,
@@ -34,6 +35,7 @@ def add_mapping(request: MappingCreate):
 
     @router.post("/mapping/terminate")
     def terminate_mapping(request: MappingTerminate):
+        """Terminate an active symbology mapping."""
         try:
             domain.terminate_mapping(request.symbol, request.end_date)
             return {
@@ -46,20 +48,23 @@ def terminate_mapping(request: MappingTerminate):
 
     @router.get("/symbol/{symbol}", response_model=int)
     def get_identifier(symbol: str, date: date):
+        """Get the identifier for a symbol on a given date."""
         try:
             return domain.get_identifier(symbol, date)
         except NotFoundError as exc:
             raise HTTPException(status_code=404, detail=str(exc))
 
     @router.get("/identifier/{identifier}", response_model=str)
     def get_symbol(identifier: int, date: date):
+        """Get the symbol for an identifier on a given date."""
         try:
             return domain.get_symbol(identifier, date)
         except NotFoundError as exc:
             raise HTTPException(status_code=404, detail=str(exc))
 
     @router.get("/mappings", response_model=List[MappingResponse])
     def get_mappings(begin: date, end: date):
+        """Get all mappings overlapping the given date range [begin, end)."""
         return domain.get_mappings_between(begin, end)
 
     return router

src/storage.py

@@ -11,13 +11,17 @@
 
 
 class MappingStorage:
+    """In-memory storage backend for symbology mappings."""
+    
     def __init__(self) -> None:
         self._mappings: List[Mapping] = []
 
     def insert(self, mapping: Mapping) -> None:
+        """Insert a new mapping."""
         self._mappings.append(mapping)
 
     def all(self) -> List[Mapping]:
+        """Return all mappings."""
         return list(self._mappings)
 
     def find_range(self, begin: date, end: date) -> List[Mapping]:
@@ -30,6 +34,7 @@ def find_range(self, begin: date, end: date) -> List[Mapping]:
         return results
 
     def find_active_by_symbol(self, symbol: str, on: date) -> Optional[Mapping]:
+        """Find active mapping for symbol on given date."""
         for m in self._mappings:
             if (
                 m.symbol == symbol
@@ -40,6 +45,7 @@ def find_active_by_symbol(self, symbol: str, on: date) -> Optional[Mapping]:
         return None
 
     def find_active_by_identifier(self, identifier: int, on: date) -> Optional[Mapping]:
+        """Find active mapping for identifier on given date."""
         for m in self._mappings:
             if (
                 m.identifier == identifier
@@ -50,6 +56,7 @@ def find_active_by_identifier(self, identifier: int, on: date) -> Optional[Mappi
         return None
 
     def terminate(self, symbol: str, end_date: date) -> None:
+        """Terminate active mapping for symbol on given date."""
         m = self.find_active_by_symbol(symbol, end_date)
         if not m:
             raise KeyError

tests/test_domain.py

@@ -10,21 +10,26 @@
 """
 
 from datetime import date
+import pytest
 from src.domain import SymbologyServer
 from src.storage import MappingStorage
-import pytest
-from src.exceptions import ConflictError
+from src.exceptions import ConflictError, NotFoundError
 
 
-def test_add_and_lookup_mapping() -> None:
-    """Verify a mapping can be added and queried."""
+def test_add_and_lookup_mapping():
     domain = SymbologyServer(MappingStorage())
     domain.add_mapping("AAPL", 1, date(2024, 1, 1))
     assert domain.get_identifier("AAPL", date(2024, 1, 2)) == 1
 
-
-def test_symbol_reassignment_same_date():
+def test_conflict_on_same_symbol():
     domain = SymbologyServer(MappingStorage())
     domain.add_mapping("AAPL", 1, date(2024, 1, 1))
     with pytest.raises(ConflictError):
         domain.add_mapping("AAPL", 2, date(2024, 1, 1))
+
+def test_termination_and_notfound():
+    domain = SymbologyServer(MappingStorage())
+    domain.add_mapping("AAPL", 1, date(2024, 1, 1))
+    domain.terminate_mapping("AAPL", date(2024, 1, 5))
+    with pytest.raises(NotFoundError):
+        domain.get_identifier("AAPL", date(2024, 1, 6))