maxar-platform 1.0.0__py3-none-any.whl

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/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/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/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

maxar_platform/monitoring.py

@@ -0,0 +1,171 @@
+"""
+Provides
+--------
+
+Functions to maintain Monitors:
+
+- create and update a monitor
+- enable/disable a monitor
+- get one or list many monitors
+- see events that the monitor has matched
+
+Reference
+---------
+https://developers.maxar.com/docs/monitoring/
+"""
+
+from posixpath import join
+from typing import List, Union
+
+from maxar_platform import BASE_URL
+from maxar_platform.session import paginated_request, session
+
+__all__ = (
+    "create_monitor",
+    "get_monitor",
+    "disable_monitor",
+    "enable_monitor",
+    "update_monitor",
+    "list_monitors",
+    "list_monitor_events",
+)
+
+MONITORING_BASE = BASE_URL + "monitoring/v1/monitors"
+MONITORING_MONITOR = join(MONITORING_BASE, ":id")
+MONITORING_EVENTS = join(MONITORING_MONITOR, "events")
+MONITORING_ENABLE = join(MONITORING_MONITOR, "enable")
+MONITORING_DISABLE = join(MONITORING_MONITOR, "disable")
+
+
+def list_monitors(
+    limit=100,
+    sort="desc",
+    filter=None,
+):
+    """Fetch user's monitors
+
+    Parameters
+    ----------
+    limit: int or None, default None
+        Maximum number of orders to fetch, None means unlimited, default is 100.
+    sort: str
+        Sort order for order IDs, either 'asc' (ascending) or 'desc' (descending). Default is 'desc'.
+    filter: str or iterable of strings
+        Filter results using `field:value` syntax.
+        Matches are case sensitive and will match if the value is found anywhere in the field: filtering on a value of `description:NV` will return `Las Vegas, NV` along with `DENVER CO` descriptions.
+        Multiple filters can be passed but keys must be unique since filters will be logically ANDed.
+        Example: 'description:denver' or ['name:denver', 'description:parking']
+
+    Returns
+    -------
+    list
+        monitor objects matching parameters"""
+
+    params = {}
+
+    if filter is not None:
+        params["filter"] = filter
+
+    return paginated_request("GET", MONITORING_BASE, "monitors", sort, limit, **params)
+
+
+def get_monitor(monitor_id):
+    """Fetch raw data about a monitor from an ID
+
+    Parameters
+    ----------
+    monitor_id : str
+        Monitor ID to fetch metadata for
+
+    Returns
+    -------
+    dict
+        API data for the given monitor"""
+
+    url = MONITORING_MONITOR.replace(":id", monitor_id)
+    r = session.get(url)
+    return r.json()["data"]
+
+
+def create_monitor(monitor_payload):
+    """Create a new monitor
+
+    Parameters
+    ----------
+    monitor_payload : dict
+        Dictionary of monitor settings
+
+    Returns
+    -------
+    dict
+        Data for the monitor"""
+
+    r = session.post(MONITORING_BASE, json=monitor_payload)
+    return r.json()["data"]
+
+
+def update_monitor(monitor_id, monitor_payload):
+    """Update an existing monitor with new settings
+
+    Parameters
+    ----------
+    monitor_id : str
+        Monitor ID to fetch metadata for
+    monitor_payload : dict
+        Dictionary of updated fields for the existing monitor
+
+    Returns
+    -------
+    dict
+        Data for the updated monitor"""
+
+    url = MONITORING_MONITOR.replace(":id", monitor_id)
+    r = session.patch(url, json=monitor_payload)
+    return r.json()["data"]
+
+
+def list_monitor_events(monitor_id):
+    """Fetch the events for a monitor from an ID
+
+    Parameters
+    ----------
+    monitor_id : str
+        monitor ID to fetch events for
+
+    Returns
+    -------
+    list
+        Matched events for the given monitor"""
+
+    url = MONITORING_EVENTS.replace(":id", monitor_id)
+    return paginated_request("GET", url, "events", sort="desc")
+
+
+def disable_monitor(monitor_id):
+    """Disable a monitor
+
+    Parameters
+    ----------
+    monitor_id : str
+        monitor ID to disable
+
+    Returns
+    -------"""
+
+    url = MONITORING_DISABLE.replace(":id", monitor_id)
+    r = session.post(url)
+
+
+def enable_monitor(monitor_id):
+    """Enable a monitor
+
+    Parameters
+    ----------
+    monitor_id : str
+        monitor ID to enable
+
+    Returns
+    -------"""
+
+    url = MONITORING_ENABLE.replace(":id", monitor_id)
+    r = session.post(url)