feat(bulk-downloads): implement bulk report query API endpoints and models

This:
- add `BulkReportQueryEndPoint`, an endpoint class for handling specific bulk report query requests
- add `BulkReportQueryParams` for serializing and validating request parameters
- add `BulkReportQueryItem` and `BulkReportQueryResult` for deserializing and validating API responses
- add `BulkFixedInfrastructureDataQueryEndPoint` for handling fixed infrastructure bulk report query requests
- add `fixtures` and `unit tests` for `BulkReportQueryParams`, and `BulkFixedInfrastructureDataQueryEndPoint`

Author: lykmapipo

src/gfwapiclient/resources/bulk_downloads/query/__init__.py

@@ -0,0 +1,18 @@
+"""Global Fishing Watch (GFW) API Python Client - Query Bulk Report.
+
+This module provides the endpoint and associated functionalities for querying
+the previously created bulk report structured data in JSON format.
+It defines the `BulkReportQueryEndPoint` class, which handles the construction
+and execution of API requests and the parsing of API responses for
+Query Bulk Report API endpoint.
+
+For detailed information about the Query Bulk Report API endpoint, please refer to
+the official Global Fishing Watch API documentation:
+
+See: https://globalfishingwatch.org/our-apis/documentation#get-data-in-json-format
+
+For more details on the Query Bulk Report data caveats, please refer to the
+official Global Fishing Watch API documentation:
+
+See: https://globalfishingwatch.org/our-apis/documentation#sar-fixed-infrastructure-data-caveats
+"""

src/gfwapiclient/resources/bulk_downloads/query/endpoints.py

@@ -0,0 +1,169 @@
+"""Global Fishing Watch (GFW) API Python Client - Query Bulk Report API endpoints."""
+
+from typing import Any, Dict, List, Type, Union
+
+from typing_extensions import override
+
+from gfwapiclient.exceptions.validation import ResultValidationError
+from gfwapiclient.http.client import HTTPClient
+from gfwapiclient.http.endpoints import GetEndPoint
+from gfwapiclient.http.models import RequestBody
+from gfwapiclient.resources.bulk_downloads.query.models.base.request import (
+    BulkReportQueryParams,
+)
+from gfwapiclient.resources.bulk_downloads.query.models.base.response import (
+    _BulkReportQueryItemT,
+    _BulkReportQueryResultT,
+)
+from gfwapiclient.resources.bulk_downloads.query.models.fixed_infrastructure_data.response import (
+    BulkFixedInfrastructureDataQueryItem,
+    BulkFixedInfrastructureDataQueryResult,
+)
+
+
+__all__ = ["BulkFixedInfrastructureDataQueryEndPoint", "BulkReportQueryEndPoint"]
+
+
+class BulkReportQueryEndPoint(
+    GetEndPoint[
+        BulkReportQueryParams,
+        RequestBody,
+        _BulkReportQueryItemT,
+        _BulkReportQueryResultT,
+    ],
+):
+    """Query Bulk Report API endpoint.
+
+    This endpoint query the previously created bulk report data in JSON format
+    based on the provided request parameters.
+
+    For more details on the Query Bulk Report API endpoint, please refer to the
+    official Global Fishing Watch API documentation:
+
+    See: https://globalfishingwatch.org/our-apis/documentation#get-data-in-json-format
+    """
+
+    def __init__(
+        self,
+        *,
+        bulk_report_id: str,
+        request_params: BulkReportQueryParams,
+        result_item_class: Type[_BulkReportQueryItemT],
+        result_class: Type[_BulkReportQueryResultT],
+        http_client: HTTPClient,
+    ) -> None:
+        """Initializes a new `BulkReportQueryEndPoint`.
+
+        Args:
+            bulk_report_id (str):
+                Unique identifier (ID) of the bulk report.
+
+            request_params (BulkReportQueryParams):
+                The request parameters.
+
+            result_item_class (Type[_BulkReportQueryItemT]):
+                Pydantic model for the expected response item.
+
+            result_class (Type[_BulkReportQueryResultT]):
+                Pydantic model for the expected response result.
+
+            http_client (HTTPClient):
+                The HTTP client used to make the API call.
+        """
+        super().__init__(
+            path=f"bulk-reports/{bulk_report_id}/query",
+            request_params=request_params,
+            result_item_class=result_item_class,
+            result_class=result_class,
+            http_client=http_client,
+        )
+
+    @override
+    def _transform_response_data(
+        self,
+        *,
+        body: Union[List[Dict[str, Any]], Dict[str, Any]],
+    ) -> Union[List[Dict[str, Any]], Dict[str, Any]]:
+        """Transform and reshape response body and yield data.
+
+        This method transforms the raw response body from the API into a format
+        suitable for the `BulkReportQueryResult` model.
+
+        The expected response structure is: `{"entries": [{...}]}`.
+
+        Args:
+            body (Union[List[Dict[str, Any]], Dict[str, Any]]):
+                The raw response body.
+
+        Returns:
+            Union[List[Dict[str, Any]], Dict[str, Any]]:
+                The transformed response data.
+
+        Raises:
+            ResultValidationError:
+                If the response body does not match the expected format.
+        """
+        # expected: {"entries": [{"key": ...}, ...], ...}
+        if not isinstance(body, dict) or "entries" not in body:
+            raise ResultValidationError(
+                message="Expected a list of entries, but got an empty list.",
+                body=body,
+            )
+
+        # Transforming and reshaping entries
+        bulk_report_data_entries: List[Dict[str, Any]] = body.get("entries", [])
+        transformed_data: List[Dict[str, Any]] = []
+
+        # Loop through "entries" list i.e [{"key": ..., ...}, ...]
+        for bulk_report_data_entry in bulk_report_data_entries:
+            # Append extracted dictionaries, if not empty
+            if bulk_report_data_entry:
+                transformed_data.append(dict(**bulk_report_data_entry))
+
+        return transformed_data
+
+
+class BulkFixedInfrastructureDataQueryEndPoint(
+    BulkReportQueryEndPoint[
+        BulkFixedInfrastructureDataQueryItem,
+        BulkFixedInfrastructureDataQueryResult,
+    ],
+):
+    """Query Bulk fixed infrastructure data API endpoint.
+
+    This endpoint query the previously created fixed infrastructure data (i.e.,
+    `public-fixed-infrastructure-data:latest` dataset) bulk report data in JSON format
+    based on the provided request parameters.
+
+    For more details on the Query Bulk Report API endpoint, please refer to the
+    official Global Fishing Watch API documentation:
+
+    See: https://globalfishingwatch.org/our-apis/documentation#get-data-in-json-format
+    """
+
+    def __init__(
+        self,
+        *,
+        bulk_report_id: str,
+        request_params: BulkReportQueryParams,
+        http_client: HTTPClient,
+    ) -> None:
+        """Initializes a new `BulkFixedInfrastructureDataQueryEndPoint`.
+
+        Args:
+            bulk_report_id (str):
+                Unique identifier (ID) of the bulk report.
+
+            request_params (BulkReportQueryParams):
+                The request parameters.
+
+            http_client (HTTPClient):
+                The HTTP client used to make the API call.
+        """
+        super().__init__(
+            bulk_report_id=bulk_report_id,
+            request_params=request_params,
+            result_item_class=BulkFixedInfrastructureDataQueryItem,
+            result_class=BulkFixedInfrastructureDataQueryResult,
+            http_client=http_client,
+        )

src/gfwapiclient/resources/bulk_downloads/query/models/__init__.py

@@ -0,0 +1,17 @@
+"""Global Fishing Watch (GFW) API Python Client - Query Bulk Report Data Models.
+
+This module defines Pydantic data models used for interacting with the
+Query Bulk Report Data API endpoint. These models are used to represent
+request parameters, and response data when querying data in JSON format of the
+previously created bulk report.
+
+For detailed information about the Query Bulk Report Data API endpoint, please refer to
+the official Global Fishing Watch API documentation:
+
+See: https://globalfishingwatch.org/our-apis/documentation#get-data-in-json-format
+
+For more details on the Query Bulk Report Data data caveats, please refer to the
+official Global Fishing Watch API documentation:
+
+See: https://globalfishingwatch.org/our-apis/documentation#sar-fixed-infrastructure-data-caveats
+"""

src/gfwapiclient/resources/bulk_downloads/query/models/base/__init__.py

@@ -0,0 +1,16 @@
+"""Global Fishing Watch (GFW) API Python Client - Query Bulk Report Base Models.
+
+This module defines base Pydantic models used across the Query Bulk Report API
+endpoint. These models provide common structures for request parameters, and response
+data when querying data in JSON format of the previously created bulk report.
+
+For detailed information about the Query Bulk Report API endpoint, please refer to
+the official Global Fishing Watch API documentation:
+
+See: https://globalfishingwatch.org/our-apis/documentation#get-data-in-json-format
+
+For more details on the Query Bulk Report data caveats, please refer to the
+official Global Fishing Watch API documentation:
+
+See: https://globalfishingwatch.org/our-apis/documentation#sar-fixed-infrastructure-data-caveats
+"""

src/gfwapiclient/resources/bulk_downloads/query/models/base/request.py

@@ -0,0 +1,51 @@
+"""Global Fishing Watch (GFW) API Python Client - Query Bulk Report Base Request Models."""
+
+from typing import ClassVar, Final, List, Optional
+
+from pydantic import Field
+
+from gfwapiclient.http.models import RequestParams
+
+
+__all__ = ["BulkReportQueryParams"]
+
+
+BULK_REPORT_QUERY_PARAMS_VALIDATION_ERROR_MESSAGE: Final[str] = (
+    "Query bulk report request parameters validation failed."
+)
+
+
+class BulkReportQueryParams(RequestParams):
+    """Request query parameters for Query Bulk Report API endpoint.
+
+    Represents pagination, sorting, filtering parameters etc. for querying previously
+    created bulk report data.
+
+    For more details on the Query Bulk Report API endpoint supported request parameters,
+    please refer to the official Global Fishing Watch API documentation:
+
+    See: https://globalfishingwatch.org/our-apis/documentation#get-data-in-json-format
+
+    Attributes:
+        limit (Optional[int]):
+            Maximum number of bulk report records to return.
+            Defaults to `99999`.
+
+        offset (Optional[int]):
+            Number of bulk report records to skip before returning results.
+            Used for pagination. Defaults to `0`.
+
+        sort (Optional[str]):
+            Property to sort the bulk report records by (e.g.
+            `"-structure_start_date"`).
+
+        includes (Optional[List[str]]):
+            List of bulk report record fields to include in the result.
+    """
+
+    indexed_fields: ClassVar[Optional[List[str]]] = ["includes"]
+
+    limit: Optional[int] = Field(99999, ge=0, alias="limit")
+    offset: Optional[int] = Field(0, ge=0, alias="offset")
+    sort: Optional[str] = Field(None, alias="sort")
+    includes: Optional[List[str]] = Field(None, alias="includes")

src/gfwapiclient/resources/bulk_downloads/query/models/base/response.py

@@ -0,0 +1,66 @@
+"""Global Fishing Watch (GFW) API Python Client - Query Bulk Report Base Response Models."""
+
+from typing import Any, List, Type, TypeVar
+
+from gfwapiclient.http.models import Result, ResultItem
+
+
+__all__ = [
+    "BulkReportQueryItem",
+    "BulkReportQueryResult",
+    "_BulkReportQueryItemT",
+    "_BulkReportQueryResultT",
+]
+
+
+class BulkReportQueryItem(ResultItem):
+    """Result item for the Query Bulk Report API endpoint.
+
+    Represents a data record of a previously created bulk report.
+
+    For more details on the Query Bulk Report API endpoint supported response bodies,
+    please refer to the official Global Fishing Watch API documentation:
+
+    See: https://globalfishingwatch.org/our-apis/documentation#get-data-in-json-format
+    """
+
+    pass
+
+
+_BulkReportQueryItemT = TypeVar("_BulkReportQueryItemT", bound=BulkReportQueryItem)
+
+
+class BulkReportQueryResult(Result[_BulkReportQueryItemT]):
+    """Result for the Query Bulk Report API endpoint.
+
+    Represents data records of a previously created bulk report.
+
+    For more details on the Query Bulk Report API endpoint supported response bodies,
+    please refer to the official Global Fishing Watch API documentation:
+
+    See: https://globalfishingwatch.org/our-apis/documentation#get-data-in-json-format
+
+    Attributes:
+        _result_item_class (Type[_BulkReportQueryItemT]):
+            The model used for individual result items.
+
+        _data (List[_BulkReportQueryItemT]):
+            The bulk report data item returned in the response.
+    """
+
+    _result_item_class: Type[_BulkReportQueryItemT]
+    _data: List[_BulkReportQueryItemT]
+
+    def __init__(self, data: List[_BulkReportQueryItemT]) -> None:
+        """Initializes a new `BulkReportQueryResult`.
+
+        Args:
+            data (List[_BulkReportQueryItemT]):
+                The list of bulk report data items.
+        """
+        super().__init__(data=data)
+
+
+_BulkReportQueryResultT = TypeVar(
+    "_BulkReportQueryResultT", bound=BulkReportQueryResult[Any]
+)

src/gfwapiclient/resources/bulk_downloads/query/models/fixed_infrastructure_data/__init__.py

@@ -0,0 +1,17 @@
+"""Global Fishing Watch (GFW) API Python Client - Query Bulk Fixed Infrastructure Data Models.
+
+This module defines Pydantic data models used for interacting with the Query Bulk
+Report API endpoint. These models are used to represent request parameters, and
+response data when querying data in JSON format of the previously created
+fixed infrastructure data (i.e `public-fixed-infrastructure-data:latest` dataset) bulk report.
+
+For detailed information about the Query Bulk Report - API endpoint, please refer to
+the official Global Fishing Watch API documentation:
+
+See: https://globalfishingwatch.org/our-apis/documentation#get-data-in-json-format
+
+For more details on the Query Bulk Report - data caveats, please refer to the
+official Global Fishing Watch API documentation:
+
+See: https://globalfishingwatch.org/our-apis/documentation#sar-fixed-infrastructure-data-caveats
+"""