maxar-platform 1.0.0__tar.gz

maxar_platform-1.0.0/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Maxar Intelligence
+
+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.

maxar_platform-1.0.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.1
+Name: maxar-platform
+Version: 1.0.0
+Summary: Maxar Geospatial Platform SDK
+License: MIT
+Author: Marc Pfister
+Author-email: marc.pfister@maxar.com
+Requires-Python: >=3.9,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Provides-Extra: rasterio
+Requires-Dist: OWSLib (>=0.29.3,<0.30.0)
+Requires-Dist: affine (>=2.4.0,<3.0.0)
+Requires-Dist: pendulum (>=3.0.0,<4.0.0)
+Requires-Dist: pygeofilter (>=0.2.1,<0.3.0)
+Requires-Dist: pyproj (>=3.6.1,<4.0.0)
+Requires-Dist: pystac-client (>=0.7.5,<0.8.0)
+Requires-Dist: pytest-coverage (>=0.0,<0.1)
+Requires-Dist: rasterio (>=1.3.9,<2.0.0) ; extra == "rasterio"
+Requires-Dist: requests (>=2.31.0,<3.0.0)
+Requires-Dist: requests-oauthlib (>=2.0.0,<3.0.0)
+Project-URL: Documentation, https://developers.maxar.com/docs/developer-tools/python-sdk
+Description-Content-Type: text/markdown
+
+# maxar-platform
+
+A Python SDK for working with [Maxar Geospatial Platform](https://pro.maxar.com/)
+
+Version: 1.0.0
+
+## Introduction
+
+`maxar-platform` provides wrappers around the MGP APIs with a focus on simplicity and productivity. It wraps popular and proven Python geospatial packages whenever possible, but also offers a core HTTP session object to use as a basis for more custom functionality.
+
+### APIs supported:
+
+#### Discovery
+
+Discovery is Maxar's catalog API. `maxar_platform` extends `pystac-client` to provide STAC search to the user.
+
+#### Streaming APIs (OGC)
+
+[`owslib`](https://owslib.readthedocs.io/en/latest/) methods are available for OGC access to imagery and image footprint OGC endpoints. In addition, `maxar-platform` provides a search client with a similar interface to the Discovery module that queries the images available from these endpoints
+
+#### Ordering, Monitoring, and Tasking APIs
+
+These endpoints can be accessed through matching modules and functions.
+
+#### Raster Analytics
+
+Open any image available in Raster Analytics with `rasterio` as if the image was a Cloud Optimized Geotiff. Pixel data is generated on-the-fly.
+
+#### Authentication
+
+An underlying `session` object handles authentication and communication with the APIs. Also included is a module for managing API Keys.
+
+## Installation
+
+`pip install maxar-platform`
+
+To use the Raster Analytics module, you will also need to install [`rasterio`](https://rasterio.readthedocs.io/en/stable/).
+
+## Documentation
+
+See the [MGP Developer Site](https://developers.maxar.com/docs/developer-tools/python-sdk)
+

maxar_platform-1.0.0/README.md

@@ -0,0 +1,41 @@
+# maxar-platform
+
+A Python SDK for working with [Maxar Geospatial Platform](https://pro.maxar.com/)
+
+Version: 1.0.0
+
+## Introduction
+
+`maxar-platform` provides wrappers around the MGP APIs with a focus on simplicity and productivity. It wraps popular and proven Python geospatial packages whenever possible, but also offers a core HTTP session object to use as a basis for more custom functionality.
+
+### APIs supported:
+
+#### Discovery
+
+Discovery is Maxar's catalog API. `maxar_platform` extends `pystac-client` to provide STAC search to the user.
+
+#### Streaming APIs (OGC)
+
+[`owslib`](https://owslib.readthedocs.io/en/latest/) methods are available for OGC access to imagery and image footprint OGC endpoints. In addition, `maxar-platform` provides a search client with a similar interface to the Discovery module that queries the images available from these endpoints
+
+#### Ordering, Monitoring, and Tasking APIs
+
+These endpoints can be accessed through matching modules and functions.
+
+#### Raster Analytics
+
+Open any image available in Raster Analytics with `rasterio` as if the image was a Cloud Optimized Geotiff. Pixel data is generated on-the-fly.
+
+#### Authentication
+
+An underlying `session` object handles authentication and communication with the APIs. Also included is a module for managing API Keys.
+
+## Installation
+
+`pip install maxar-platform`
+
+To use the Raster Analytics module, you will also need to install [`rasterio`](https://rasterio.readthedocs.io/en/stable/).
+
+## Documentation
+
+See the [MGP Developer Site](https://developers.maxar.com/docs/developer-tools/python-sdk)

maxar_platform-1.0.0/maxar_platform/__init__.py

@@ -0,0 +1,32 @@
+"""
+Provides
+--------
+
+Streamlined access to these Maxar Geospatial Platform APIs:
+
+- Authentication
+- Discovery Catalog
+- OGC Image streaming, vectors, and metadata
+- Ordering
+- Monitoring
+- Tasking
+- Raster Analytics
+
+Coming soon:
+
+- 3D Analytics
+- Change Monitoring
+
+Reference
+---------
+
+https://developers.maxar.com/
+"""
+
+__version__ = "1.0.0"
+
+import os
+
+BASE_URL = os.environ.get("MGP_BASE_URL") or "https://api.maxar.com/"
+CLIENT_ID = os.environ.get("MAXAR_CLIENT_ID") or "mgp"
+PACKAGE = "maxar_platform"

maxar_platform-1.0.0/maxar_platform/api_keys.py

@@ -0,0 +1,179 @@
+"""
+API keys are an alternative to OAuth2 authentication.
+
+They are more compact than OAuth2 bearer tokens which makes them easier to send as URL parameters.
+
+Unlike bearer tokens which expire in two hours, API keys have a default 6 month lifespan. It is also possible to
+set the expiration date as short as needed. API keys can not be renewed or extended, once they expire a new one must
+be created.
+
+API keys have the same roles and scopes as your account but can not be used on any of the administrative endpoints:
+
+- Admin API
+- API Key Service
+- Oauth2 Authentication
+
+API Key dictionaries use a custom representations that mask out the API key string when they are displayed/printed.
+
+    >>> key = generate_key("my key")
+    >>> print(key)
+
+    {'id': '5431dd15-3efe-418a-b04d-acdca3a4d281',
+     'name': 'my key',
+     'description': '',
+     'api_key': '*******',
+     'last_modified_date': '2023-07-20 19:44:07',
+     'created_date': '2023-07-20 19:44:07',
+     'expiration_date': '2024-03-12 18:33:23'}
+
+The `api_key` value is not otherwise masked, be careful with:
+
+    >>> print(key['api_key'])
+    <your key will print out!>
+
+
+Reference
+---------
+
+https://developers.maxar.com/docs/authentication/guides/api-key
+
+"""
+
+import pprint
+from posixpath import join
+
+import pendulum
+
+from maxar_platform import BASE_URL
+from maxar_platform.exceptions import MissingAPIResource
+from maxar_platform.session import session
+
+__all__ = ["generate_key", "list_keys", "delete_key", "get_key"]
+
+
+KEYS_URL = join(BASE_URL, "api-key/api/v2/api-key")
+KEYS_KEY = join(KEYS_URL, "id/:id")
+
+
+def generate_key(name="", description="", expiration=None, lifespan=None):
+    """Generate a new API key
+
+    Keywords
+    ----------
+    name: str, optional
+        Name of key, while optional highly recommended.
+    description: str, optional
+        Description of key.
+    expiration: datelike object
+        Expiration date. Can be Date or Datetime objects, or strings of dates in common formats. Maximum lifespan is 6 months.
+    lifespan: int
+        Lifespan of keys in days if you don't want to compute an expiration date.
+
+    Returns
+    -------
+    KeyDict
+        Key as Python dictionary with special `str` and `repr` methods to mask keys from accidental display.
+
+    """
+
+    expires_format = "YYYY-MM-DD HH:mm:ss"
+
+    payload = {"name": name, "description": description}
+
+    if expiration and lifespan:
+        raise ValueError("Tokens can be given an `expiration` OR a `lifespan`, not both")
+
+    if expiration:
+        expires = pendulum.parse(expiration)
+        payload["expiration_date"] = expires.format(expires_format)
+
+    if lifespan:
+        expires = pendulum.now().add(days=lifespan)
+        payload["expiration_date"] = expires.format(expires_format)
+
+    return KeyDict(session.oauth_session.post(KEYS_URL, json=payload).json())
+
+
+def list_keys():
+    """List keys associated with your user
+
+    Returns
+    -------
+    list of KeyDict
+        All of user's keys, including expired ones
+
+    """
+    return [KeyDict(k) for k in session.oauth_session.get(KEYS_URL).json()]
+
+
+def delete_key(key_or_id):
+    """Delete an API key
+
+    Parameters
+    ----------
+    key: KeyDict or str
+        Either a key dictionary, or a key's ID string
+
+    Returns
+    -------
+    None
+
+    Note
+    ----
+    A key's ID is the 'id' value, not the 'api_key' value that is used for authentication.
+
+
+    """
+    if isinstance(key_or_id, dict):
+        key_id = key_or_id["id"]
+    else:
+        key_id = key_or_id
+    url = KEYS_KEY.replace(":id", key_id)
+    try:
+        session.oauth_session.delete(url)
+    except MissingAPIResource:
+        raise MissingAPIResource(f"API Key with ID {key_id} was not found")
+
+
+def get_key(**kwargs):
+    """Get a key
+
+    Keywords
+    ----------
+    id: str, optional
+    name: str, optional
+    description: str, optional
+    api_key: str, optional
+
+    Returns
+    -------
+    KeyDict
+        The first key found matching the supplied keyword arguments.
+
+    Note
+    ----
+    You can match to any ONE of the KeyDict fields, however in most cases you would use ID or name.
+    Matching is exact, there is no support for wildcards or other regex magic at this time.
+
+    """
+    if len(kwargs) > 1:
+        raise ValueError("API keys can only be retrieved on a single property")
+    for k, v in kwargs.items():
+        for key in list_keys():
+            if key[k] == v:
+                return KeyDict(key)
+    raise MissingAPIResource(f"API Key with {k} `{v}` was not found")
+
+
+class KeyDict(dict):
+    """A dictionary class for keys that masks the key value when printed or displayed"""
+
+    def __str__(self):
+        masked = self.copy()
+        masked["api_key"] = "**************"
+        return pprint.pformat(masked, sort_dicts=False)
+
+    def __repr__(self):
+        masked = self.copy()
+        masked["api_key"] = "*******"
+        return str(masked)

maxar_platform-1.0.0/maxar_platform/discovery.py

@@ -0,0 +1,163 @@
+""" Discovery API
+
+Discovery is Maxar's data catalog. Since it implements STAC API, this SDK uses `pystac_client` for access.
+
+For search, open a catalog or subcatalog to get a STAC client.
+
+
+    from maxar_platform.discovery import open_catalog
+    open_catalog() # returns the root catalog, or pass a subcatalog name like "imagery"
+    results = stac_api_client.search(...)
+
+
+Reference
+---------
+https://developers.maxar.com/docs/discovery/
+
+https://pystac-client.readthedocs.io/en/latest/usage.html#itemsearch
+
+"""
+
+import json
+import logging
+from copy import deepcopy
+from posixpath import join
+
+from pygeofilter.backends.cql2_json import to_cql2
+from pygeofilter.parsers.cql2_text import parse as cql2_parse
+from pystac_client import Client
+from pystac_client.exceptions import APIError
+from pystac_client.stac_api_io import StacApiIO
+
+from maxar_platform import BASE_URL
+from maxar_platform.session import session
+
+logger = logging.getLogger(__name__)
+
+from typing import Any, Dict, Optional
+
+DISCOVERY_URL = join(BASE_URL, "discovery/v1/")
+DISCOVERY_CATALOG = join(DISCOVERY_URL, "catalogs/:subCatalogId")
+
+__all__ = ["stac_api_client", "open_catalog"]
+
+
+class MaxarStacApiIO(StacApiIO):
+
+    area_based_calc = False
+
+    def request(
+        self,
+        href: str,
+        method: Optional[str] = None,
+        headers: Optional[Dict[str, str]] = None,
+        parameters: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        """Makes a request to an http endpoint
+
+        Args:
+            href (str): The request URL
+            method (Optional[str], optional): The http method to use, 'GET' or 'POST'.
+              Defaults to None, which will result in 'GET' being used.
+            headers (Optional[Dict[str, str]], optional): Additional headers to include
+                in request. Defaults to None.
+            parameters (Optional[Dict[str, Any]], optional): parameters to send with
+                request. Defaults to None.
+
+        Raises:
+            APIError: raised if the server returns an error response
+
+        Return:
+            str: The decoded response from the endpoint
+
+        Note:
+            This follows the default StacApiIO call but uses the SDK's session object. It also converts
+            cql2 text queries to json since the Discovery API currently doesn't accept text queries in
+            POST queries.
+        """
+        if method == "POST":
+            if parameters.get("filter-lang") == "cql2-text":
+                ast = cql2_parse(parameters["filter"])
+                parameters["filter"] = json.loads(to_cql2(ast))
+                parameters["filter-lang"] = "cql2-json"
+            if self.area_based_calc and parameters:
+                if "bbox" in parameters or "intersects" in parameters:
+                    parameters.update({"area-based-calc": True})
+            resp = session.post(url=href, headers=headers, json=parameters)
+        else:
+            params = deepcopy(parameters) or {}
+            if self.area_based_calc and parameters:
+                if "bbox" in parameters or "intersects" in parameters:
+                    params.update({"area-based-calc": 1})
+            resp = session.get(url=href, headers=headers, params=params)
+        try:
+            return resp.content.decode("utf-8")
+        except Exception as err:
+            raise APIError(str(err))
+
+
+def open_catalog(catalog=None):
+    """Open a pystac_client connection to a Discovery catalog
+
+    Parameters
+    ----------
+    catalog : str, default None
+        Catalog or subcatalog name to open, i.e. "imagery". If omitted the root catalog is used.
+
+    Returns
+    -------
+    pystac_client.Client
+        A Client object, configured to use Maxar authentication and area-based calculations
+
+    Reference
+    ---------
+    https://pystac-client.readthedocs.io/en/latest/api.html#collection-client"""
+
+    if not catalog:
+        url = DISCOVERY_URL
+    else:
+        url = DISCOVERY_CATALOG.replace(":subCatalogId", catalog)
+
+    client = Client.open(url, stac_io=MaxarStacApiIO())
+
+    def abc_getter(self):
+        return self._stac_io.area_based_calc
+
+    def abc_setter(self, val):
+        if type(val) is not bool:
+            raise ValueError("Value must be a boolean")
+        self._stac_io.area_based_calc = val
+
+    setattr(
+        client.__class__,
+        "area_based_calc",
+        property(abc_getter, abc_setter, doc="Return metadata with area-based calculations"),
+    )
+
+    return client
+
+
+stac_api_client = open_catalog()
+""" A pre-configured `pystac-client` instance ready to search the root catalog.
+
+
+    Attributes
+    ----------
+    area_based_calc : Bool
+        Toggles area-based calculations, default is False
+
+    Reference
+    ---------
+    https://pystac-client.readthedocs.io/en/latest/api.html#collection-client """
+
+
+# This is handy for certain searches
+CATID_TO_COLLECTION = {
+    "1010": "qb01",
+    "1020": "wv01",
+    "1030": "wv02",
+    "1040": "wv03-vnir",
+    "104A": "wv03-swir",
+    "1050": "ge01",
+    "1060": "ik02",
+}

maxar_platform-1.0.0/maxar_platform/exceptions.py

@@ -0,0 +1,124 @@
+""" SDK Exceptions """
+
+from datetime import datetime
+
+__all__ = [
+    "MissingDependency",
+    "APIServerException",
+    "BadAPIRequest",
+    "MissingAPIResource",
+    "OversizeRequestException",
+    "UnAuthorizedException",
+]
+
+#########
+# General Errors
+#########
+
+
+class MissingDependency(Exception):
+    """A dependency required for this functionality has not been installed"""
+
+    pass
+
+
+#########
+# API Errors
+#########
+
+
+class APIServerException(Exception):
+    """The API service encountered an error"""
+
+    def __init__(self, msg, *args, **kwargs):
+        msg = f"{msg} ({datetime.now()})"
+        super().__init__(msg, *args, **kwargs)
+
+
+class BadAPIRequest(Exception):
+    """The API request sent was incorrectly formatted"""
+
+    pass
+
+
+class MissingAPIResource(Exception):
+    """An API request returned a 404"""
+
+    pass
+
+
+class OversizeRequestException(Exception):
+    """The API request sent was incorrectly formatted"""
+
+    pass
+
+
+class UnAuthorizedException(Exception):
+    """The API request's credentials were rejected"""
+
+    pass
+
+
+########
+# Hook functions for Request.Session.hooks
+########
+
+
+def messenger(request):
+    try:
+        payload = request.json()
+        message = payload.get("message")
+        messages = payload.get("error").get("error_messages")
+        if messages:
+            messages = "; ".join(messages)
+        return message or messages or request.text
+    except:
+        return request.text
+
+
+def oversize_request_hook(r, *args, **kwargs):
+    """
+    Hook for handling oversize request errors from API.
+    """
+    if r.status_code == 413 and "Request Entity Too Large" in r.json()["message"]:
+        raise OversizeRequestException(f"{messenger(r)}, Reduce size of attributes and try again.")
+
+    return r
+
+
+def bad_api_request_hook(r, *args, **kwargs):
+    """
+    Hook for handling 400 errors from API.
+    """
+    if r.status_code == 400:
+        raise BadAPIRequest(messenger(r))
+    return r
+
+
+def unauth_request_hook(r, *args, **kwargs):
+    """
+    Hook for handling 401 errors from API.
+    """
+    if r.status_code in [401, 403]:
+        raise UnAuthorizedException(
+            f"Server responded with {r.status_code} '{messenger(r)}', check your credentials and try again."
+        )
+
+    return r
+
+
+def missing_resource_hook(r, *args, **kwargs):
+    if r.status_code == 404:
+        raise MissingAPIResource(messenger(r))
+
+    return r
+
+
+def api_server_request_hook(r, *args, **kwargs):
+    """
+    Hook for handling non-20X errors from API.
+    """
+    if not r.ok:
+        raise APIServerException(messenger(r))
+
+    return r