improve and add http Result utilities and protocols

.github/workflows/ci.yaml

@@ -20,11 +20,11 @@ jobs:
     steps:
     - name: Checkout codes
       id: checkout-codes
-      uses: actions/checkout@v4.2.2
+      uses: actions/checkout@v7.0.0
 
     - name: Setup python
       id: setup-python
-      uses: actions/setup-python@v5.4.0
+      uses: actions/setup-python@v6.3.0
       with:
         python-version: ${{ matrix.python-version }}
         architecture: x64
@@ -43,7 +43,7 @@ jobs:
 
     - name: Upload coverage reports to Codecov
       id: upload-coverage-reports-to-codecov
-      uses: codecov/codecov-action@v5.3.1
+      uses: codecov/codecov-action@v7.0.0
       if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
       with:
         token: ${{ secrets.CODECOV_TOKEN }}

.github/workflows/pre-commit.yaml

@@ -14,11 +14,11 @@ jobs:
     steps:
     - name: Checkout codes
       id: checkout-codes
-      uses: actions/checkout@v4.2.2
+      uses: actions/checkout@v7.0.0
 
     - name: Setup python
       id: setup-python
-      uses: actions/setup-python@v5.4.0
+      uses: actions/setup-python@v6.3.0
       with:
         python-version: 3.12.8
         architecture: x64

src/gfwapiclient/http/models/response.py

@@ -4,18 +4,22 @@
     Any,
     Callable,
     Generic,
+    Iterable,
     Iterator,
     List,
     Optional,
     Set,
     Type,
     TypeVar,
     Union,
+    cast,
 )
 
 import geopandas as gpd
 import pandas as pd
 
+from pydantic import BaseModel as PydanticBaseModel
+
 from gfwapiclient.base.models import BaseModel
 
 
@@ -38,6 +42,7 @@ class ResultItem(BaseModel):
 
 
 _ResultItemT = TypeVar("_ResultItemT", bound=ResultItem)
+_ResultItemMappedT = TypeVar("_ResultItemMappedT")
 
 
 class Result(Generic[_ResultItemT]):
@@ -186,6 +191,104 @@ def find(
 
         return None
 
+    def map(
+        self,
+        *,
+        mapper: Callable[[_ResultItemT], _ResultItemMappedT],
+    ) -> Iterator[_ResultItemMappedT]:
+        """Transforms each API endpoint result data using a mapping function.
+
+        This method applies `mapper` to every `ResultItem` and returns an `Iterator`
+        yielding the transformed `_ResultItemMappedT`.
+
+        Args:
+            mapper (Callable[[_ResultItemT], _ResultItemMappedT]):
+                A callable that transforms a `ResultItem` instance and
+                returns transformed `_ResultItemMappedT` instance.
+
+        Yields:
+            _ResultItemMappedT:
+                Individual transformed `_ResultItemMappedT` from API endpoint result data.
+
+        Raises:
+            TypeError:
+                If `mapper` is not callable.
+        """
+        if not callable(mapper):
+            raise TypeError("Expected `mapper` to be callable.")
+
+        for item in self._iter_data():
+            yield mapper(item)
+
+    def flat_map(
+        self,
+        *,
+        mapper: Callable[
+            [_ResultItemT], Union[_ResultItemMappedT, Iterable[_ResultItemMappedT]]
+        ],
+    ) -> Iterator[_ResultItemMappedT]:
+        """Transforms and flattens API endpoint result data using a mapping function.
+
+        This method applies `mapper` to every `ResultItem`, recursively flattens
+        iterable values returned by the `mapper`, and yielding the transformed `_ResultItemMappedT`.
+
+        Unlike :meth:`map`, which yields the mapper output directly, `flat_map`
+        expands nested collections into a single iterator of values.
+
+        Iterable values are flattened when they represent collections, including:
+
+        - `list`
+        - `tuple`
+        - `set`
+        - generators
+        - iterators
+        - other non-atomic iterable objects
+
+        Atomic values are yielded unchanged. The following objects are treated as
+        scalar values and are not expanded:
+
+        - `str`
+        - `bytes`
+        - `dict`
+        - `None`
+        - :class:`PydanticBaseModel` instances
+        - :class:`BaseModel` instances
+        - :class:`ResultItem` instances
+
+        Args:
+            mapper (Callable[[_ResultItemT], Union[_ResultItemMappedT, Iterable[_ResultItemMappedT]]]):
+                A callable that transforms a `ResultItem` instance and
+                returns either transformed single or iterable of
+                `_ResultItemMappedT` instance.
+
+        Yields:
+            _ResultItemMappedT:
+                Individual transformed-flattened `_ResultItemMappedT` from API endpoint
+                result data produced by the mapper.
+
+        Raises:
+            TypeError:
+                If `mapper` is not callable.
+        """
+        if not callable(mapper):
+            raise TypeError("Expected `mapper` to be callable.")
+
+        def _yield_values(
+            value: object,
+        ) -> Iterator[_ResultItemMappedT]:
+            """Recursively yields flattened values from nested iterables."""
+            if isinstance(value, Iterable) and not isinstance(
+                value,
+                (str, bytes, dict, ResultItem, BaseModel, PydanticBaseModel),
+            ):
+                for nested_value in value:
+                    yield from _yield_values(nested_value)
+            else:
+                yield cast(_ResultItemMappedT, value)
+
+        for item in self._iter_data():
+            yield from _yield_values(mapper(item))
+
     def _iter_data(self) -> Iterator[_ResultItemT]:
         """Iterate lazily over API endpoint result data without copying.
 
@@ -199,15 +302,56 @@ def _iter_data(self) -> Iterator[_ResultItemT]:
         Yields:
             _ResultItemT:
                 Individual `ResultItem` contained in API endpoint result data.
-
-        Returns:
-            Iterator[_ResultItemT]:
-                An iterator over API endpoint result data.
         """
         if isinstance(self._data, list):
             yield from self._data
         else:
             yield self._data
 
+    def __iter__(self) -> Iterator[_ResultItemT]:
+        """Returns an iterator over API endpoint result data.
+
+        Yields:
+            _ResultItemT:
+                Individual `ResultItem` contained in API endpoint result data.
+        """
+        yield from self._iter_data()
+
+    def __len__(self) -> int:
+        """Returns total number of items in API endpoint result data.
+
+        Returns:
+            int:
+                The total number of items in API endpoint result data.
+        """
+        if isinstance(self._data, list):
+            return len(self._data)
+
+        return 1
+
+    def __add__(self, other: object) -> "Result[_ResultItemT]":
+        """Concatenates API endpoint result data with items from another iterable.
+
+        This method returns a new `Result` instance containing combined
+        `ResultItem` objects.
+
+        Args:
+            other (object):
+                Iterable of `ResultItem` to append to API endpoint result data.
+
+        Returns:
+            Result[_ResultItemT]:
+                A new `Result` instance containing the combined `ResultItem` objects.
+
+        Raises:
+            TypeError:
+                If `other` is not iterable.
+        """
+        if isinstance(other, Iterable):
+            combined_items: List[_ResultItemT] = [*self._iter_data(), *other]
+            return self.__class__(data=combined_items)
+
+        return NotImplemented
+
 
 _ResultT = TypeVar("_ResultT", bound=Result[Any])