enhance reference region models, documentations, and test fixtures

Makefile

@@ -11,27 +11,23 @@ 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)
 
 .PHONY: lint  ## Lint python source files
 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:

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
 

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"
    ]

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
 ]
 
 

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

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
 """

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__(

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
+"""