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

vessel_api_python/__init__.py

@@ -0,0 +1,183 @@
+"""Vessel Tracking API Python SDK.
+
+Usage::
+
+    from vessel_api_python import VesselClient
+
+    client = VesselClient(api_key="your-api-key")
+    result = client.search.vessels(filter_name="Ever Given")
+"""
+
+from ._client import AsyncVesselClient, VesselClient
+from ._constants import DEFAULT_BASE_URL, VERSION
+from ._errors import (
+    VesselAPIError,
+    VesselAuthError,
+    VesselNotFoundError,
+    VesselRateLimitError,
+    VesselServerError,
+)
+from ._iterator import AsyncIterator, SyncIterator
+from ._models import (
+    MODU,
+    BroadcastStation,
+    Classification,
+    ClassificationCertificate,
+    ClassificationCondition,
+    ClassificationDimensions,
+    ClassificationHull,
+    ClassificationIdentification,
+    ClassificationInfo,
+    ClassificationMachinery,
+    ClassificationOwner,
+    ClassificationPurpose,
+    ClassificationResponse,
+    ClassificationSurvey,
+    ClassificationVessel,
+    ClassificationYard,
+    DGPSStation,
+    DGPSStationsWithinLocationResponse,
+    FindDGPSStationsResponse,
+    FindLightAidsResponse,
+    FindMODUsResponse,
+    FindPortsResponse,
+    FindRadioBeaconsResponse,
+    FindVesselsResponse,
+    GeoJSON,
+    Inspection,
+    InspectionDeficiency,
+    InspectionDetail,
+    InspectionDetailRecord,
+    InspectionDetailResponseData,
+    InspectionRecord,
+    InspectionsResponseData,
+    LightAid,
+    LightAidsWithinLocationResponse,
+    MarineCasualtiesResponse,
+    MarineCasualty,
+    MODUsWithinLocationResponse,
+    Navtex,
+    NavtexMessagesResponse,
+    Ownership,
+    OwnershipResponseData,
+    Port,
+    PortCountry,
+    PortEvent,
+    PortEventResponse,
+    PortEventsResponse,
+    PortReference,
+    PortResponse,
+    PortsWithinLocationResponse,
+    RadioBeacon,
+    RadioBeaconsWithinLocationResponse,
+    TypesInspectionDetailResponse,
+    TypesInspectionsResponse,
+    TypesOwnershipResponse,
+    Vessel,
+    VesselEmission,
+    VesselEmissionsResponse,
+    VesselETA,
+    VesselETAResponse,
+    VesselFormerName,
+    VesselOwnership,
+    VesselPosition,
+    VesselPositionResponse,
+    VesselPositionsResponse,
+    VesselReference,
+    VesselResponse,
+    VesselsWithinLocationResponse,
+)
+
+__all__ = [
+    # Clients
+    "VesselClient",
+    "AsyncVesselClient",
+    # Errors
+    "VesselAPIError",
+    "VesselAuthError",
+    "VesselNotFoundError",
+    "VesselRateLimitError",
+    "VesselServerError",
+    # Iterators
+    "SyncIterator",
+    "AsyncIterator",
+    # Constants
+    "VERSION",
+    "DEFAULT_BASE_URL",
+    # Models — Shared / helper
+    "GeoJSON",
+    "PortCountry",
+    "PortReference",
+    "VesselReference",
+    "VesselFormerName",
+    "BroadcastStation",
+    # Models — Classification sub-models
+    "ClassificationCertificate",
+    "ClassificationCondition",
+    "ClassificationDimensions",
+    "ClassificationHull",
+    "ClassificationIdentification",
+    "ClassificationInfo",
+    "ClassificationMachinery",
+    "ClassificationOwner",
+    "ClassificationPurpose",
+    "ClassificationSurvey",
+    "ClassificationVessel",
+    "ClassificationYard",
+    # Models — Vessel
+    "Vessel",
+    "VesselResponse",
+    "VesselPosition",
+    "VesselPositionResponse",
+    "VesselPositionsResponse",
+    "MarineCasualty",
+    "MarineCasualtiesResponse",
+    "Classification",
+    "ClassificationResponse",
+    "VesselEmission",
+    "VesselEmissionsResponse",
+    "VesselETA",
+    "VesselETAResponse",
+    # Models — Inspection
+    "InspectionRecord",
+    "Inspection",
+    "InspectionDeficiency",
+    "InspectionDetailRecord",
+    "InspectionDetail",
+    "InspectionsResponseData",
+    "InspectionDetailResponseData",
+    "TypesInspectionsResponse",
+    "TypesInspectionDetailResponse",
+    # Models — Ownership
+    "VesselOwnership",
+    "Ownership",
+    "OwnershipResponseData",
+    "TypesOwnershipResponse",
+    # Models — Port
+    "Port",
+    "PortResponse",
+    "PortEvent",
+    "PortEventResponse",
+    "PortEventsResponse",
+    # Models — Search
+    "FindVesselsResponse",
+    "FindPortsResponse",
+    "DGPSStation",
+    "FindDGPSStationsResponse",
+    "LightAid",
+    "FindLightAidsResponse",
+    "MODU",
+    "FindMODUsResponse",
+    "RadioBeacon",
+    "FindRadioBeaconsResponse",
+    # Models — Location
+    "VesselsWithinLocationResponse",
+    "PortsWithinLocationResponse",
+    "DGPSStationsWithinLocationResponse",
+    "LightAidsWithinLocationResponse",
+    "MODUsWithinLocationResponse",
+    "RadioBeaconsWithinLocationResponse",
+    # Models — Navtex
+    "Navtex",
+    "NavtexMessagesResponse",
+]

vessel_api_python/_client.py

@@ -0,0 +1,163 @@
+"""High-level Vessel API clients (sync and async).
+
+Usage::
+
+    # Sync
+    client = VesselClient(api_key="your-api-key")
+    vessel = client.vessels.get("9363728")
+
+    # Async
+    async with AsyncVesselClient(api_key="your-api-key") as client:
+        vessel = await client.vessels.get("9363728")
+"""
+
+from __future__ import annotations
+
+import httpx
+
+from ._constants import (
+    DEFAULT_BASE_URL,
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_TIMEOUT,
+    DEFAULT_USER_AGENT,
+)
+from ._services import (
+    AsyncEmissionsService,
+    AsyncLocationService,
+    AsyncNavtexService,
+    AsyncPortEventsService,
+    AsyncPortsService,
+    AsyncSearchService,
+    AsyncVesselsService,
+    EmissionsService,
+    LocationService,
+    NavtexService,
+    PortEventsService,
+    PortsService,
+    SearchService,
+    VesselsService,
+)
+from ._transport import (
+    AsyncAuthTransport,
+    AsyncRetryTransport,
+    AuthTransport,
+    RetryTransport,
+)
+
+
+class VesselClient:
+    """Synchronous client for the Vessel Tracking API.
+
+    Args:
+        api_key: Bearer token for authentication. Required, must not be empty.
+        base_url: API base URL. Defaults to ``https://api.vesselapi.com/v1``.
+        timeout: Request timeout in seconds. Defaults to 30.
+        max_retries: Maximum retries on 429/5xx. Defaults to 3.
+        user_agent: User-Agent header value.
+        transport: Custom base ``httpx.BaseTransport`` (auth + retry wrap on top).
+
+    Raises:
+        ValueError: If ``api_key`` is empty.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        user_agent: str = DEFAULT_USER_AGENT,
+        transport: httpx.BaseTransport | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("vesselapi: api_key must not be empty")
+        if max_retries < 0:
+            max_retries = 0
+
+        base_transport = transport or httpx.HTTPTransport()
+        auth_transport = AuthTransport(base_transport, api_key, user_agent)
+        retry_transport = RetryTransport(auth_transport, max_retries)
+
+        self._client = httpx.Client(
+            base_url=base_url,
+            timeout=timeout,
+            transport=retry_transport,
+        )
+
+        self.vessels = VesselsService(self._client)
+        self.ports = PortsService(self._client)
+        self.port_events = PortEventsService(self._client)
+        self.emissions = EmissionsService(self._client)
+        self.search = SearchService(self._client)
+        self.location = LocationService(self._client)
+        self.navtex = NavtexService(self._client)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client and release resources."""
+        self._client.close()
+
+    def __enter__(self) -> VesselClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+
+class AsyncVesselClient:
+    """Asynchronous client for the Vessel Tracking API.
+
+    Args:
+        api_key: Bearer token for authentication. Required, must not be empty.
+        base_url: API base URL. Defaults to ``https://api.vesselapi.com/v1``.
+        timeout: Request timeout in seconds. Defaults to 30.
+        max_retries: Maximum retries on 429/5xx. Defaults to 3.
+        user_agent: User-Agent header value.
+        transport: Custom base ``httpx.AsyncBaseTransport`` (auth + retry wrap on top).
+
+    Raises:
+        ValueError: If ``api_key`` is empty.
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        user_agent: str = DEFAULT_USER_AGENT,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("vesselapi: api_key must not be empty")
+        if max_retries < 0:
+            max_retries = 0
+
+        base_transport = transport or httpx.AsyncHTTPTransport()
+        auth_transport = AsyncAuthTransport(base_transport, api_key, user_agent)
+        retry_transport = AsyncRetryTransport(auth_transport, max_retries)
+
+        self._client = httpx.AsyncClient(
+            base_url=base_url,
+            timeout=timeout,
+            transport=retry_transport,
+        )
+
+        self.vessels = AsyncVesselsService(self._client)
+        self.ports = AsyncPortsService(self._client)
+        self.port_events = AsyncPortEventsService(self._client)
+        self.emissions = AsyncEmissionsService(self._client)
+        self.search = AsyncSearchService(self._client)
+        self.location = AsyncLocationService(self._client)
+        self.navtex = AsyncNavtexService(self._client)
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client and release resources."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> AsyncVesselClient:
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.aclose()

vessel_api_python/_constants.py

@@ -0,0 +1,8 @@
+"""Constants for the Vessel API Python SDK."""
+
+VERSION = "1.0.0"
+DEFAULT_BASE_URL = "https://api.vesselapi.com/v1"
+DEFAULT_USER_AGENT = f"vesselapi-python/{VERSION}"
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_TIMEOUT = 30.0
+MAX_BACKOFF = 30.0  # seconds

vessel_api_python/_errors.py

@@ -0,0 +1,137 @@
+"""Error types for the Vessel API Python SDK."""
+
+from __future__ import annotations
+
+import http
+import json
+
+
+class VesselAPIError(Exception):
+    """Base error for all Vessel API errors.
+
+    Attributes:
+        status_code: The HTTP status code from the response.
+        message: A human-readable error message.
+        body: The raw response body bytes, available for re-parsing.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        message: str,
+        body: bytes = b"",
+    ) -> None:
+        self.status_code = status_code
+        self.message = message
+        self.body = body
+        super().__init__(f"vesselapi: {message} (status {status_code})")
+
+    @property
+    def is_not_found(self) -> bool:
+        """True if the error is a 404 Not Found response."""
+        return self.status_code == 404
+
+    @property
+    def is_rate_limited(self) -> bool:
+        """True if the error is a 429 Too Many Requests response."""
+        return self.status_code == 429
+
+    @property
+    def is_auth_error(self) -> bool:
+        """True if the error is a 401 Unauthorized response."""
+        return self.status_code == 401
+
+
+class VesselAuthError(VesselAPIError):
+    """Raised on 401 Unauthorized responses."""
+
+
+class VesselNotFoundError(VesselAPIError):
+    """Raised on 404 Not Found responses."""
+
+
+class VesselRateLimitError(VesselAPIError):
+    """Raised on 429 Too Many Requests responses."""
+
+
+class VesselServerError(VesselAPIError):
+    """Raised on 5xx server error responses."""
+
+
+def error_from_response(
+    status_code: int,
+    body: bytes,
+    headers: dict[str, str] | None = None,
+) -> None:
+    """Raise a VesselAPIError if the response indicates an error.
+
+    Checks for success using ``200 <= status_code < 300``. On error,
+    attempts to parse a human-readable message from the JSON body using
+    multiple known shapes, falling back to the HTTP status text.
+
+    Args:
+        status_code: The HTTP response status code.
+        body: The raw response body bytes.
+        headers: Optional response headers (unused currently, reserved).
+
+    Raises:
+        VesselAuthError: On 401 responses.
+        VesselNotFoundError: On 404 responses.
+        VesselRateLimitError: On 429 responses.
+        VesselServerError: On 5xx responses.
+        VesselAPIError: On all other non-2xx responses.
+    """
+    if 200 <= status_code < 300:
+        return
+
+    # Try to extract a human-readable message from the response body.
+    msg = _status_text(status_code)
+    if body:
+        try:
+            data = json.loads(body)
+            # Try {"error": {"message": "..."}} (Vessel API standard shape).
+            nested_msg = _get_nested(data, "error", "message")
+            if nested_msg:
+                msg = nested_msg
+            else:
+                # Try {"message": "..."} (common alternative shape).
+                flat_msg = data.get("message") if isinstance(data, dict) else None
+                if flat_msg and isinstance(flat_msg, str):
+                    msg = flat_msg
+            # If both fail, msg stays as HTTP status text.
+            # Raw body is always available in VesselAPIError.body.
+        except (json.JSONDecodeError, TypeError, AttributeError):
+            pass
+
+    # Return the appropriate subclass based on status code.
+    error_cls: type[VesselAPIError]
+    if status_code == 401:
+        error_cls = VesselAuthError
+    elif status_code == 404:
+        error_cls = VesselNotFoundError
+    elif status_code == 429:
+        error_cls = VesselRateLimitError
+    elif status_code >= 500:
+        error_cls = VesselServerError
+    else:
+        error_cls = VesselAPIError
+
+    raise error_cls(status_code=status_code, message=msg, body=body)
+
+
+def _get_nested(data: dict[str, object] | list[object] | None, *keys: str) -> str | None:
+    """Safely traverse nested dicts to extract a string value."""
+    current: object = data
+    for key in keys:
+        if not isinstance(current, dict):
+            return None
+        current = current.get(key)
+    return current if isinstance(current, str) else None
+
+
+def _status_text(status_code: int) -> str:
+    """Return the HTTP status text for a given code."""
+    try:
+        return http.HTTPStatus(status_code).phrase
+    except ValueError:
+        return f"HTTP {status_code}"

vessel_api_python/_iterator.py

@@ -0,0 +1,120 @@
+"""Pagination iterators for the Vessel API Python SDK."""
+
+from __future__ import annotations
+
+from typing import Callable, Generic, Optional, TypeVar
+
+T = TypeVar("T")
+
+# A fetch function returns (items, next_token_or_None).
+FetchFunc = Callable[[], tuple[list[T], Optional[str]]]
+
+
+class SyncIterator(Generic[T]):
+    """Lazy, sequential iterator over paginated API results (sync).
+
+    Implements the ``__iter__``/``__next__`` protocol so it can be used
+    directly in ``for`` loops.
+
+    Example::
+
+        for vessel in client.search.all_vessels(filter_name="tanker"):
+            print(vessel.name)
+    """
+
+    def __init__(self, fetch: FetchFunc[T]) -> None:
+        self._fetch = fetch
+        self._items: list[T] = []
+        self._index = 0
+        self._done = False
+        self._started = False
+
+    def __iter__(self) -> SyncIterator[T]:
+        return self
+
+    def __next__(self) -> T:
+        # Advance index if we've already yielded at least one item.
+        if self._started:
+            self._index += 1
+        self._started = True
+
+        # Return buffered item if available.
+        if self._index < len(self._items):
+            return self._items[self._index]
+
+        # No more pages.
+        if self._done:
+            raise StopIteration
+
+        # Fetch next page.
+        items, next_token = self._fetch()
+        self._items = items
+        self._index = 0
+
+        if not items:
+            self._done = True
+            raise StopIteration
+
+        if not next_token:
+            self._done = True
+
+        return self._items[self._index]
+
+    def collect(self) -> list[T]:
+        """Consume the iterator and return all remaining items as a list."""
+        return list(self)
+
+
+class AsyncIterator(Generic[T]):
+    """Lazy, sequential iterator over paginated API results (async).
+
+    Implements the ``__aiter__``/``__anext__`` protocol for use in
+    ``async for`` loops.
+
+    Example::
+
+        async for vessel in client.search.all_vessels(filter_name="tanker"):
+            print(vessel.name)
+    """
+
+    def __init__(self, fetch: Callable[[], object]) -> None:
+        # fetch is an async callable returning (items, next_token).
+        self._fetch = fetch
+        self._items: list[T] = []
+        self._index = 0
+        self._done = False
+        self._started = False
+
+    def __aiter__(self) -> AsyncIterator[T]:
+        return self
+
+    async def __anext__(self) -> T:
+        if self._started:
+            self._index += 1
+        self._started = True
+
+        if self._index < len(self._items):
+            return self._items[self._index]
+
+        if self._done:
+            raise StopAsyncIteration
+
+        items, next_token = await self._fetch()  # type: ignore[misc]
+        self._items = items
+        self._index = 0
+
+        if not items:
+            self._done = True
+            raise StopAsyncIteration
+
+        if not next_token:
+            self._done = True
+
+        return self._items[self._index]
+
+    async def collect(self) -> list[T]:
+        """Consume the iterator and return all remaining items as a list."""
+        result: list[T] = []
+        async for item in self:
+            result.append(item)
+        return result