Skip to content

AGENTS.md

Latest commit

 

History

History
72 lines (59 loc) · 2.71 KB

AGENTS.md

File metadata and controls

72 lines (59 loc) · 2.71 KB
Raw

Agent guide

Guidance for AI assistants working in this repository.

Setup

pip install -e ".[dev]"
pytest tests/ -v

No network access is needed for tests; every HTTP call is mocked with unittest.mock.patch on requests.Session.get / requests.Session.post.

Project structure

datalastic/
  __init__.py     public exports (Client, models, exceptions)
  client.py       Client + _get/_post/_handle + base URLs + stat()
  vessels.py      VesselsResource (8 methods)
  ports.py        PortsResource (find, get)
  routes.py       RoutesResource (calculate)
  intel.py        IntelResource (8 maritime_reports endpoints)
  reports.py      ReportsResource (submit, get, list_all)
  models.py       dict-backed data classes, each with .raw and __repr__
  exceptions.py   exception hierarchy
tests/test_client.py

Key conventions

  • Auth is a query parameter. api-key is appended to params in _get() and injected into the JSON body in _post(). Never a header.
  • Three base URLs. BASE_V0 (default), BASE_EXT (sea routes, SAT-E), BASE_MR (all intel endpoints). Pass base= to _get().
  • Date params are renamed. Python from_date / to_date are sent as the from / to query keys. vessel_type in vessels.find() is sent as type to avoid shadowing the builtin.
  • None filtering. Always strip None values before building the request ({k: v for k, v in params.items() if v is not None}).
  • Validate before HTTP. Required-parameter checks raise ValueError before any request is made.
  • Bulk uses repeated params. vessels.bulk() builds a list of (key, value) tuples so identifiers are sent as mmsi=x&mmsi=y.
  • Response unwrapping. _get() / _post() unwrap the envelope and return body["data"] directly; callers use the returned value as the model data. List endpoints map each element into a model.
  • Models never raise on missing fields. They use .get() and keep the raw payload in .raw.

Exception hierarchy

DatalasticError
├── AuthenticationError       401
├── InsufficientCreditsError  402
├── NotFoundError             404
├── RateLimitError            429
└── APIError                  everything else; has .status_code

Timeouts, connection errors, non-JSON bodies, and missing data keys all map to APIError.

Testing conventions

  • Build fake responses with the make_response() / ok() helpers in tests/test_client.py.
  • Every resource method has a happy-path test plus validation-error tests.
  • Assert the called URL prefix to confirm the correct base URL is used.
  • Assert query params / JSON body to confirm renaming and auth injection.
  • Keep tests offline — never hit the live API.