vessel-api-python 1.0.0__py3-none-any.whl

vessel_api_python/_transport.py

@@ -0,0 +1,185 @@
+"""HTTP transport middleware for auth and retry logic."""
+
+from __future__ import annotations
+
+import asyncio
+import datetime
+import math
+import random
+import time
+from email.utils import parsedate_to_datetime
+
+import httpx
+
+from ._constants import MAX_BACKOFF
+
+# ---------------------------------------------------------------------------
+# Auth transports
+# ---------------------------------------------------------------------------
+
+
+class AuthTransport(httpx.BaseTransport):
+    """Sync transport that adds Bearer token auth and User-Agent headers."""
+
+    def __init__(self, base: httpx.BaseTransport, api_key: str, user_agent: str) -> None:
+        self._base = base
+        self._api_key = api_key
+        self._user_agent = user_agent
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        request.headers["Authorization"] = f"Bearer {self._api_key}"
+        request.headers["User-Agent"] = self._user_agent
+        return self._base.handle_request(request)
+
+    def close(self) -> None:
+        self._base.close()
+
+
+class AsyncAuthTransport(httpx.AsyncBaseTransport):
+    """Async transport that adds Bearer token auth and User-Agent headers."""
+
+    def __init__(self, base: httpx.AsyncBaseTransport, api_key: str, user_agent: str) -> None:
+        self._base = base
+        self._api_key = api_key
+        self._user_agent = user_agent
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        request.headers["Authorization"] = f"Bearer {self._api_key}"
+        request.headers["User-Agent"] = self._user_agent
+        return await self._base.handle_async_request(request)
+
+    async def aclose(self) -> None:
+        await self._base.aclose()
+
+
+# ---------------------------------------------------------------------------
+# Retry transports
+# ---------------------------------------------------------------------------
+
+
+class RetryTransport(httpx.BaseTransport):
+    """Sync transport with retry logic for 429, 5xx, and transient errors.
+
+    Implements exponential backoff with jitter, respects Retry-After headers
+    (both seconds and HTTP-date formats), and caps backoff at 30 seconds.
+    Only retries non-idempotent methods (POST/PATCH) on 429.
+    """
+
+    def __init__(self, base: httpx.BaseTransport, max_retries: int = 3) -> None:
+        self._base = base
+        self._max_retries = max(max_retries, 0)
+
+    def handle_request(self, request: httpx.Request) -> httpx.Response:
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._base.handle_request(request)
+            except httpx.TransportError:
+                # Retry transient network errors for idempotent methods only.
+                if attempt >= self._max_retries or not _is_idempotent(request.method):
+                    raise
+                time.sleep(_calc_exp_backoff(attempt))
+                continue
+
+            if not _is_retryable(response.status_code) or attempt >= self._max_retries:
+                return response
+
+            # Don't retry non-idempotent methods on 5xx.
+            if response.status_code != 429 and not _is_idempotent(request.method):
+                return response
+
+            wait = _calc_backoff(attempt, response)
+            # Read and discard the body to free the connection.
+            response.read()
+            response.close()
+            time.sleep(wait)
+
+        # Unreachable — the loop always returns.
+        raise RuntimeError("vesselapi: retry loop exited unexpectedly")  # pragma: no cover
+
+    def close(self) -> None:
+        self._base.close()
+
+
+class AsyncRetryTransport(httpx.AsyncBaseTransport):
+    """Async transport with retry logic for 429, 5xx, and transient errors.
+
+    Same logic as RetryTransport but using asyncio.sleep for async contexts.
+    """
+
+    def __init__(self, base: httpx.AsyncBaseTransport, max_retries: int = 3) -> None:
+        self._base = base
+        self._max_retries = max(max_retries, 0)
+
+    async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = await self._base.handle_async_request(request)
+            except httpx.TransportError:
+                if attempt >= self._max_retries or not _is_idempotent(request.method):
+                    raise
+                await asyncio.sleep(_calc_exp_backoff(attempt))
+                continue
+
+            if not _is_retryable(response.status_code) or attempt >= self._max_retries:
+                return response
+
+            if response.status_code != 429 and not _is_idempotent(request.method):
+                return response
+
+            wait = _calc_backoff(attempt, response)
+            await response.aread()
+            await response.aclose()
+            await asyncio.sleep(wait)
+
+        raise RuntimeError("vesselapi: retry loop exited unexpectedly")  # pragma: no cover
+
+    async def aclose(self) -> None:
+        await self._base.aclose()
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+
+def _is_retryable(status_code: int) -> bool:
+    """Return True if the status code warrants a retry."""
+    return status_code == 429 or status_code >= 500
+
+
+def _is_idempotent(method: str) -> bool:
+    """Return True for HTTP methods that are safe to retry."""
+    return method.upper() in {"GET", "HEAD", "OPTIONS", "PUT", "DELETE"}
+
+
+def _calc_backoff(attempt: int, response: httpx.Response) -> float:
+    """Calculate retry wait time, respecting Retry-After header."""
+    retry_after = response.headers.get("Retry-After", "")
+    if retry_after:
+        # Try integer seconds first.
+        try:
+            seconds = int(retry_after)
+            return max(0.0, min(float(seconds), MAX_BACKOFF))
+        except ValueError:
+            pass
+        # Try HTTP-date format (RFC 7231 section 7.1.3).
+        try:
+            dt = parsedate_to_datetime(retry_after)
+            delta = (dt - _utcnow()).total_seconds()
+            return max(0.0, min(delta, MAX_BACKOFF))
+        except (ValueError, TypeError):
+            pass
+    return _calc_exp_backoff(attempt)
+
+
+def _calc_exp_backoff(attempt: int) -> float:
+    """Exponential backoff with jitter, capped at MAX_BACKOFF."""
+    base = math.pow(2, attempt)
+    jitter = random.random() * base  # noqa: S311
+    duration = (base + jitter) * 0.5
+    return min(duration, MAX_BACKOFF)
+
+
+def _utcnow() -> datetime.datetime:
+    """Return current UTC datetime. Extracted for test patching."""
+    return datetime.datetime.now(datetime.timezone.utc)

vessel_api_python-1.0.0.dist-info/METADATA

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: vessel-api-python
+Version: 1.0.0
+Summary: Python client for the Vessel Tracking API — maritime vessel tracking, port events, emissions, and navigation data.
+Project-URL: Documentation, https://vesselapi.com/docs
+Project-URL: Repository, https://github.com/vessel-api/vesselapi-python
+Project-URL: Issues, https://github.com/vessel-api/vesselapi-python/issues
+Project-URL: Changelog, https://github.com/vessel-api/vesselapi-python/releases
+Author-email: Vessel API <support@vesselapi.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ais,maritime,sdk,tracking,vessel,vesselapi
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: eval-type-backport>=0.2.0; python_version < '3.10'
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# vesselapi-python
+
+[![CI](https://github.com/vessel-api/vesselapi-python/actions/workflows/ci.yml/badge.svg)](https://github.com/vessel-api/vesselapi-python/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/vessel-api-python.svg)](https://pypi.org/project/vessel-api-python/)
+[![Python](https://img.shields.io/pypi/pyversions/vessel-api-python.svg)](https://pypi.org/project/vessel-api-python/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+Python client for the [Vessel Tracking API](https://vesselapi.com) — maritime vessel tracking, port events, emissions, and navigation data.
+
+**Resources**: [Documentation](https://vesselapi.com/docs) | [API Explorer](https://vesselapi.com/api-reference) | [Dashboard](https://dashboard.vesselapi.com) | [Contact Support](mailto:support@vesselapi.com)
+
+## Install
+
+```bash
+pip install vessel-api-python
+```
+
+Requires Python 3.9+.
+
+## Quick Start
+
+```python
+from vessel_api_python import VesselClient
+
+client = VesselClient(api_key="your-api-key")
+
+# Search for a vessel by name.
+result = client.search.vessels(filter_name="Ever Given")
+for v in result.vessels or []:
+    print(f"{v.name} (IMO {v.imo})")
+
+# Get a port by UN/LOCODE.
+port = client.ports.get("NLRTM")
+print(port.port.name)
+
+# Auto-paginate through port events.
+for event in client.port_events.list_all(pagination_limit=10):
+    print(f"{event.event} at {event.timestamp}")
+```
+
+### Async
+
+```python
+import asyncio
+from vessel_api_python import AsyncVesselClient
+
+async def main():
+    async with AsyncVesselClient(api_key="your-api-key") as client:
+        result = await client.search.vessels(filter_name="Ever Given")
+        async for event in client.port_events.list_all(pagination_limit=10):
+            print(f"{event.event} at {event.timestamp}")
+
+asyncio.run(main())
+```
+
+## Available Services
+
+| Service | Methods | Description |
+|---------|---------|-------------|
+| `vessels` | `get`, `position`, `casualties`, `classification`, `emissions`, `eta`, `inspections`, `inspection_detail`, `ownership`, `positions` | Vessel details, positions, and records |
+| `ports` | `get` | Port lookup by UN/LOCODE |
+| `port_events` | `list`, `by_port`, `by_ports`, `by_vessel`, `last_by_vessel`, `by_vessels` | Vessel arrival/departure events |
+| `emissions` | `list` | EU MRV emissions data |
+| `search` | `vessels`, `ports`, `dgps`, `light_aids`, `modus`, `radio_beacons` | Full-text search across entity types |
+| `location` | `vessels_bounding_box`, `vessels_radius`, `ports_bounding_box`, `ports_radius`, `dgps_bounding_box`, `dgps_radius`, `light_aids_bounding_box`, `light_aids_radius`, `modus_bounding_box`, `modus_radius`, `radio_beacons_bounding_box`, `radio_beacons_radius` | Geo queries by bounding box or radius |
+| `navtex` | `list` | NAVTEX maritime safety messages |
+
+**37 methods total.**
+
+## Error Handling
+
+All methods raise specific exception types on non-2xx responses:
+
+```python
+from vessel_api_python import VesselAPIError
+
+try:
+    client.ports.get("ZZZZZ")
+except VesselAPIError as err:
+    if err.is_not_found:
+        print("Port not found")
+    elif err.is_rate_limited:
+        print("Rate limited — back off")
+    elif err.is_auth_error:
+        print("Check API key")
+    print(err.status_code, err.message)
+```
+
+## Auto-Pagination
+
+Every list endpoint has an `all_*` / `list_all` variant returning an iterator:
+
+```python
+# Sync
+for vessel in client.search.all_vessels(filter_name="tanker"):
+    print(vessel.name)
+
+# Async
+async for vessel in client.search.all_vessels(filter_name="tanker"):
+    print(vessel.name)
+
+# Collect all at once
+vessels = client.search.all_vessels(filter_name="tanker").collect()
+```
+
+## Configuration
+
+```python
+client = VesselClient(
+    api_key="your-api-key",
+    base_url="https://custom-endpoint.example.com/v1",
+    timeout=60.0,
+    max_retries=5,  # default: 3
+    user_agent="my-app/1.0",
+)
+```
+
+Retries use exponential backoff with jitter on 429 and 5xx responses. The `Retry-After` header is respected.
+
+## Documentation
+
+- [API Documentation](https://vesselapi.com/docs) — endpoint guides, request/response schemas, and usage examples
+- [API Explorer](https://vesselapi.com/api-reference) — interactive API reference
+- [Dashboard](https://dashboard.vesselapi.com) — manage API keys and monitor usage
+
+## Contributing & Support
+
+Found a bug, have a feature request, or need help? You're welcome to [open an issue](https://github.com/vessel-api/vesselapi-python/issues). For API-level bugs and feature requests, please use the [main VesselAPI repository](https://github.com/vessel-api/VesselApi/issues).
+
+For security vulnerabilities, **do not** open a public issue — email security@vesselapi.com instead. See [SECURITY.md](SECURITY.md).
+
+## License
+
+[MIT](LICENSE)

vessel_api_python-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+vessel_api_python/__init__.py,sha256=K4ob0XECb6ur-lKl_h0YAJQAhQ9HO1JSTv9fCshj9gQ,4505
+vessel_api_python/_client.py,sha256=39yKlQ4W2TnE85sTtK7KlBzFF385Pl52I5ghyq575EA,5067
+vessel_api_python/_constants.py,sha256=wQeOziPys14EdD21f2vBgM8BKrO3WeHIUeOTQAG3BAI,244
+vessel_api_python/_errors.py,sha256=pxDm36mbrviOoDRmJ-ogtlUIsyu-dHpC0jcs5f34WDU,4310
+vessel_api_python/_iterator.py,sha256=SkgsGSdxLrKtw-ad8fSUPaEDDJCamAKK0PrG_P8HX-4,3198
+vessel_api_python/_models.py,sha256=g1c--6UUhtfDSfTv4G6wDmYxGdURN8KASNNAXXQvibE,29124
+vessel_api_python/_services.py,sha256=-3FFJo3C_5fXZDnPc8gcgXQ472BC1hScaQWIOX6qQiU,73801
+vessel_api_python/_transport.py,sha256=_4s-65JMRwD2S435u0iuoLGH_GyLNaX8cP_uSh_u80I,6692
+vessel_api_python/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vessel_api_python-1.0.0.dist-info/METADATA,sha256=Pc35iFq8GJ5FywrNWOJKGwcQ2VS8Miv7L8ubW3T3P0s,6309
+vessel_api_python-1.0.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+vessel_api_python-1.0.0.dist-info/licenses/LICENSE,sha256=zoj_abq99mj8cz-Bz71XCnwB-Qv3kU1VzVXeKEntuQU,1067
+vessel_api_python-1.0.0.dist-info/RECORD,,

vessel_api_python-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

vessel_api_python-1.0.0.dist-info/licenses/LICENSE

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