How golles/tomtom-apis-python works
Project type and purpose
• This is an asynchronous Python client library (“tomtom-apis”) for interacting with various TomTom REST APIs. It’s not a full-stack application but a reusable SDK/module that your Python code imports.
• Purpose: provide typed, async wrappers around TomTom’s Automotive, Maps, Places, Routing, Tracking & Logistics, and Traffic APIs, handling HTTP calls, request/response modeling, error handling, and authentication.
File structure
• Top-level directories:
• src/tomtom_apis/ – all client code, organized into subpackages per API domain (automotive, maps, places, routing, tracking_logistics, traffic).
• examples/ – sample scripts demonstrating usage of the client.
• tests/ – pytest tests and fixtures covering each API domain.
• scripts/ – local CI helpers, test‐fixture updates, environment setup.
• Config files & tooling:
• .github/workflows/ – CI, code scanning, release.
• pyproject.toml & package.json – build, lint, publish metadata.
• .env.sample – environment variables (e.g., API key).
README for additional insights
• Highlights supported APIs and unimplemented endpoints.
• Points to examples directory.
• Mentions full type support (using Python typing and src/tomtom_apis/py.typed).
Main components & interactions
a. Components
• Client façade: tomtom_apis.api.TomTomClient (central entry point).
• API domains (subpackages):
– Automotive (src/tomtom_apis/automotive)
– Maps (src/tomtom_apis/maps)
– Places (src/tomtom_apis/places)
– Routing (src/tomtom_apis/routing)
– Tracking & Logistics (src/tomtom_apis/tracking_logistics)
– Traffic (src/tomtom_apis/traffic)
• Models layer: data classes under each domain’s models.py plus shared src/tomtom_apis/models.py.
• HTTP transport layer: internal HTTP client in src/tomtom_apis/api.py and utils.py.
• Exceptions: custom error types in src/tomtom_apis/exceptions.py.
• Configuration: environment variables (API key, base URL) loaded via .env.
• Client consumer (your application) and external TomTom services (REST endpoints).
b. Relationships & data flow
1. Consumer code imports TomTomClient.
2. Calls a domain method (e.g., client.places.search(...)).
3. Client builds HTTP request, injects credentials.
4. HTTP transport executes async request to TomTom REST endpoint.
5. HTTP layer returns JSON → parsed into typed Model classes.
6. If HTTP or API error, custom Exception is thrown.
7. Control returns to consumer code with a Python object or exception.
c. Architectural patterns & design principles
• Modular package per API domain.
• Façade pattern via TomTomClient.
• Single-responsibility: transport, models, exceptions, utils separated.
• Asynchronous I/O everywhere.
• Dependency injection via environment/config.
• Type safety: typed function signatures and data models.
d. Key technologies & libraries
• Async HTTP client (e.g., aiohttp or httpx, implied).
• Python typing (py.typed, PEP 484).
• pytest for tests.
• CI/CD: GitHub Actions.
• Shell scripts for local CI.