Initial release: Datalastic Python SDK v0.1.0

Author: datalastic

.github/workflows/publish.yml

@@ -0,0 +1,48 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest tests/ -v
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install build tooling
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine
+      - name: Build distributions
+        run: python -m build
+      - name: Check distributions
+        run: twine check dist/*
+      - name: Publish to PyPI
+        env:
+          TWINE_USERNAME: __token__
+          TWINE_PASSWORD: ${{ secrets.PYPI_TOKEN }}
+        run: twine upload dist/*

.gitignore

@@ -0,0 +1,39 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+wheels/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# IDEs / editors
+.idea/
+.vscode/
+*.swp
+.DS_Store
+
+# Secrets
+.env
+*.env
+
+# Internal dev notes — keep off GitHub
+CLAUDE.md

AGENTS.md

@@ -0,0 +1,72 @@
+# Agent guide
+
+Guidance for AI assistants working in this repository.
+
+## Setup
+
+```bash
+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.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Datalastic
+
+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.