vessel-api-python 1.3.0__py3-none-any.whl → 2.0.0__py3-none-any.whl

vessel_api_python/__init__.py

@@ -13,28 +13,15 @@ from ._constants import DEFAULT_BASE_URL, VERSION
 from ._errors import (
     VesselAPIError,
     VesselAuthError,
+    VesselForbiddenError,
     VesselNotFoundError,
+    VesselPaymentRequiredError,
     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,
@@ -44,22 +31,11 @@ from ._models import (
     FindRadioBeaconsResponse,
     FindVesselsResponse,
     GeoJSON,
-    Inspection,
-    InspectionDeficiency,
-    InspectionDetail,
-    InspectionDetailRecord,
-    InspectionDetailResponseData,
-    InspectionRecord,
-    InspectionsResponseData,
     LightAid,
     LightAidsWithinLocationResponse,
     MarineCasualtiesResponse,
     MarineCasualty,
     MODUsWithinLocationResponse,
-    Navtex,
-    NavtexMessagesResponse,
-    Ownership,
-    OwnershipResponseData,
     Port,
     PortCountry,
     PortEvent,
@@ -72,23 +48,21 @@ from ._models import (
     RadioBeacon,
     RadioBeaconsWithinLocationResponse,
     ResolutionMeta,
-    TypesInspectionDetailResponse,
-    TypesInspectionsResponse,
-    TypesOwnershipResponse,
     Vessel,
     VesselEmission,
     VesselEmissionsResponse,
     VesselETA,
     VesselETAResponse,
     VesselFormerName,
-    VesselOwnership,
     VesselPosition,
     VesselPositionResponse,
     VesselPositionsResponse,
     VesselReference,
     VesselResponse,
+    VesselSearchMeta,
     VesselsWithinLocationResponse,
 )
+from ._services import MultiFilter
 
 __all__ = [
     # Clients
@@ -97,7 +71,9 @@ __all__ = [
     # Errors
     "VesselAPIError",
     "VesselAuthError",
+    "VesselForbiddenError",
     "VesselNotFoundError",
+    "VesselPaymentRequiredError",
     "VesselRateLimitError",
     "VesselServerError",
     # Iterators
@@ -106,27 +82,15 @@ __all__ = [
     # Constants
     "VERSION",
     "DEFAULT_BASE_URL",
+    # Typing helpers
+    "MultiFilter",
     # Models — Shared / helper
     "GeoJSON",
     "PortCountry",
     "PortReference",
     "VesselReference",
     "VesselFormerName",
-    "BroadcastStation",
     "ResolutionMeta",
-    # Models — Classification sub-models
-    "ClassificationCertificate",
-    "ClassificationCondition",
-    "ClassificationDimensions",
-    "ClassificationHull",
-    "ClassificationIdentification",
-    "ClassificationInfo",
-    "ClassificationMachinery",
-    "ClassificationOwner",
-    "ClassificationPurpose",
-    "ClassificationSurvey",
-    "ClassificationVessel",
-    "ClassificationYard",
     # Models — Vessel
     "Vessel",
     "VesselResponse",
@@ -135,27 +99,10 @@ __all__ = [
     "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",
@@ -164,6 +111,7 @@ __all__ = [
     "PortEventsResponse",
     "PortInboundResponse",
     # Models — Search
+    "VesselSearchMeta",
     "FindVesselsResponse",
     "FindPortsResponse",
     "DGPSStation",
@@ -181,7 +129,4 @@ __all__ = [
     "LightAidsWithinLocationResponse",
     "MODUsWithinLocationResponse",
     "RadioBeaconsWithinLocationResponse",
-    # Models — Navtex
-    "Navtex",
-    "NavtexMessagesResponse",
 ]

vessel_api_python/_client.py

@@ -24,14 +24,12 @@ from ._constants import (
 from ._services import (
     AsyncEmissionsService,
     AsyncLocationService,
-    AsyncNavtexService,
     AsyncPortEventsService,
     AsyncPortsService,
     AsyncSearchService,
     AsyncVesselsService,
     EmissionsService,
     LocationService,
-    NavtexService,
     PortEventsService,
     PortsService,
     SearchService,
@@ -91,7 +89,6 @@ class VesselClient:
         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."""
@@ -150,7 +147,6 @@ class AsyncVesselClient:
         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."""

vessel_api_python/_constants.py

@@ -1,6 +1,6 @@
 """Constants for the Vessel API Python SDK."""
 
-VERSION = "1.1.0"
+VERSION = "2.0.0"
 DEFAULT_BASE_URL = "https://api.vesselapi.com/v1"
 DEFAULT_USER_AGENT = f"vesselapi-python/{VERSION}"
 DEFAULT_MAX_RETRIES = 3

vessel_api_python/_errors.py

@@ -13,6 +13,10 @@ class VesselAPIError(Exception):
         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.
+        code: The API's machine-readable error code (e.g. ``insufficient_credits``,
+            ``feature_not_available``), or None if the response carried none.
+            Branch on this rather than on ``message``, which may be reworded.
+        error_type: The API's error type (e.g. ``payment_required_error``), or None.
     """
 
     def __init__(
@@ -20,10 +24,14 @@ class VesselAPIError(Exception):
         status_code: int,
         message: str,
         body: bytes = b"",
+        code: str | None = None,
+        error_type: str | None = None,
     ) -> None:
         self.status_code = status_code
         self.message = message
         self.body = body
+        self.code = code
+        self.error_type = error_type
         super().__init__(f"vesselapi: {message} (status {status_code})")
 
     @property
@@ -41,11 +49,39 @@ class VesselAPIError(Exception):
         """True if the error is a 401 Unauthorized response."""
         return self.status_code == 401
 
+    @property
+    def is_payment_required(self) -> bool:
+        """True if the error is a 402 Payment Required response.
+
+        Returned when a satellite-backed call is made with no satellite credits
+        left. Retry without ``filter_sat`` to serve stored data instead, or top
+        up the balance.
+        """
+        return self.status_code == 402
+
+    @property
+    def is_forbidden(self) -> bool:
+        """True if the error is a 403 Forbidden response.
+
+        Distinct from 401: the key is valid but not permitted. Check ``code`` to
+        tell a temporarily suspended key from a feature that is not on the
+        caller's plan.
+        """
+        return self.status_code == 403
+
 
 class VesselAuthError(VesselAPIError):
     """Raised on 401 Unauthorized responses."""
 
 
+class VesselPaymentRequiredError(VesselAPIError):
+    """Raised on 402 Payment Required responses (satellite credits exhausted)."""
+
+
+class VesselForbiddenError(VesselAPIError):
+    """Raised on 403 Forbidden responses (key suspended, or feature not on plan)."""
+
+
 class VesselNotFoundError(VesselAPIError):
     """Raised on 404 Not Found responses."""
 
@@ -76,6 +112,8 @@ def error_from_response(
 
     Raises:
         VesselAuthError: On 401 responses.
+        VesselPaymentRequiredError: On 402 responses (satellite credits exhausted).
+        VesselForbiddenError: On 403 responses (suspended key, or feature not on plan).
         VesselNotFoundError: On 404 responses.
         VesselRateLimitError: On 429 responses.
         VesselServerError: On 5xx responses.
@@ -86,6 +124,8 @@ def error_from_response(
 
     # Try to extract a human-readable message from the response body.
     msg = _status_text(status_code)
+    code: str | None = None
+    error_type: str | None = None
     if body:
         try:
             data = json.loads(body)
@@ -98,6 +138,10 @@ def error_from_response(
                 flat_msg = data.get("message") if isinstance(data, dict) else None
                 if flat_msg and isinstance(flat_msg, str):
                     msg = flat_msg
+            # The API also sends machine-readable discriminators. Expose them:
+            # branching on `message` breaks whenever the wording changes.
+            code = _get_nested(data, "error", "code")
+            error_type = _get_nested(data, "error", "type")
             # If both fail, msg stays as HTTP status text.
             # Raw body is always available in VesselAPIError.body.
         except (json.JSONDecodeError, TypeError, AttributeError):
@@ -107,6 +151,10 @@ def error_from_response(
     error_cls: type[VesselAPIError]
     if status_code == 401:
         error_cls = VesselAuthError
+    elif status_code == 402:
+        error_cls = VesselPaymentRequiredError
+    elif status_code == 403:
+        error_cls = VesselForbiddenError
     elif status_code == 404:
         error_cls = VesselNotFoundError
     elif status_code == 429:
@@ -116,7 +164,7 @@ def error_from_response(
     else:
         error_cls = VesselAPIError
 
-    raise error_cls(status_code=status_code, message=msg, body=body)
+    raise error_cls(status_code=status_code, message=msg, body=body, code=code, error_type=error_type)
 
 
 def _get_nested(data: dict[str, object] | list[object] | None, *keys: str) -> str | None: