diff --git a/Makefile b/Makefile index 4261cd7..ebe5af3 100644 --- a/Makefile +++ b/Makefile @@ -11,13 +11,11 @@ install: .PHONY: format ## Auto-format python source files format: - python -m black $(sources) python -m ruff check --fix $(sources) python -m ruff format $(sources) .PHONY: format-notebooks ## Auto-format Jupyter Notebooks format-notebooks: - python -m black $(notebooks-sources) python -m ruff check --fix $(notebooks-sources) python -m ruff format $(notebooks-sources) @@ -25,13 +23,11 @@ format-notebooks: lint: python -m ruff check $(sources) python -m ruff format --check $(sources) - python -m black $(sources) --check --diff .PHONY: lint-notebooks ## Lint Jupyter Notebooks lint-notebooks: python -m ruff check $(notebooks-sources) python -m ruff format --check $(notebooks-sources) - python -m black $(notebooks-sources) --check --diff .PHONY: codespell ## Use Codespell to do spellchecking codespell: diff --git a/docs/source/conf.py b/docs/source/conf.py index bff4053..da0f0e7 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,5 +1,6 @@ +"""Global Fishing Watch (GFW) API Python Client - Sphinx Documentation Configuration.""" + # Configuration file for the Sphinx documentation builder. -# # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html diff --git a/notebooks/usage-guides/bulk-downloads-api.ipynb b/notebooks/usage-guides/bulk-downloads-api.ipynb index fb7b832..10461bc 100644 --- a/notebooks/usage-guides/bulk-downloads-api.ipynb +++ b/notebooks/usage-guides/bulk-downloads-api.ipynb @@ -118,8 +118,8 @@ }, "outputs": [], "source": [ - "import time\n", "import os\n", + "import time\n", "\n", "import gfwapiclient as gfw" ] diff --git a/pyproject.toml b/pyproject.toml index ffb229a..3a22d42 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -64,29 +64,29 @@ dependencies = [ "httpx~=0.28", # Making HTTP requests "typing-extensions~=4.15", # Backported Type Hints for Python 3.8+ "pydantic~=2.12", # Data validation and serialization - "pydantic-settings~=2.11", # Type-hinted configurations or settings + "pydantic-settings~=2.12", # Type-hinted configurations or settings "geojson-pydantic~=2.1", # Data models for the GeoJSON specification "mapbox-vector-tile~=2.2", # Encoding and decoding Mapbox Vector Tiles (MVT) "mercantile~=1.2", # Web mercator XYZ tile utilities - "pandas~=2.3", # Data analysis and manipulation + "pandas~=3.0", # Data analysis and manipulation "geopandas~=1.1", # Geospatial data analysis and manipulation ] [project.optional-dependencies] # Linting and code quality tools lint = [ - "black[jupyter]>=25.9.0", # Code formatting tool + "black[jupyter]>=26.1.0", # Code formatting tool "isort>=7.0.0", # Python imports sorting tool - "mypy>=1.18.2", # Static type checker + "mypy>=1.19.1", # Static type checker "pydocstyle>=6.3.0", # Python docstring style checker - "ruff>=0.14.2", # Linter and code analysis tool + "ruff>=0.14.14", # Linter and code analysis tool "codespell[toml]>=2.4.1", # Spell checker for code ] # Testing tools test = [ - "pytest>=8.4.2", # Core testing framework - "pytest-asyncio>=1.2.0", # Asyncio plugin for pytest + "pytest>=9.0.2", # Core testing framework + "pytest-asyncio>=1.3.0", # Asyncio plugin for pytest "pytest-cov>=7.0.0", # Coverage plugin for pytest "pytest-mock>=3.15.1", # Mocking plugin for pytest "pytest-xdist>=3.8.0", # Parallel test execution for pytest @@ -97,39 +97,39 @@ test = [ # Development workflow and tools dev = [ - "commitizen>=4.9.1", # Standardized commit messages and versioning - "pre-commit>=4.3.0", # Framework for managing pre-commit hooks - "pip-audit>=2.9.0", # Audit for finding vulnerabilities in dependencies + "commitizen>=4.12.1", # Standardized commit messages and versioning + "pre-commit>=4.5.1", # Framework for managing pre-commit hooks + "pip-audit>=2.10.0", # Audit for finding vulnerabilities in dependencies ] # Build tools build = [ - "build>=1.2.2", # Python PEP 517 compliant build system + "build>=1.4.0", # Python PEP 517 compliant build system "check-wheel-contents>=0.6.3", # Check wheels have the right contents - "pydistcheck>=0.10.0", # Inspect Python package distributions for common problems - "pyroma>=5.0", # Test project's packaging friendliness - "setuptools>=80.9.0", # Python packaging library + "pydistcheck>=0.11.3", # Inspect Python package distributions for common problems + "pyroma>=5.0.1", # Test project's packaging friendliness + "setuptools>=80.10.2", # Python packaging library "twine>=6.2.0", # For uploading Python packages to PyPI ] # Documentation tools docs = [ - "sphinx>=8.2.3", # Tool for generating documentation - "furo>=2025.9.25", # Sphinx theme for beautiful documentation - "myst-parser>=4.0.1", # Writing documentation with Markdown in Sphinx + "sphinx>=9.0.4", # Tool for generating documentation + "furo>=2025.12.19", # Sphinx theme for beautiful documentation + "myst-parser>=5.0.0", # Writing documentation with Markdown in Sphinx "myst-nb>=1.3.0", # Writing documentation with Jupyter Notebook in Sphinx "sphinx-copybutton>=0.5.2", # Add a "copy" button to code blocks in Sphinx "sphinx-autobuild>=2025.8.25", # Build, watch and serve documentation with live reload in the browser - "sphinx-inline-tabs>=2023.4.21", # Add inline tabbed content to documentation + "sphinx-inline-tabs>=2025.12.21.14", # Add inline tabbed content to documentation "sphinx-autodoc2>=0.5.0", # Generates API documentation for Python packages ] # Jupyter notebook and interactive tools notebooks = [ "ipykernel>=7.1.0", # Jupyter kernel for Python - "ipython>=9.6.0", # Enhanced interactive Python shell - "jupyterlab>=4.4.10", # Jupyter's next-generation web-based interface - "watermark>=2.5.0", # Add timestamps and version info to Jupyter notebook + "ipython>=9.9.0", # Enhanced interactive Python shell + "jupyterlab>=4.5.3", # Jupyter's next-generation web-based interface + "watermark>=2.6.0", # Add timestamps and version info to Jupyter notebook ] diff --git a/src/gfwapiclient/resources/references/__init__.py b/src/gfwapiclient/resources/references/__init__.py index 3213102..6207e4b 100644 --- a/src/gfwapiclient/resources/references/__init__.py +++ b/src/gfwapiclient/resources/references/__init__.py @@ -1,14 +1,30 @@ """Global Fishing Watch (GFW) API Python Client - Reference Data API Resource. This module provides the base resource for accessing static reference data from the -Global Fishing Watch (GFW) API. It includes functionality for retrieving -various types of reference information, such as regions, and other -contextual data. +Global Fishing Watch (GFW) API. It includes functionality for retrieving various types +of reference information, such as regions, and other contextual data. -For more details on the Reference Data API, please refer to the official +For detailed information about the Reference Data API, please refer to the official Global Fishing Watch API documentation: See: https://globalfishingwatch.org/our-apis/documentation#reference-data + +See: https://globalfishingwatch.org/our-apis/documentation#regions + +For more details on the Reference Data data caveats, please refer to the official +Global Fishing Watch API documentation: + +See: https://globalfishingwatch.org/our-apis/documentation#exclusive-economic-zone-boundaries-definition + +See: https://globalfishingwatch.org/our-apis/documentation#marine-protected-area-boundaries-definition + +See: https://globalfishingwatch.org/our-apis/documentation#what-does-it-mean-if-an-event-is-within-a-specific-geographic-area-such-as-an-eez-mpa-or-rfmo + +See: https://globalfishingwatch.org/our-apis/documentation#how-does-gfw-calculate-that-an-event-has-a-publicly-listed-authorization + +See: https://globalfishingwatch.org/our-apis/documentation#exclusive-economic-zone-boundaries-definitions + +See: https://globalfishingwatch.org/our-apis/documentation#marine-protected-area-boundaries-definition-2 """ from gfwapiclient.resources.references.resources import ReferenceResource diff --git a/src/gfwapiclient/resources/references/regions/__init__.py b/src/gfwapiclient/resources/references/regions/__init__.py index 804692b..e826f0b 100644 --- a/src/gfwapiclient/resources/references/regions/__init__.py +++ b/src/gfwapiclient/resources/references/regions/__init__.py @@ -1,12 +1,30 @@ -"""Global Fishing Watch (GFW) API Python Client - Regions API Endpoints. +"""Global Fishing Watch (GFW) API Python Client - Regions API endpoints. -This module defines the API endpoints for accessing region-specific data -from the Global Fishing Watch (GFW) API. It provides endpoints for retrieving -information about Exclusive Economic Zones (EEZs), Marine Protected Areas (MPAs), -and Regional Fisheries Management Organizations (RFMOs). +This module provides the endpoints and associated functionalities for retrieving +Exclusive Economic Zones (EEZs), Marine Protected Areas (MPAs), and +Regional Fisheries Management Organizations (RFMOs). It defines the `EEZRegionEndPoint`, +`MPARegionEndPoint`, and `RFMORegionEndPoint` classes, which handles the construction +and execution of API requests, and the parsing of API responses for Regions API endpoints. -For more details on the Regions API, please refer to the official +For detailed information about the Regions API endpoints, please refer to the official Global Fishing Watch API documentation: +See: https://globalfishingwatch.org/our-apis/documentation#reference-data + See: https://globalfishingwatch.org/our-apis/documentation#regions + +For more details on the Regions data caveats, please refer to the official +Global Fishing Watch API documentation: + +See: https://globalfishingwatch.org/our-apis/documentation#exclusive-economic-zone-boundaries-definition + +See: https://globalfishingwatch.org/our-apis/documentation#marine-protected-area-boundaries-definition + +See: https://globalfishingwatch.org/our-apis/documentation#what-does-it-mean-if-an-event-is-within-a-specific-geographic-area-such-as-an-eez-mpa-or-rfmo + +See: https://globalfishingwatch.org/our-apis/documentation#how-does-gfw-calculate-that-an-event-has-a-publicly-listed-authorization + +See: https://globalfishingwatch.org/our-apis/documentation#exclusive-economic-zone-boundaries-definitions + +See: https://globalfishingwatch.org/our-apis/documentation#marine-protected-area-boundaries-definition-2 """ diff --git a/src/gfwapiclient/resources/references/regions/endpoints.py b/src/gfwapiclient/resources/references/regions/endpoints.py index aeceaa7..861eda5 100644 --- a/src/gfwapiclient/resources/references/regions/endpoints.py +++ b/src/gfwapiclient/resources/references/regions/endpoints.py @@ -1,9 +1,9 @@ -"""Global Fishing Watch (GFW) API Python Client - Regions API EndPoints.""" +"""Global Fishing Watch (GFW) API Python Client - Regions API endpoints.""" from gfwapiclient.http.client import HTTPClient from gfwapiclient.http.endpoints import GetEndPoint from gfwapiclient.http.models import RequestBody, RequestParams -from gfwapiclient.resources.references.regions.models import ( +from gfwapiclient.resources.references.regions.models.response import ( EEZRegionItem, EEZRegionResult, MPARegionItem, @@ -22,8 +22,11 @@ class EEZRegionEndPoint( """Get Exclusive Economic Zone (EEZ) regions API endpoint. This endpoint retrieves a list of Exclusive Economic Zone (EEZ) regions. - See the API documentation for more details: - https://globalfishingwatch.org/our-apis/documentation#regions + + For more details on the EEZ regions API endpoint, please refer to the official + Global Fishing Watch API documentation: + + See: https://globalfishingwatch.org/our-apis/documentation#regions """ def __init__( @@ -52,8 +55,11 @@ class MPARegionEndPoint( """Get Marine Protected Area (MPA) regions API endpoint. This endpoint retrieves a list of Marine Protected Area (MPA) regions. - See the API documentation for more details: - https://globalfishingwatch.org/our-apis/documentation#regions + + For more details on the MPA regions API endpoint, please refer to the official + Global Fishing Watch API documentation: + + See: https://globalfishingwatch.org/our-apis/documentation#regions """ def __init__( @@ -82,8 +88,11 @@ class RFMORegionEndPoint( """Get Regional Fisheries Management Organization (RFMO) regions API endpoint. This endpoint retrieves a list of Regional Fisheries Management Organization (RFMO) regions. - See the API documentation for more details: - https://globalfishingwatch.org/our-apis/documentation#regions + + For more details on the RFMO regions API endpoint, please refer to the official + Global Fishing Watch API documentation: + + See: https://globalfishingwatch.org/our-apis/documentation#regions """ def __init__( diff --git a/src/gfwapiclient/resources/references/regions/models/__init__.py b/src/gfwapiclient/resources/references/regions/models/__init__.py index 6478b1c..f5d3a45 100644 --- a/src/gfwapiclient/resources/references/regions/models/__init__.py +++ b/src/gfwapiclient/resources/references/regions/models/__init__.py @@ -1,35 +1,32 @@ """Global Fishing Watch (GFW) API Python Client - Regions API Models. -This module defines the data models for the Regions API within the GFW API Python Client. -It provides Pydantic models for the response objects related to Exclusive Economic Zones (EEZs), -Marine Protected Areas (MPAs), and Regional Fisheries Management Organizations (RFMOs). +This module defines Pydantic data models used for interacting with the +Regions API endpoints. These models are used to represent response data +when retrieving Exclusive Economic Zones (EEZs), Marine Protected Areas (MPAs), +and Regional Fisheries Management Organizations (RFMOs). -These models are used to deserialize the JSON responses from the GFW API's regions endpoints, +These models are used to deserialize the JSON responses from the Regions API endpoints, ensuring type safety and data validation. -For more information on the GFW API and its regions endpoints, please refer to the -official Global Fishing Watch API documentation: +For detailed information about the Regions API endpoints, please refer to the official +Global Fishing Watch API documentation: See: https://globalfishingwatch.org/our-apis/documentation#reference-data See: https://globalfishingwatch.org/our-apis/documentation#regions -""" -from gfwapiclient.resources.references.regions.models.response import ( - EEZRegionItem, - EEZRegionResult, - MPARegionItem, - MPARegionResult, - RFMORegionItem, - RFMORegionResult, -) - - -__all__ = [ - "EEZRegionItem", - "EEZRegionResult", - "MPARegionItem", - "MPARegionResult", - "RFMORegionItem", - "RFMORegionResult", -] +For more details on the Regions data caveats, please refer to the official +Global Fishing Watch API documentation: + +See: https://globalfishingwatch.org/our-apis/documentation#exclusive-economic-zone-boundaries-definition + +See: https://globalfishingwatch.org/our-apis/documentation#marine-protected-area-boundaries-definition + +See: https://globalfishingwatch.org/our-apis/documentation#what-does-it-mean-if-an-event-is-within-a-specific-geographic-area-such-as-an-eez-mpa-or-rfmo + +See: https://globalfishingwatch.org/our-apis/documentation#how-does-gfw-calculate-that-an-event-has-a-publicly-listed-authorization + +See: https://globalfishingwatch.org/our-apis/documentation#exclusive-economic-zone-boundaries-definitions + +See: https://globalfishingwatch.org/our-apis/documentation#marine-protected-area-boundaries-definition-2 +""" diff --git a/src/gfwapiclient/resources/references/regions/models/response.py b/src/gfwapiclient/resources/references/regions/models/response.py index ceed743..7ffa191 100644 --- a/src/gfwapiclient/resources/references/regions/models/response.py +++ b/src/gfwapiclient/resources/references/regions/models/response.py @@ -20,32 +20,63 @@ class EEZRegionItem(ResultItem): """Exclusive Economic Zone (EEZ) region item. + Represents single EEZ region item returned by the EEZ regions API endpoint. + Attributes: id (Optional[int]): - Region ID. + Unique identifier for the EEZ region. Used in 4Wings, Events and + Bulk Download API queries. label (Optional[str]): - Region label. + Human-readable name of the EEZ region. iso3 (Optional[str]): - ISO3 country code. + ISO 3166-1 alpha-3 country code (`null` for joint regimes and + overlapping claims). + + iso_sov_1 (Optional[str]): + Primary sovereignty ISO code. + + iso_sov_2 (Optional[str]): + Secondary sovereignty ISO code (for joint regimes/overlapping claims). + + iso_sov_3 (Optional[str]): + Tertiary sovereignty ISO code (for complex overlapping claims). + + territory_1 (Optional[str]): + Territory name. dataset (str): - Dataset name or ID. + Dataset name or ID. Used in 4Wings, Events and Bulk Download API queries. """ id: Optional[int] = Field(None) label: Optional[str] = Field(None) iso3: Optional[str] = Field(None) + iso_sov_1: Optional[str] = Field(None, alias="isoSov1") + iso_sov_2: Optional[str] = Field(None, alias="isoSov2") + iso_sov_3: Optional[str] = Field(None, alias="isoSov3") + territory_1: Optional[str] = Field(None, alias="territory1") dataset: Optional[str] = Field("public-eez-areas") class EEZRegionResult(Result[EEZRegionItem]): """Result for Exclusive Economic Zone (EEZ) regions API endpoint. - This model represents the result returned by the EEZ regions API endpoint. - See the API documentation for more details: - https://globalfishingwatch.org/our-apis/documentation#regions + Represents result (i.e., list of EEZ region items) returned by the EEZ regions + API endpoint. + + For more details on the EEZ regions API endpoint supported response bodies, + please refer to the official Global Fishing Watch API documentation: + + See: https://globalfishingwatch.org/our-apis/documentation#regions + + Attributes: + _result_item_class (Type[EEZRegionItem]): + The model used for individual result items. + + _data (EEZRegionItem): + The EEZ region item returned in the response. """ _result_item_class: Type[EEZRegionItem] @@ -56,7 +87,7 @@ def __init__(self, data: List[EEZRegionItem]) -> None: Args: data (List[EEZRegionItem]): - A list of `EEZRegionItem` objects representing the EEZ regions. + The of list of EEZ region items. """ super().__init__(data=data) @@ -64,32 +95,42 @@ def __init__(self, data: List[EEZRegionItem]) -> None: class MPARegionItem(ResultItem): """Marine Protected Area (MPA) region item. + Represents single MPA region item returned by the MPA regions API endpoint. + Attributes: id (Optional[str]): - Region ID. + Unique identifier for the MPA region. Used in 4Wings, Events and + Bulk Download API queries. label (Optional[str]): - Region label. - - name (Optional[str]): - Region name. + Name and designation of the Marine Protected Area. dataset (str): - Dataset name or ID. + Dataset name or ID. Used in 4Wings, Events and Bulk Download API queries. """ id: Optional[str] = Field(None) label: Optional[str] = Field(None) - name: Optional[str] = Field(None, validation_alias="NAME") dataset: Optional[str] = Field("public-mpa-all") class MPARegionResult(Result[MPARegionItem]): """Result for Marine Protected Area (MPA) regions API endpoint. - This model represents the result returned by the MPA regions API endpoint. - See the API documentation for more details: - https://globalfishingwatch.org/our-apis/documentation#regions + Represents result (i.e., list of MPA region items) returned by the MPA regions + API endpoint. + + For more details on the MPA regions API endpoint supported response bodies, + please refer to the official Global Fishing Watch API documentation: + + See: https://globalfishingwatch.org/our-apis/documentation#regions + + Attributes: + _result_item_class (Type[MPARegionItem]): + The model used for individual result items. + + _data (MPARegionItem): + The MPA region item returned in the response. """ _result_item_class: Type[MPARegionItem] @@ -100,7 +141,7 @@ def __init__(self, data: List[MPARegionItem]) -> None: Args: data (List[MPARegionItem]): - A list of `MPARegionItem` objects representing the MPA regions. + The of list of EEZ region items. """ super().__init__(data=data) @@ -108,32 +149,46 @@ def __init__(self, data: List[MPARegionItem]) -> None: class RFMORegionItem(ResultItem): """Regional Fisheries Management Organization (RFMO) region item. + Represents single RFMO region item returned by the RFMO regions API endpoint. + Attributes: id (Optional[str]): - Region ID. + Unique identifier for the RFMO region (matches the abbreviation). + Used in 4Wings, Events and Bulk Download API queries. label (Optional[str]): - Region label. + Standard abbreviation of the RFMO or fisheries body. - rfb (Optional[str]): - Region RFB. + id_ (Optional[str]): + Duplicate identifier field (matches id and label). dataset (str): - Dataset name or ID. + Dataset name or ID. Used in 4Wings, Events and Bulk Download API queries. """ id: Optional[str] = Field(None) label: Optional[str] = Field(None) - rfb: Optional[str] = Field(None, title="RFB", validation_alias="RFB") + id_: Optional[str] = Field(None, alias="ID") dataset: Optional[str] = Field("public-rfmo") class RFMORegionResult(Result[RFMORegionItem]): """Result for Regional Fisheries Management Organization (RFMO) regions API endpoint. - This model represents the result returned by the RFMO regions API endpoint. - See the API documentation for more details: - https://globalfishingwatch.org/our-apis/documentation#regions + Represents result (i.e., list of RFMO region items) returned by the RFMO regions + API endpoint. + + For more details on the RFMO regions API endpoint supported response bodies, + please refer to the official Global Fishing Watch API documentation: + + See: https://globalfishingwatch.org/our-apis/documentation#regions + + Attributes: + _result_item_class (Type[RFMORegionItem]): + The model used for individual result items. + + _data (RFMORegionItem): + The RFMO region item returned in the response. """ _result_item_class: Type[RFMORegionItem] @@ -144,6 +199,6 @@ def __init__(self, data: List[RFMORegionItem]) -> None: Args: data (List[RFMORegionItem]): - A list of `RFMORegionItem` objects representing the RFMO regions. + The of list of EEZ region items. """ super().__init__(data=data) diff --git a/src/gfwapiclient/resources/references/resources.py b/src/gfwapiclient/resources/references/resources.py index c67cab1..d1d8171 100644 --- a/src/gfwapiclient/resources/references/resources.py +++ b/src/gfwapiclient/resources/references/resources.py @@ -8,7 +8,7 @@ MPARegionEndPoint, RFMORegionEndPoint, ) -from gfwapiclient.resources.references.regions.models import ( +from gfwapiclient.resources.references.regions.models.response import ( EEZRegionResult, MPARegionResult, RFMORegionResult, @@ -21,9 +21,34 @@ class ReferenceResource(BaseResource): """References data API resource. - This resource provides access to reference data endpoints, such as EEZ, MPA, and RFMO regions. - See the API documentation for more details: - https://globalfishingwatch.org/our-apis/documentation#regions + This resource provides methods to interact with the Reference Data API, + specifically to: + + - Retrieves a list of Exclusive Economic Zone (EEZ) regions. + - Retrieves a list of Marine Protected Area (MPA) regions. + - Retrieves a list of Regional Fisheries Management Organization (RFMO) regions. + + For detailed information about the Reference Data API, please refer to the official + Global Fishing Watch API documentation: + + See: https://globalfishingwatch.org/our-apis/documentation#reference-data + + See: https://globalfishingwatch.org/our-apis/documentation#regions + + For more details on the Reference Data API data caveats, please refer to the + official Global Fishing Watch API documentation: + + See: https://globalfishingwatch.org/our-apis/documentation#exclusive-economic-zone-boundaries-definition + + See: https://globalfishingwatch.org/our-apis/documentation#marine-protected-area-boundaries-definition + + See: https://globalfishingwatch.org/our-apis/documentation#what-does-it-mean-if-an-event-is-within-a-specific-geographic-area-such-as-an-eez-mpa-or-rfmo + + See: https://globalfishingwatch.org/our-apis/documentation#how-does-gfw-calculate-that-an-event-has-a-publicly-listed-authorization + + See: https://globalfishingwatch.org/our-apis/documentation#exclusive-economic-zone-boundaries-definitions + + See: https://globalfishingwatch.org/our-apis/documentation#marine-protected-area-boundaries-definition-2 """ async def get_eez_regions(self, **kwargs: Dict[str, Any]) -> EEZRegionResult: @@ -31,13 +56,31 @@ async def get_eez_regions(self, **kwargs: Dict[str, Any]) -> EEZRegionResult: Retrieves a list of Exclusive Economic Zone (EEZ) regions. + For detailed information about the EEZ regions API endpoint, please refer to the official + Global Fishing Watch API documentation: + + See: https://globalfishingwatch.org/our-apis/documentation#regions + + For more details on the EEZ regions data caveats, please refer to the official + Global Fishing Watch API documentation: + + See: https://globalfishingwatch.org/our-apis/documentation#exclusive-economic-zone-boundaries-definition + + See: https://globalfishingwatch.org/our-apis/documentation#what-does-it-mean-if-an-event-is-within-a-specific-geographic-area-such-as-an-eez-mpa-or-rfmo + + See: https://globalfishingwatch.org/our-apis/documentation#exclusive-economic-zone-boundaries-definitions + Args: **kwargs (Dict[str, Any]): Additional keyword arguments to pass to the EEZ region endpoint's request. Returns: EEZRegionResult: - An `EEZRegionResult` instance containing the EEZ regions data. + The result containing the list of EEZ regions data items. + + Raises: + GFWAPIClientError: + If the API request fails. """ endpoint: EEZRegionEndPoint = EEZRegionEndPoint(http_client=self._http_client) result: EEZRegionResult = await endpoint.request(**kwargs) @@ -48,13 +91,31 @@ async def get_mpa_regions(self, **kwargs: Dict[str, Any]) -> MPARegionResult: Retrieves a list of Marine Protected Area (MPA) regions. + For detailed information about the MPA regions API endpoint, please refer to the official + Global Fishing Watch API documentation: + + See: https://globalfishingwatch.org/our-apis/documentation#regions + + For more details on the MPA regions data caveats, please refer to the official + Global Fishing Watch API documentation: + + See: https://globalfishingwatch.org/our-apis/documentation#marine-protected-area-boundaries-definition + + See: https://globalfishingwatch.org/our-apis/documentation#what-does-it-mean-if-an-event-is-within-a-specific-geographic-area-such-as-an-eez-mpa-or-rfmo + + See: https://globalfishingwatch.org/our-apis/documentation#marine-protected-area-boundaries-definition-2 + Args: **kwargs (Dict[str, Any]): Additional keyword arguments to pass to the MPA region endpoint's request. Returns: MPARegionResult: - An `MPARegionResult` instance containing the MPA regions data. + The result containing the list of MPA regions data items. + + Raises: + GFWAPIClientError: + If the API request fails. """ endpoint: MPARegionEndPoint = MPARegionEndPoint(http_client=self._http_client) result: MPARegionResult = await endpoint.request(**kwargs) @@ -65,13 +126,29 @@ async def get_rfmo_regions(self, **kwargs: Dict[str, Any]) -> RFMORegionResult: Retrieves a list of Regional Fisheries Management Organization (RFMO) regions. + For detailed information about the RFMO regions API endpoint, please refer to the official + Global Fishing Watch API documentation: + + See: https://globalfishingwatch.org/our-apis/documentation#regions + + For more details on the RFMO regions data caveats, please refer to the official + Global Fishing Watch API documentation: + + See: https://globalfishingwatch.org/our-apis/documentation#what-does-it-mean-if-an-event-is-within-a-specific-geographic-area-such-as-an-eez-mpa-or-rfmo + + See: https://globalfishingwatch.org/our-apis/documentation#how-does-gfw-calculate-that-an-event-has-a-publicly-listed-authorization + Args: **kwargs (Dict[str, Any]): Additional keyword arguments to pass to the RFMO region endpoint's request. Returns: RFMORegionResult: - An `RFMORegionResult` instance containing the RFMO regions data. + The result containing the list of RFMO regions data items. + + Raises: + GFWAPIClientError: + If the API request fails. """ endpoint: RFMORegionEndPoint = RFMORegionEndPoint(http_client=self._http_client) result: RFMORegionResult = await endpoint.request(**kwargs) diff --git a/tests/fixtures/references/eez_region_item.json b/tests/fixtures/references/eez_region_item.json new file mode 100644 index 0000000..833304d --- /dev/null +++ b/tests/fixtures/references/eez_region_item.json @@ -0,0 +1,9 @@ +{ + "label": "Senegalese Exclusive Economic Zone", + "id": 8371, + "iso3": "SEN", + "isoSov1": "SEN", + "isoSov2": null, + "isoSov3": null, + "territory1": "Senegal" +} diff --git a/tests/fixtures/references/mpa_region_item.json b/tests/fixtures/references/mpa_region_item.json new file mode 100644 index 0000000..ab36607 --- /dev/null +++ b/tests/fixtures/references/mpa_region_item.json @@ -0,0 +1,4 @@ +{ + "label": "Dorsal de Nasca - Reserva Nacional", + "id": "555745302" +} diff --git a/tests/fixtures/references/rfmo_region_item.json b/tests/fixtures/references/rfmo_region_item.json new file mode 100644 index 0000000..1e1230a --- /dev/null +++ b/tests/fixtures/references/rfmo_region_item.json @@ -0,0 +1,5 @@ +{ + "label": "ICCAT", + "id": "ICCAT", + "ID": "ICCAT" +} diff --git a/tests/resources/references/conftest.py b/tests/resources/references/conftest.py index abe3fd6..ec19ac6 100644 --- a/tests/resources/references/conftest.py +++ b/tests/resources/references/conftest.py @@ -1,53 +1,62 @@ """Test configurations for `gfwapiclient.resources.references`.""" -from typing import Any, Dict +from typing import Any, Callable, Dict import pytest @pytest.fixture -def mock_raw_eez_region_item() -> Dict[str, Any]: +def mock_raw_eez_region_item( + load_json_fixture: Callable[[str], Dict[str, Any]], +) -> Dict[str, Any]: """Fixture for mock raw EEZ region item. + This fixture loads sample JSON data representing a single + `EEZRegionItem` from a fixture file. + Returns: Dict[str, Any]: - Raw `EEZRegionItem` sample data. + Raw `EEZRegionItem` sample data as a dictionary. """ - raw_eez_region_item: Dict[str, Any] = { - "id": 8371, - "label": "Senegal", - "iso3": "SEN", - } + raw_eez_region_item: Dict[str, Any] = load_json_fixture( + "references/eez_region_item.json" + ) return raw_eez_region_item @pytest.fixture -def mock_raw_mpa_region_item() -> Dict[str, Any]: +def mock_raw_mpa_region_item( + load_json_fixture: Callable[[str], Dict[str, Any]], +) -> Dict[str, Any]: """Fixture for mock raw MPA region item. + This fixture loads sample JSON data representing a single + `MPARegionItem` from a fixture file. + Returns: Dict[str, Any]: - Raw `MPARegionItem` sample data. + Raw `MPARegionItem` sample data as a dictionary. """ - raw_mpa_region_item: Dict[str, Any] = { - "label": "Dorsal de Nasca - Reserva Nacional", - "id": "555745302", - "NAME": "Dorsal de Nasca", - } + raw_mpa_region_item: Dict[str, Any] = load_json_fixture( + "references/mpa_region_item.json" + ) return raw_mpa_region_item @pytest.fixture -def mock_raw_rfmo_region_item() -> Dict[str, Any]: +def mock_raw_rfmo_region_item( + load_json_fixture: Callable[[str], Dict[str, Any]], +) -> Dict[str, Any]: """Fixture for mock raw RFMO region item. + This fixture loads sample JSON data representing a single + `RFMORegionItem` from a fixture file. + Returns: Dict[str, Any]: - Raw `RFMORegionItem` sample data. + Raw `RFMORegionItem` sample data as a dictionary. """ - raw_rfmo_region_item: Dict[str, Any] = { - "label": "ICCAT", - "id": "ICCAT", - "RFB": "ICCAT", - } + raw_rfmo_region_item: Dict[str, Any] = load_json_fixture( + "references/rfmo_region_item.json" + ) return raw_rfmo_region_item diff --git a/tests/resources/references/regions/models/test_response_models.py b/tests/resources/references/regions/models/test_response_models.py index 872573b..6e28059 100644 --- a/tests/resources/references/regions/models/test_response_models.py +++ b/tests/resources/references/regions/models/test_response_models.py @@ -20,6 +20,10 @@ def test_eez_region_item_deserializes_all_fields( assert eez_region_item.id == mock_raw_eez_region_item["id"] assert eez_region_item.label == mock_raw_eez_region_item["label"] assert eez_region_item.iso3 == mock_raw_eez_region_item["iso3"] + assert eez_region_item.iso_sov_1 == mock_raw_eez_region_item["isoSov1"] + assert eez_region_item.iso_sov_2 == mock_raw_eez_region_item["isoSov2"] + assert eez_region_item.iso_sov_3 == mock_raw_eez_region_item["isoSov3"] + assert eez_region_item.territory_1 == mock_raw_eez_region_item["territory1"] assert eez_region_item.dataset == "public-eez-areas" @@ -30,7 +34,6 @@ def test_mpa_region_item_deserializes_all_fields( mpa_region_item = MPARegionItem(**mock_raw_mpa_region_item) assert mpa_region_item.id == mock_raw_mpa_region_item["id"] assert mpa_region_item.label == mock_raw_mpa_region_item["label"] - assert mpa_region_item.name == mock_raw_mpa_region_item["NAME"] assert mpa_region_item.dataset == "public-mpa-all" @@ -41,7 +44,7 @@ def test_rfmo_region_item_deserializes_all_fields( rfmo_region_item = RFMORegionItem(**mock_raw_rfmo_region_item) assert rfmo_region_item.id == mock_raw_rfmo_region_item["id"] assert rfmo_region_item.label == mock_raw_rfmo_region_item["label"] - assert rfmo_region_item.rfb == mock_raw_rfmo_region_item["RFB"] + assert rfmo_region_item.id_ == mock_raw_rfmo_region_item["ID"] assert rfmo_region_item.dataset == "public-rfmo"