prescient-sdk 0.1.0__py3-none-any.whl

prescient_sdk/client.py

@@ -0,0 +1,206 @@
+import logging
+import datetime
+import urllib.parse
+
+import msal
+import boto3
+from rasterio.session import AWSSession
+
+from prescient_sdk.config import Settings
+
+logger = logging.getLogger("prescient_sdk")
+
+
+class PrescientClient:
+    """
+    Client for interacting with the Prescient API.
+
+    This client is used to authenticate using Azure AD, and for obtaining AWS
+    credentials using the Azure AD access token. The client also provides helpers such as
+    provding the STAC URL for the Prescient API, and authentication headers for making
+    requests to the STAC API.
+
+    Token expiration (both AWS and Azure) is handled automatically for long running instances
+    of the client (in a notebook for example).
+
+    Default configuration is set using the default values from prescient_sdk.config.
+    These can be overridden by setting values explicitly when initializing the client.
+
+    Args:
+        settings (Settings, optional): Configuration settings for the client. Defaults to None.
+
+    """
+
+    def __init__(
+        self,
+        settings: Settings | None = None,
+    ):
+        # default configuration values are set in the Settings class (prescient_sdk.config)
+        if settings is None:
+            settings = Settings()  # type: ignore
+        self.settings: Settings = settings
+
+        # initialize empty credentials
+        self._azure_credentials: dict = {}
+        self._aws_credentials: dict = {}
+
+    @property
+    def stac_catalog_url(self) -> str:
+        """
+        Get the STAC URL.
+
+        Returns:
+            str: The STAC URL.
+        """
+        return urllib.parse.urljoin(self.settings.endpoint_url, "stac")
+
+    @property
+    def azure_credentials(self) -> dict:
+        """
+        Get the Azure credentials for the client.
+
+        Returns:
+            dict: Azure access token::
+
+                {
+                    "token_type": "string",
+                    "scope": "string",
+                    "expires_in": "int",
+                    "ext_expires_in": "int",
+                    "access_token": "string",
+                    "refresh_token": "string",
+                    "id_token": "string",
+                    "client_info": "string",
+                    "id_token_claims": {
+                        "aud": "string",
+                        "iss": "string",
+                        "iat": "int",
+                        "nbf": "int",
+                        "exp": "int",
+                        "aio": "string",
+                        "name": "string",
+                        "nonce": "string",
+                        "oid": "string",
+                        "preferred_username": "string",
+                        "rh": "string",
+                        "roles": ["string"],
+                        "sub": "string",
+                        "tid": "string",
+                        "uti": "string",
+                        "ver": "string",
+                    },
+                    "token_source": "string",
+                }
+        Raises:
+            ValueError: If the response status code is not 200, or if the access token is not in the response.
+        """
+        # return cached credentials if they exist and are not expired
+        if "expiration" in self._azure_credentials and (
+            datetime.datetime.now(datetime.timezone.utc)
+            < self._azure_credentials["expiration"]
+        ):
+            return self._azure_credentials
+
+        authority_url = urllib.parse.urljoin(
+            self.settings.azure_auth_url, self.settings.azure_tenant_id
+        )
+        app = msal.PublicClientApplication(
+            client_id=self.settings.azure_client_id, authority=authority_url
+        )
+
+        # trigger auth or auth refresh flow
+        time_zero = datetime.datetime.now(datetime.timezone.utc)
+        if not self._azure_credentials:
+            # aquire creds interactively if none have been fetched yet
+            self._azure_credentials = app.acquire_token_interactive(scopes=[])
+        else:
+            # refresh creds if they have been fetched before and are expired
+            self._azure_credentials = app.acquire_token_by_refresh_token(
+                refresh_token=self._azure_credentials["refresh_token"], scopes=[]
+            )
+
+        # check that a nonzero length token has been obtained
+        token: str = self._azure_credentials.get("id_token", "")
+        if token == "":
+            raise ValueError(f"Failed to obtain Azure token: {self._azure_credentials}")
+
+        # set expiration time of the token
+        self._azure_credentials["expiration"] = time_zero + datetime.timedelta(
+            seconds=self._azure_credentials["expires_in"]
+        )
+
+        return self._azure_credentials
+
+    @property
+    def headers(self) -> dict:
+        """
+        Get headers for a request, including the auth header with a bearer token.
+
+        Returns:
+            dict: The headers.
+        """
+        return {
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+            "Authorization": f"Bearer {self.azure_credentials['id_token']}",
+        }
+
+    @property
+    def aws_credentials(self):
+        """Get AWS credentials using Azure AD access token
+
+        Returns:
+            dict: AWS temporary credentials::
+
+                {
+                    "AccessKeyId": "string",
+                    "SecretAccessKey": "string",
+                    "SessionToken": "string",
+                    "Expiration": datetime(2015, 1, 1)
+                }
+
+        Raises:
+            ValueError: If the AWS credentials response is empty
+        """
+        if (
+            "Expiration" in self._aws_credentials
+            and datetime.datetime.now(datetime.timezone.utc)
+            < self._aws_credentials["Expiration"]
+        ):
+            return self._aws_credentials
+
+        access_token = self.azure_credentials.get("id_token")
+        sts_client = boto3.client("sts", region_name=self.settings.aws_region)
+
+        # exchange token with aws temp creds
+        response: dict = sts_client.assume_role_with_web_identity(
+            DurationSeconds=3600,  # 1 hour
+            RoleArn=self.settings.aws_role,
+            RoleSessionName="prescient-s3-access",
+            WebIdentityToken=access_token,
+        )
+        self._aws_credentials = response.get("Credentials", {})
+
+        if not self._aws_credentials:
+            raise ValueError(f"Failed to obtain AWS creds: {response}")
+
+        # convert datetime to UTC for later comparison
+        self._aws_credentials["Expiration"] = self._aws_credentials[
+            "Expiration"
+        ].astimezone(datetime.timezone.utc)
+
+        return self._aws_credentials
+    
+    @property
+    def session(self) -> AWSSession:
+        """
+        Get an AWS session to be used when authenticating rasterio
+
+        Returns:
+            AWSSession: Rasterio AWS session
+        """
+        return AWSSession(
+            aws_access_key_id=self.aws_credentials["AccessKeyId"], 
+            aws_secret_access_key=self.aws_credentials["SecretAccessKey"], 
+            aws_session_token=self.aws_credentials["SessionToken"]
+        )

prescient_sdk/config.py

@@ -0,0 +1,33 @@
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from pydantic import Field
+
+
+class Settings(BaseSettings):
+    """
+    Default configuration for the Prescient SDK.
+
+    Configuration is handled using [pydantic-settings](https://docs.pydantic.dev/latest/concepts/pydantic_settings/)
+
+    Order of precedence for configuration values:
+
+    1. Environment variables are always highest precedence and will override any other configuration values
+    2. `.env` file: if a `.env` file is present in the root of the project, it will be used
+    """
+
+    endpoint_url: str = Field()
+    
+    aws_region: str = Field()
+    aws_role: str = Field(min_length=20)
+
+    azure_tenant_id: str
+    azure_client_id: str
+    azure_auth_url: str
+    azure_auth_token_path: str
+
+    model_config = SettingsConfigDict(
+        env_file="config.env",
+        env_file_encoding="utf-8",
+        env_prefix="PRESCIENT_",
+        case_sensitive=False,
+    )

prescient_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.3
+Name: prescient-sdk
+Version: 0.1.0
+Summary: A Python SDK for integrating with Prescient services
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: boto3>=1.35.19
+Requires-Dist: msal>=1.31.0
+Requires-Dist: pydantic-settings>=2.5.2
+Description-Content-Type: text/markdown
+
+# prescient-sdk
+A Python SDK for integrating with Prescient services
+
+
+# Quickstart
+
+## Local Development
+
+The project is set up using [uv](https://docs.astral.sh/uv/) for package management. To develop locally:
+
+1. Install uv following [these](https://docs.astral.sh/uv/getting-started/installation/) intructions
+
+1. (Optional) Use uv to set up your local env. 
+
+    Note that this will happen automatically when you run tests or any python application using uv, so it is not necessary
+
+    ```
+    uv sync
+    ```
+
+1. Run the tests
+
+    ```
+    uv run pytest
+    ```
+
+    or 
+
+    ```
+    make run-tests
+    ```
+
+## Configuration
+
+Configuration methods are discussed in the Jupyter Notebook [configuration.ipynb](./docs/examples/configuration.ipynb)
+
+## Code Formatting/Linting
+
+Code format is set using the [Ruff](https://docs.astral.sh/ruff/) formatter. To run this formatter:
+
+```
+make format
+```
+
+## Adding or removing dependencies
+
+Add or remove dependencies using [UV](https://docs.astral.sh/uv/concepts/dependencies/).
+
+In the simplest case, you can add a new dependency like this:
+
+```
+uv add <some-dependency>
+```
+
+To add a dev dependency:
+
+```
+uv add <some-dependency> --dev
+```
+
+To remove a dependency:
+
+```
+uv remove <some-dependency>
+```
+
+For more complex features, see the [uv documentation](https://docs.astral.sh/uv/)
+
+## Build the documentation
+
+Public facing documentation is built using [jupyter-books](https://jupyterbook.org/en/stable/intro.html).
+
+The [docs](./docs) folder contains the layout for the public facing documentation.
+
+You can build the documentation locally, and access the built html pages in a local browser:
+
+1. Build the docs:
+
+    ```
+    make build-docs
+    ```
+
+1. Open the html in a browser:
+
+    After building the docs, the path to the index.html file will be logged, and should look something like `docs/_build/html/index.html`

prescient_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+prescient_sdk/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+prescient_sdk/client.py,sha256=7o6vP67-evUSYhhI_ZktdRrXJUNRPTBYnHC9VzQOgcA,7141
+prescient_sdk/config.py,sha256=kKSMqtst7yvs02tszGk1ejcjSpinpIfztbCphvG9Q34,947
+prescient_sdk-0.1.0.dist-info/METADATA,sha256=jfS3BAnzQLsFD3SwtFRCvSH9LMw6wJMjFcGlLzIzvJI,2180
+prescient_sdk-0.1.0.dist-info/WHEEL,sha256=1yFddiXMmvYK7QYTqtRNtX66WJ0Mz8PYEiEUoOUUxRY,87
+prescient_sdk-0.1.0.dist-info/licenses/LICENSE,sha256=XSE_ZgGPmTkM8I6i2rJMIXsgMAJlaQh2qdNe5u7v0S4,1069
+prescient_sdk-0.1.0.dist-info/RECORD,,

prescient_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.25.0
+Root-Is-Purelib: true
+Tag: py3-none-any

prescient_sdk-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 sparkgeo.com
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.