added request_modifier hook to StacApiIO to enable AWS SigV4 signing

A modifier provides the ability to modify the request immediately before
sending, a requirement for AWS SigV4. This allows users to plug in
their signing method.

Also, added the `stac_io` parameter to `Client.open()` allowing for
easy usage of a custom `StacApiIO` instance.

Author: Joe Reed

CHANGELOG.md

@@ -10,6 +10,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ### Added
 
 - Python 3.11 support [#347](https://github.com/stac-utils/pystac-client/pull/347)
+- Added `modifier` to `StacApiIO` to allow for additional authentication mechanisms (e.g. AWS SigV4) [#371](https://github.com/stac-utils/pystac-client/issues/371).
 
 ### Changed
 

pystac_client/client.py

@@ -14,6 +14,7 @@
 import pystac
 import pystac.validation
 from pystac import CatalogType, Collection
+from requests import Request
 
 from pystac_client._utils import Modifiable, call_modifier
 from pystac_client.collection_client import CollectionClient
@@ -93,6 +94,8 @@ def open(
         parameters: Optional[Dict[str, Any]] = None,
         ignore_conformance: bool = False,
         modifier: Optional[Callable[[Modifiable], None]] = None,
+        request_modifier: Optional[Callable[[Request], Union[Request, None]]] = None,
+        stac_io: Optional[StacApiIO] = None,
     ) -> "Client":
         """Opens a STAC Catalog or API
         This function will read the root catalog of a STAC Catalog or API
@@ -128,12 +131,31 @@ def open(
                 After getting a child collection with, e.g.
                 :meth:`Client.get_collection`, the child items of that collection
                 will still be signed with ``modifier``.
+            request_modifier: A callable that eitehr modifies a `Request` instance or
+                returns a new one. This can be useful for injecting Authentication
+                headers and/or signing fully-formed requests (e.g. signing requests
+                using AWS SigV4).
+
+                The callable should expect a single argument, which will be an instance
+                of :class:`requests.Request`.
+
+                If the callable returns a `requests.Request`, that will be used.
+                Alternately, the calable may simply modify the provided request object
+                and return `None`.
+            stac_io: A `StacApiIO` object to use for I/O requests. Generally, leave
+                this to the default. However in cases where customized I/O processing
+                is required, a custom instance can be provided here.
 
         Return:
             catalog : A :class:`Client` instance for this Catalog/API
         """
         client: Client = cls.from_file(
-            url, headers=headers, parameters=parameters, modifier=modifier
+            url,
+            headers=headers,
+            parameters=parameters,
+            modifier=modifier,
+            request_modifier=request_modifier,
+            stac_io=stac_io,
         )
         search_link = client.get_search_link()
         # if there is a search link, but no conformsTo advertised, ignore
@@ -161,14 +183,19 @@ def from_file(  # type: ignore
         headers: Optional[Dict[str, str]] = None,
         parameters: Optional[Dict[str, Any]] = None,
         modifier: Optional[Callable[[Modifiable], None]] = None,
+        request_modifier: Optional[Callable[[Request], Union[Request, None]]] = None,
     ) -> "Client":
         """Open a STAC Catalog/API
 
         Returns:
             Client: A Client (PySTAC Catalog) of the root Catalog for this Catalog/API
         """
         if stac_io is None:
-            stac_io = StacApiIO(headers=headers, parameters=parameters)
+            stac_io = StacApiIO(
+                headers=headers,
+                parameters=parameters,
+                request_modifier=request_modifier,
+            )
 
         client: Client = super().from_file(href, stac_io)  # type: ignore
 

pystac_client/stac_api_io.py

@@ -2,7 +2,7 @@
 import logging
 import re
 from copy import deepcopy
-from typing import TYPE_CHECKING, Any, Dict, Iterator, List, Optional
+from typing import TYPE_CHECKING, Any, Callable, Dict, Iterator, List, Optional, Union
 from urllib.parse import urlparse
 
 import pystac
@@ -34,6 +34,7 @@ def __init__(
         headers: Optional[Dict[str, str]] = None,
         conformance: Optional[List[str]] = None,
         parameters: Optional[Dict[str, Any]] = None,
+        request_modifier: Optional[Callable[[Request], Union[Request, None]]] = None,
     ):
         """Initialize class for API IO
 
@@ -43,6 +44,10 @@ def __init__(
                 <https://github.com/radiantearth/stac-api-spec/blob/master/overview.md#conformance-classes>`__.
             parameters: Optional dictionary of query string parameters to
               include in all requests.
+            request_modifier: Optional callable that can be used to modify Request
+              objects before they are sent. If provided, the callable receives a
+              `request.Request` and must either modify the object directly or return
+              a new / modified request instance.
 
         Return:
             StacApiIO : StacApiIO instance
@@ -54,6 +59,8 @@ def __init__(
 
         self._conformance = conformance
 
+        self._req_modifier = request_modifier
+
     def read_text(self, source: pystac.link.HREF, *args: Any, **kwargs: Any) -> str:
         """Read text from the given URI.
 
@@ -132,7 +139,8 @@ def request(
                 params["intersects"] = json.dumps(params["intersects"])
             request = Request(method="GET", url=href, headers=headers, params=params)
         try:
-            prepped = self.session.prepare_request(request)
+            modified = self._req_modifier(request) if self._req_modifier else None
+            prepped = self.session.prepare_request(modified or request)
             msg = f"{prepped.method} {prepped.url} Headers: {prepped.headers}"
             if method == "POST":
                 msg += f" Payload: {json.dumps(request.json)}"

tests/test_stac_api_io.py

@@ -1,3 +1,4 @@
+import typing
 from pathlib import Path
 from urllib.parse import parse_qs, urlsplit
 
@@ -85,6 +86,52 @@ def test_custom_headers(self, requests_mock: Mocker) -> None:
         assert header_name in history[0].headers
         assert history[0].headers[header_name] == header_value
 
+    def test_modifier(self, requests_mock: Mocker) -> None:
+        """Verify the modifier is correctly called with a returned object."""
+        header_name = "x-my-header"
+        header_value = "Some Value"
+        url = "https://some-url.com/some-file.json"
+
+        def custom_modifier(request: typing.Any) -> typing.Union[typing.Any, None]:
+            request.headers["x-pirate-name"] = "yellowbeard"
+            return request
+
+        stac_api_io = StacApiIO(
+            headers={header_name: header_value}, request_modifier=custom_modifier
+        )
+
+        requests_mock.get(url, status_code=200, json={})
+
+        stac_api_io.read_json(url)
+
+        history = requests_mock.request_history
+        assert len(history) == 1
+        assert header_name in history[0].headers
+        assert history[0].headers["x-pirate-name"] == "yellowbeard"
+
+    def test_modifier_noreturn(self, requests_mock: Mocker) -> None:
+        """Verify the modifier is correctly called when None is returned."""
+        header_name = "x-my-header"
+        header_value = "Some Value"
+        url = "https://some-url.com/some-file.json"
+
+        def custom_modifier(request: typing.Any) -> typing.Union[typing.Any, None]:
+            request.headers["x-pirate-name"] = "yellowbeard"
+            return None
+
+        stac_api_io = StacApiIO(
+            headers={header_name: header_value}, request_modifier=custom_modifier
+        )
+
+        requests_mock.get(url, status_code=200, json={})
+
+        stac_api_io.read_json(url)
+
+        history = requests_mock.request_history
+        assert len(history) == 1
+        assert header_name in history[0].headers
+        assert history[0].headers["x-pirate-name"] == "yellowbeard"
+
     def test_custom_query_params(self, requests_mock: Mocker) -> None:
         """Checks that query params passed to the init method are added to requests."""
         init_qp_name = "my-param"