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

vessel_api_python/_transport.py

@@ -164,8 +164,11 @@ def _calc_backoff(attempt: int, response: httpx.Response) -> float:
             pass
         # Try HTTP-date format (RFC 7231 section 7.1.3).
         try:
-            dt = parsedate_to_datetime(retry_after)
-            delta = (dt - _utcnow()).total_seconds()
+            # Annotated because typeshed types parsedate_to_datetime as Any on
+            # Python 3.9, which propagates through the subtraction and makes the
+            # return Any. Without this, mypy passes on 3.12 and fails on 3.9.
+            dt: datetime.datetime = parsedate_to_datetime(retry_after)
+            delta: float = (dt - _utcnow()).total_seconds()
             return max(0.0, min(delta, MAX_BACKOFF))
         except (ValueError, TypeError):
             pass

{vessel_api_python-1.3.0.dist-info → vessel_api_python-2.0.0.dist-info}/METADATA

@@ -1,7 +1,7 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: vessel-api-python
-Version: 1.3.0
-Summary: Python client for the Vessel Tracking API — maritime vessel tracking, port events, emissions, and navigation data.
+Version: 2.0.0
+Summary: Python client for the Vessel Tracking API: maritime vessel tracking, port events, emissions, and nautical infrastructure.
 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
@@ -39,7 +39,7 @@ Description-Content-Type: text/markdown
 [![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.
+Python client for the [Vessel Tracking API](https://vesselapi.com): maritime vessel tracking, port events, emissions, and nautical infrastructure.
 
 **Resources**: [Documentation](https://vesselapi.com/docs) | [API Explorer](https://vesselapi.com/api-reference) | [Dashboard](https://dashboard.vesselapi.com) | [Contact Support](mailto:support@vesselapi.com)
 
@@ -91,15 +91,33 @@ asyncio.run(main())
 
 | 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 |
+| `vessels` | `get`, `position`, `casualties`, `emissions`, `eta`, `positions` | Vessel details, positions, and records |
+| `ports` | `get`, `inbound`, `inbound_all` | Port lookup by UN/LOCODE and inbound vessels |
 | `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.**
+**33 methods total**, one per API endpoint, plus 28 auto-pagination iterators.
+
+## Required Parameters
+
+Parameters the API requires are keyword-only with no default, so leaving one out
+raises `TypeError` at the call instead of returning HTTP 400 from the server:
+
+```python
+client.location.vessels_radius(latitude=51.9225, longitude=4.47917, radius=10000)
+client.location.vessels_radius(latitude=51.9225)  # TypeError: missing longitude, radius
+```
+
+This covers the geo bounds on every `location` method (`lat_min`, `lat_max`,
+`lon_min`, `lon_max` for bounding boxes; `latitude`, `longitude`, `radius` for
+radius queries), `filter_name` on `search.dgps`, `search.light_aids`,
+`search.modus` and `search.radio_beacons`, `filter_port_name` on
+`port_events.by_ports`, `filter_vessel_name` on `port_events.by_vessels`, and
+`filter_ids` on `vessels.positions`, along with the matching `all_*` iterators.
+`filter_id_type` is required by the API but keeps its `"imo"` default, since the
+SDK always sends it.
 
 ## Vessel Lookup & Location
 
@@ -108,16 +126,47 @@ asyncio.run(main())
 vessel = client.vessels.get("9811000")
 print(f"{vessel.vessel.name} ({vessel.vessel.vessel_type})")
 
-# Get the vessel's latest AIS position.
-pos = client.vessels.position("9811000")
+# Get a vessel's latest stored AIS position. A vessel that exists may have no
+# stored position, which raises VesselNotFoundError rather than returning empty.
+pos = client.vessels.position("232003239", filter_id_type="mmsi")
 print(f"Position: {pos.vessel_position.latitude}, {pos.vessel_position.longitude}")
 
+# filter_sat=True falls back to satellite AIS when nothing is stored.
+# ⚠️ Satellite lookups draw on a prepaid balance and are charged per call.
+# Omit it unless you need that fallback.
+
 # Find all vessels within 10 km of Rotterdam.
 nearby = client.location.vessels_radius(latitude=51.9225, longitude=4.47917, radius=10000)
 for v in nearby.vessels or []:
     print(f"{v.vessel_name} at {v.latitude}, {v.longitude}")
 ```
 
+## Search
+
+`search.vessels` accepts `q`, a unified search across IMO, MMSI, ENI, callsign and
+name. One value can return several vessels, and `_meta.matched_on` maps each result's
+index to the fields it matched on.
+
+```python
+res = client.search.vessels(q="4606770")
+print(res.meta.matched_on)  # {"0": ["eni"]}
+```
+
+Filters the API declares as repeatable take either one value or a list. A list is
+sent as a repeated query parameter, so the values are OR-ed:
+
+```python
+# ?filter.flag=PA&filter.flag=LR&filter.vesselType=Container%20Ship
+client.search.vessels(filter_flag=["PA", "LR"], filter_vessel_type="Container Ship")
+
+client.search.ports(filter_country=["NL", "BE"], filter_size=["LARGE", "MEDIUM"])
+```
+
+These are `filter_flag` and `filter_vessel_type` on `search.vessels`;
+`filter_country`, `filter_port_type`, `filter_size`, `filter_harbor_size` and
+`filter_harbor_use` on `search.ports`; and `filter_ids` on `vessels.positions`,
+which also accepts the comma-separated single-string form.
+
 ## Error Handling
 
 All methods raise specific exception types on non-2xx responses:
@@ -131,7 +180,7 @@ except VesselAPIError as err:
     if err.is_not_found:
         print("Port not found")
     elif err.is_rate_limited:
-        print("Rate limited — back off")
+        print("Rate limited, backing off")
     elif err.is_auth_error:
         print("Check API key")
     print(err.status_code, err.message)
@@ -150,8 +199,14 @@ for vessel in client.search.all_vessels(filter_vessel_type="Tanker"):
 async for vessel in client.search.all_vessels(filter_vessel_type="Tanker"):
     print(vessel.name)
 
-# Collect a bounded set at once
+# Collect every match at once. pagination_limit is the page size, not a total:
+# .collect() walks to the end, so this is one request per page until exhausted.
 vessels = client.search.all_vessels(filter_vessel_type="Tanker", pagination_limit=50).collect()
+
+# To take a fixed number, stop the iterator yourself.
+from itertools import islice
+
+first_50 = list(islice(client.search.all_vessels(filter_vessel_type="Tanker"), 50))
 ```
 
 ## Configuration
@@ -170,15 +225,24 @@ Retries use exponential backoff with jitter on 429 and 5xx responses. The `Retry
 
 ## 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
+- [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).
+For security vulnerabilities, **do not** open a public issue. Email security@vesselapi.com instead. See [SECURITY.md](SECURITY.md).
+
+## Data Sources & Attribution
+
+Emissions and casualty data: © European Union. Source: European Maritime Safety Agency
+(EMSA): THETIS-MRV (EU MRV, Regulation (EU) 2015/757) and the European Marine Casualty
+Information Platform (EMCIP). Reused under the European Commission reuse notice
+(Commission Decision 2011/833/EU), which authorises reuse for commercial and
+non-commercial purposes with acknowledgement of the source. Data may be transformed and
+combined; EMSA does not endorse this service.
 
 ## License
 

vessel_api_python-2.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+vessel_api_python/__init__.py,sha256=-c0Rq1t5pDN4OY1w_9uNNeHjUI__kovOiyWvvU319jo,3114
+vessel_api_python/_client.py,sha256=L7qkzUiATDpPlxWViEKicNpNx7D90gCohas56uCimgA,4919
+vessel_api_python/_constants.py,sha256=Im6d9J9HSo5D-Rt4SVIQ35lqqGXIovSxhGsBhNqTVdU,244
+vessel_api_python/_errors.py,sha256=DaiyCjYKJZTo6-6sOqAcJBdOeFaIYgWHE48nsHWGeGA,6414
+vessel_api_python/_iterator.py,sha256=SkgsGSdxLrKtw-ad8fSUPaEDDJCamAKK0PrG_P8HX-4,3198
+vessel_api_python/_models.py,sha256=rJnRaZZ9y-h3xYbn0e-7nRLm6Sr9bSkigLIC6jY_HW0,19739
+vessel_api_python/_services.py,sha256=8f6yxKHvzDuIbrQCpN01wT_g4OsByWGHOIhKgDGeaQg,108285
+vessel_api_python/_transport.py,sha256=pfRaJwkq_GYpA5Ev8wH7tBdlzN2ykgy29Ag1L3F5K4Y,6956
+vessel_api_python/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+vessel_api_python-2.0.0.dist-info/METADATA,sha256=1HWjKevhtZDfUq9F1k4DNZoGZvtfaWnzsJw5dnPOVA0,10048
+vessel_api_python-2.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+vessel_api_python-2.0.0.dist-info/licenses/LICENSE,sha256=zoj_abq99mj8cz-Bz71XCnwB-Qv3kU1VzVXeKEntuQU,1067
+vessel_api_python-2.0.0.dist-info/RECORD,,

{vessel_api_python-1.3.0.dist-info → vessel_api_python-2.0.0.dist-info}/WHEEL

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

vessel_api_python-1.3.0.dist-info/RECORD

@@ -1,13 +0,0 @@
-vessel_api_python/__init__.py,sha256=kmYpzbtVfaMHRXUBoom7JqZa5hCif3vGL8y-q5n4DrA,4599
-vessel_api_python/_client.py,sha256=39yKlQ4W2TnE85sTtK7KlBzFF385Pl52I5ghyq575EA,5067
-vessel_api_python/_constants.py,sha256=Cp_uNnK0RljiWlyPmkMrVFoQtF5GpXTggSCD1SPvcyk,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=eawnhctWmvGK505EJzDyszTqXpI5ctRg73-uR6AVOck,30575
-vessel_api_python/_services.py,sha256=PoRoHZP7PoqcUGGEaZNszm9_a1K_nTBQu_s5OaPCIqI,79094
-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.3.0.dist-info/METADATA,sha256=omcgGfIpL-dHECfAZqvoTmHqAUn6oKf14g0NoAULcHk,7019
-vessel_api_python-1.3.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-vessel_api_python-1.3.0.dist-info/licenses/LICENSE,sha256=zoj_abq99mj8cz-Bz71XCnwB-Qv3kU1VzVXeKEntuQU,1067
-vessel_api_python-1.3.0.dist-info/RECORD,,