elements-api 2025.11.4__tar.gz

elements_api-2025.11.4/LICENSE

@@ -0,0 +1,7 @@
+Copyright 2022 Orbital Insight, Inc.
+
+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.

elements_api-2025.11.4/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: elements-api
+Version: 2025.11.4
+Summary: Elements API Client
+License-File: LICENSE
+Requires-Dist: grpcio
+Requires-Dist: grpcio-status
+Requires-Dist: requests
+Dynamic: license-file
+Dynamic: requires-dist
+Dynamic: summary

elements_api-2025.11.4/README.md

@@ -0,0 +1,7 @@
+# Orbital Insight Platform API (OI Papi)
+
+PAPI (Platform API) is the gateway to Orbital Insight's Terra platform. PAPI provides a single, unified API for developers to build geospatial analytics solutions tailed to their specific domains. PAPI provides both gRPC and HTTP Rest endpoints.
+
+For more information about PAPI endpoints please refer to the [API documentation](https://sphinx.core3.orbitalinsight.io/oi_papi/latest/api-docs/).
+
+If you are developer of PAPI itself, please refer to the [Local Setup and Testing](docs/local_setup_and_testing.md) document to get started.

elements_api-2025.11.4/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=42", "wheel", "PyYAML>=6.0"]
+build-backend = "setuptools.build_meta"

elements_api-2025.11.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

elements_api-2025.11.4/setup.py

@@ -0,0 +1,29 @@
+"""
+A setuptools based setup module.
+Based on:
+https://packaging.python.org/en/latest/distributing.html
+https://github.com/pypa/sampleproject
+"""
+
+import yaml
+import setuptools  # type: ignore
+
+
+def get_version(version_file_loc):
+    with open(version_file_loc, 'r') as stream:
+        data = yaml.load(stream, yaml.SafeLoader)
+        return (data.get('version'))
+
+
+setuptools.setup(
+    name='elements-api',
+    version=get_version('ops/conda-recipe/conda_build_config.yaml'),
+    description='Elements API Client',
+    package_dir={'': 'src/py'},
+    packages=setuptools.find_packages('src/py', exclude=[
+        'mocked_services',
+        'oi_papi',
+        'oi_papi.*'
+    ]),
+    install_requires=['grpcio', 'grpcio-status', 'requests']
+)

elements_api-2025.11.4/src/py/elements_api/__init__.py

@@ -0,0 +1,8 @@
+# Copyright 2017-2021 Orbital Insight Inc., all rights reserved.
+# Contains confidential and trade secret information.
+# Government Users:  Commercial Computer Software - Use governed by
+# terms of Orbital Insight commercial license agreement.
+
+
+from elements_api.sync_client import ElementsSyncClient  # noqa
+from elements_api.async_client import ElementsAsyncClient  # noqa

elements_api-2025.11.4/src/py/elements_api/async_client.py

@@ -0,0 +1,43 @@
+# Copyright 2017-2021 Orbital Insight Inc., all rights reserved.
+# Contains confidential and trade secret information.
+# Government Users:  Commercial Computer Software - Use governed by
+# terms of Orbital Insight commercial license agreement.
+
+
+import grpc
+from elements_api.elements_base_api import ElementsBaseApi
+from elements_api import models
+from elements_api.async_interceptors import (
+    ContextInjectorUnaryUnary, ContextInjectorStreamUnary, ContextInjectorUnaryStream, ContextInjectorStreamStream
+)
+
+
+class ElementsAsyncClient:
+    def __init__(self, oi_papi_url, port=443, secure=True, api_token=None, root_certificates_file=None):
+        self.api = ElementsAsyncApi(oi_papi_url, port, secure, api_token=api_token,
+                                    root_certificates_file=root_certificates_file)
+        self.models = models
+
+
+class ElementsAsyncApi(ElementsBaseApi):
+    def __init__(self, oi_papi_url, port=443, secure=True, api_token=None, root_certificates_file=None):
+        self.context_injecting_interceptors = [
+            # materialize distributed context from request headers
+            ContextInjectorUnaryUnary(), ContextInjectorUnaryStream(),
+            ContextInjectorStreamUnary(), ContextInjectorStreamStream()
+        ]
+        super(ElementsAsyncApi, self).__init__(oi_papi_url, port, secure, api_token,
+                                               root_certificates_file)
+
+    def _get_channel(self, channel_credentials: grpc.ChannelCredentials):
+        token_creds = grpc.access_token_call_credentials(self.access_token)
+        creds = grpc.composite_channel_credentials(channel_credentials, token_creds)
+        return grpc.aio.secure_channel(f"{self._oi_papi_url}:{self._port}",
+                                       creds,
+                                       options=self.options,
+                                       compression=None,
+                                       interceptors=self.context_injecting_interceptors)
+
+    # TODO: async destructor
+    def __adel__(self):
+        self._channel.close()

elements_api-2025.11.4/src/py/elements_api/async_interceptors.py

@@ -0,0 +1,105 @@
+import importlib
+from typing import Callable, Union
+
+import grpc
+from grpc.aio import \
+    UnaryUnaryClientInterceptor, \
+    UnaryStreamClientInterceptor, \
+    StreamUnaryClientInterceptor, \
+    StreamStreamClientInterceptor, \
+    ClientCallDetails
+from grpc.aio._call import \
+    UnaryUnaryCall, \
+    UnaryStreamCall, \
+    StreamUnaryCall, \
+    StreamStreamCall
+
+from grpc.aio._typing import RequestType, ResponseIterableType, ResponseType, \
+    RequestIterableType
+
+if importlib.util.find_spec('oi_tracing'):
+    from oi_tracing import inject_current_span
+else:
+    def inject_current_span(_headers):
+        pass
+
+if importlib.util.find_spec('mercury_client'):
+    from mercury_client.context import context_as_dict
+else:
+    def context_as_dict():
+        return {}
+
+
+def inject_current_context_into_header(client_call_details: ClientCallDetails)\
+        -> ClientCallDetails:
+
+    if client_call_details.metadata is None:  # grpc.aio._metadata.Metadata
+        client_call_details.metadata = grpc.aio._metadata.Metadata()
+
+    new_headers = context_as_dict()
+    # Remove any Auth headers and let this be controlled by Papi's token setting
+    for key in ('Authorization', 'X-Orbitalinsight-Auth-Token'):
+        new_headers.pop(key, None)
+
+    inject_current_span(new_headers)
+    # inject_current_auth(new_headers)
+
+    for k, v in new_headers.items():
+        client_call_details.metadata.add(k, str(v))
+    # todo not clear if it is safe to modify or a new copy needs to be made
+    #   at this point returning modified original object
+    return client_call_details
+
+
+class ContextInjectorUnaryUnary(UnaryUnaryClientInterceptor):
+
+    async def intercept_unary_unary(
+            self, continuation: Callable[[ClientCallDetails, RequestType],
+                                         UnaryUnaryCall],
+            client_call_details: ClientCallDetails,
+            request: RequestType) \
+            -> Union[UnaryUnaryCall, ResponseType]:
+        new_details = inject_current_context_into_header(client_call_details)
+        response = continuation(new_details, request)
+        return await response
+
+
+class ContextInjectorUnaryStream(UnaryStreamClientInterceptor):
+
+    async def intercept_unary_stream(
+            self,
+            continuation: Callable[[ClientCallDetails, RequestType],
+                                   UnaryStreamCall],
+            client_call_details: ClientCallDetails,
+            request: RequestType) \
+            -> Union[ResponseIterableType, UnaryStreamCall]:
+        new_details = inject_current_context_into_header(client_call_details)
+        response = continuation(new_details, request)
+        return await response
+
+
+class ContextInjectorStreamUnary(StreamUnaryClientInterceptor):
+
+    async def intercept_stream_unary(
+            self,
+            continuation: Callable[[ClientCallDetails, RequestType],
+                                   StreamUnaryCall],
+            client_call_details: ClientCallDetails,
+            request_iterator: RequestIterableType,
+    ) -> StreamUnaryCall:
+        new_details = inject_current_context_into_header(client_call_details)
+        response = continuation(new_details, request_iterator)
+        return await response
+
+
+class ContextInjectorStreamStream(StreamStreamClientInterceptor):
+    async def intercept_stream_stream(
+            self,
+            continuation: Callable[[ClientCallDetails, RequestType],
+                                   StreamStreamCall],
+            client_call_details: ClientCallDetails,
+            request_iterator: RequestIterableType,
+    ) -> Union[ResponseIterableType, StreamStreamCall]:
+        new_details = inject_current_context_into_header(client_call_details)
+        response = continuation(new_details, request_iterator)
+        return await response

elements_api-2025.11.4/src/py/elements_api/elements_base_api.py

@@ -0,0 +1,454 @@
+# Copyright 2017-2021 Orbital Insight Inc., all rights reserved.
+# Contains confidential and trade secret information.
+# Government Users:  Commercial Computer Software - Use governed by
+# terms of Orbital Insight commercial license agreement.
+
+import os
+from abc import ABC, abstractmethod
+import json
+import time
+import base64
+from typing import Optional
+from functools import lru_cache, wraps
+import requests
+
+import grpc
+
+
+API_TOKEN = 'TERRASCOPE_API_TOKEN'
+
+
+@lru_cache(maxsize=128)
+def json_from_jwt(jwt_token: str) -> dict[str, object]:
+    # see also similar function in user svc client
+    # returns claims dict
+    try:
+        [_header, payload, _signature] = jwt_token.split('.')
+        payload_text = base64.b64decode(payload + "===", '-_')
+        payload_json = json.loads(payload_text)
+        return payload_json
+    except BaseException:
+        return {}
+
+
+def is_token_expiring(jwt_token_str, within_secs=300) -> bool:
+    claims = json_from_jwt(jwt_token_str)
+    return claims.get('exp') < time.time() + within_secs
+
+
+def is_offline_token(jwt_token_str) -> bool:
+    claims = json_from_jwt(jwt_token_str)
+    return claims.get('typ') == 'Offline'
+
+
+def check_access_token(func) -> bool:
+    # decorator
+    @wraps(func)
+    def wrapper(*args, **kwargs):  # The instance is passed as the first argument
+        self = args[0]
+        # check if current access token is expired
+        self.refresh_access_token_and_recreate_stubs()
+        result = func(self)
+        return result
+    return wrapper
+
+
+class ElementsBaseApi(ABC):
+
+    def __init__(self, oi_papi_url: str, port: int = 443, secure=True, api_token: str = None, root_certificates_file=None):
+        self._oi_papi_url = oi_papi_url
+        self._port = port
+        self._secure = secure
+        self._root_certificates_file = root_certificates_file
+        self._channel = None
+        self.api_token: Optional[str] = os.environ.get(API_TOKEN, "").strip() if api_token is None else api_token.strip()
+
+        # check if this is an offline token, which is a refresh token, and obtain access tokens from it periodically
+        self.is_offline_token: bool = is_offline_token(self.api_token)
+        self.access_token: Optional[str] = self.api_token if not is_offline_token else None
+        self.access_token_expiration_threshold = int(os.getenv('ACCESS_TOKEN_EXPIRATION_THRESHOLD', '300'))
+        # (token will be renewed when it has less than this threshhold before expiry)
+        self.options = [('grpc.max_send_message_length', -1),
+                        ('grpc.max_receive_message_length', -1),
+                        ('grpc.max_metadata_size', 16000)]
+        service_config_json: str = json.dumps({
+            "methodConfig": [{
+                "name": [{}],  # Apply retry to all methods by using [{}]
+                "retryPolicy": {
+                    "maxAttempts": 5,
+                    "initialBackoff": "1.0s",
+                    "maxBackoff": "60s",
+                    "backoffMultiplier": 2,
+                    "retryableStatusCodes": ["UNAVAILABLE"],
+                },
+            }]
+        })
+        self.options.append(("grpc.service_config", service_config_json))
+
+        self.refresh_access_token()
+        self.new_channel()
+        self.recreate_stubs()
+
+    def recreate_stubs(self):
+        from elements_api import stubs
+        # unauthenticated users can access forgot_password
+        self._forgot_password = stubs.forgot_password.ForgotPasswordApiStub(self._channel)
+
+        if self.api_token:
+            self._algorithm = stubs.algorithm.AlgorithmApiStub(self._channel)
+            self._algorithm_version = stubs.algorithm_version.AlgorithmVersionApiStub(self._channel)
+            self._algorithm_config = stubs.algorithm_config.AlgorithmConfigApiStub(self._channel)
+            self._aoi = stubs.aoi.AOIApiStub(self._channel)
+            self._aoi_collection = stubs.aoi_collection.AOICollectionApiStub(self._channel)
+            self._aoi_version = stubs.aoi_version.AOIVersionApiStub(self._channel)
+            self._aoi_catalog = stubs.aoi_catalog.AOICatalogApiStub(self._channel)
+            self._aoi_transaction = stubs.aoi_transaction.AOITransactionApiStub(self._channel)
+            self._aoi_export = stubs.aoi_export.AOIExportApiStub(self._channel)
+            self._algorithm_computation = stubs.algorithm_computation.AlgorithmComputationApiStub(self._channel)
+            self._algorithm_computation_execution = \
+                stubs.algorithm_computation_execution.AlgorithmComputationExecutionApiStub(self._channel)
+            self._analysis = stubs.analysis.AnalysisApiStub(self._channel)
+            self._analysis_version = stubs.analysis_version.AnalysisVersionApiStub(self._channel)
+            self._credit = stubs.credit.CreditApiStub(self._channel)
+            self._result = stubs.result.ResultApiStub(self._channel)
+            self._analysis_config = stubs.analysis_config.AnalysisConfigApiStub(self._channel)
+            self._analysis_computation = stubs.analysis_computation.AnalysisComputationApiStub(self._channel)
+            self._system = stubs.system.SystemApiStub(self._channel)
+            self._toi = stubs.toi.TOIApiStub(self._channel)
+            self._permission = stubs.permission.PermissionApiStub(self._channel)
+            self._user = stubs.user.UserApiStub(self._channel)
+            self._user_collection = stubs.user_collection.UserCollectionApiStub(self._channel)
+            self._token = stubs.token.TokenApiStub(self._channel)
+            self._visualization = stubs.visualization.VisualizationApiStub(self._channel)
+            self._tile = stubs.tile.TileApiStub(self._channel)
+            self._notification = stubs.notification.NotificationApiStub(self._channel)
+            self._data_source = stubs.data_source.DataSourceAPIStub(self._channel)
+            self._data_type = stubs.data_type.DataTypeAPIStub(self._channel)
+            self._data_tracking = stubs.data_tracking.DataTrackingApiStub(self._channel)
+            self._project = stubs.project.ProjectApiStub(self._channel)
+            self._project_analysis_config = stubs.project_analysis_config.ProjectAnalysisConfigApiStub(self._channel)
+            self._project_collaborator = stubs.project_collaborator.ProjectCollaboratorApiStub(self._channel)
+            self._project_group = stubs.project_group.ProjectGroupApiStub(self._channel)
+            self._project_result = stubs.project_result.ProjectResultApiStub(self._channel)
+            self._project_filter = stubs.project_filter.ProjectFilterApiStub(self._channel)
+            self._filter = stubs.filter.FilterApiStub(self._channel)
+            self._project_aoi = stubs.project_aoi.ProjectAOIApiStub(self._channel)
+            self._order = stubs.order.OrderApiStub(self._channel)
+            self._order_recommendation = stubs.order_recommendation.OrderRecommendationApiStub(self._channel)
+            self._tasking_order = stubs.tasking_order.TaskingOrderApiStub(self._channel)
+            self._provider_quotas = stubs.provider_quotas.ProviderQuotasApiStub(self._channel)
+            self._resource = stubs.resource.ResourceApiStub(self._channel)
+            self._s3 = stubs.s3.S3ApiStub(self._channel)
+
+    def new_channel(self):
+        # if self._channel is not None:
+        #     self._channel.close() # todo this is async, and channel.__del__ takes care of it
+        self._channel = self._get_channel(
+            self._get_ssl_channel_credentials(
+                self._secure,
+                root_certificates_file=self._root_certificates_file))
+        return self._channel
+
+    def refresh_access_token(self) -> bool:
+        """
+        Refreshes the access token if it is expired.
+        returns True if the access token was refreshed, False otherwise.
+        """
+        # check if current access token is expired
+        if self.api_token and not is_offline_token(self.api_token):
+            return False  # in which case it is an access token, and it was not refreshed
+        # check expiration on the access_token
+
+        if self.access_token and not is_token_expiring(
+            self.access_token,
+            within_secs=self.access_token_expiration_threshold
+        ):
+            return False
+
+        oidc_base_url = os.getenv(
+            'OIDC_BASE_URL',
+            'https://keycloak.orbitalinsight.com')
+        oidc_realm = os.getenv('OIDC_REALM', 'elements')
+        oidc_token_endpoint = os.getenv(
+            'OIDC_TOKEN_ENDPOINT',
+            f'{oidc_base_url}/realms/{oidc_realm}/protocol/openid-connect/token')
+
+        # note: api token is an offline token, which is a special refresh token.
+        oidc_client_id = os.getenv('OIDC_CLIENT_ID', 'login-ui')
+        oidc_client_secret = os.getenv('OIDC_CLIENT_SECRET')
+
+        request_json = {
+            'refresh_token': self.api_token,
+            'client_id': oidc_client_id,
+            'grant_type': 'refresh_token',
+            'scope': 'openid offline_access'
+        }
+        if oidc_client_secret:
+            request_json['client_secret'] = oidc_client_secret
+
+        response = requests.post(
+            oidc_token_endpoint,
+            data=request_json,
+            headers={'Content-Type': 'application/x-www-form-urlencoded'})
+        if not response.ok:
+            raise Exception(f"Failed to refresh token: {response.text}")
+
+        self.access_token = response.json().get('access_token')
+        return True
+
+    def refresh_access_token_and_recreate_stubs(self) -> bool:
+        # check if current access token is expired
+        if not self.refresh_access_token():
+            return False
+        self.new_channel()
+        self.recreate_stubs()
+        return True
+    # individual api accessors are properties, since underlying channel may need to change
+    # at any time due to its token change. Do not store property result in a variable,
+    # as it will not be refreshed automatically when the token changes
+    # token freshness is checked in every call, then if it expired and changed,
+    # (all) stubs are regenerated. A new channel is created with that token in each stub
+
+    @property
+    @check_access_token
+    def forgot_password(self):
+        return self._forgot_password
+
+    @property
+    @check_access_token
+    def algorithm(self):
+        return self._algorithm
+
+    @property
+    @check_access_token
+    def algorithm_version(self):
+        return self._algorithm_version
+
+    @property
+    @check_access_token
+    def algorithm_config(self):
+        return self._algorithm_config
+
+    @property
+    @check_access_token
+    def aoi(self):
+        return self._aoi
+
+    @property
+    @check_access_token
+    def aoi_collection(self):
+        return self._aoi_collection
+
+    @property
+    @check_access_token
+    def aoi_version(self):
+        return self._aoi_version
+
+    @property
+    @check_access_token
+    def aoi_catalog(self):
+        return self._aoi_catalog
+
+    @property
+    @check_access_token
+    def aoi_transaction(self):
+        return self._aoi_transaction
+
+    @property
+    @check_access_token
+    def aoi_export(self):
+        return self._aoi_export
+
+    @property
+    @check_access_token
+    def algorithm_computation(self):
+        return self._algorithm_computation
+
+    @property
+    @check_access_token
+    def algorithm_computation_execution(self):
+        return self._algorithm_computation_execution
+
+    @property
+    @check_access_token
+    def analysis(self):
+        return self._analysis
+
+    @property
+    @check_access_token
+    def analysis_version(self):
+        return self._analysis_version
+
+    @property
+    @check_access_token
+    def credit(self):
+        return self._credit
+
+    @property
+    @check_access_token
+    def result(self):
+        return self._result
+
+    @property
+    @check_access_token
+    def analysis_config(self):
+        return self._analysis_config
+
+    @property
+    @check_access_token
+    def analysis_computation(self):
+        return self._analysis_computation
+
+    @property
+    @check_access_token
+    def system(self):
+        return self._system
+
+    @property
+    @check_access_token
+    def toi(self):
+        return self._toi
+
+    @property
+    @check_access_token
+    def permission(self):
+        return self._permission
+
+    @property
+    @check_access_token
+    def user(self):
+        return self._user
+
+    @property
+    @check_access_token
+    def user_collection(self):
+        return self._user_collection
+
+    @property
+    @check_access_token
+    def token(self):
+        return self._token
+
+    @property
+    @check_access_token
+    def visualization(self):
+        return self._visualization
+
+    @property
+    @check_access_token
+    def tile(self):
+        return self._tile
+
+    @property
+    @check_access_token
+    def notification(self):
+        return self._notification
+
+    @property
+    @check_access_token
+    def data_source(self):
+        return self._data_source
+
+    @property
+    @check_access_token
+    def data_type(self):
+        return self._data_type
+
+    @property
+    @check_access_token
+    def data_tracking(self):
+        return self._data_tracking
+
+    @property
+    @check_access_token
+    def project(self):
+        return self._project
+
+    @property
+    @check_access_token
+    def project_analysis_config(self):
+        return self._project_analysis_config
+
+    @property
+    @check_access_token
+    def project_collaborator(self):
+        return self._project_collaborator
+
+    @property
+    @check_access_token
+    def project_group(self):
+        return self._project_group
+
+    @property
+    @check_access_token
+    def project_result(self):
+        return self._project_result
+
+    @property
+    @check_access_token
+    def project_filter(self):
+        return self._project_filter
+
+    @property
+    @check_access_token
+    def filter(self):
+        return self._filter
+
+    @property
+    @check_access_token
+    def project_aoi(self):
+        return self._project_aoi
+
+    @property
+    @check_access_token
+    def order(self):
+        return self._order
+
+    @property
+    @check_access_token
+    def order_recommendation(self):
+        return self._order_recommendation
+
+    @property
+    @check_access_token
+    def tasking_order(self):
+        return self._tasking_order
+
+    @property
+    @check_access_token
+    def provider_quotas(self):
+        return self._provider_quotas
+
+    @property
+    @check_access_token
+    def provider(self):
+        return self._provider
+
+    @property
+    @check_access_token
+    def resource(self):
+        return self._resource
+
+    @property
+    @check_access_token
+    def s3(self):
+        return self._s3
+
+    def _get_ssl_channel_credentials(self, secure, root_certificates_file=None):
+        # note: with all defaults, gRPC will search for cert as described here:
+        #  https://github.com/grpc/grpc/blob/7a63bd5407d5e14b30f19a5aaf4b6cd1b80f00e1/include/grpc/grpc_security.h#L287
+        # for local env, use local_channel_credentials:
+        #  https://grpc.github.io/grpc/python/grpc.html#grpc.local_channel_credentials
+        if secure:
+            root_certificates = None
+            if root_certificates_file:
+                with open(root_certificates_file, 'rb') as file:
+                    root_certificates = file.read()
+
+            return grpc.ssl_channel_credentials(root_certificates=root_certificates,
+                                                private_key=None, certificate_chain=None)
+        return grpc.local_channel_credentials()
+
+    @abstractmethod
+    def _get_channel(self, channel_credentials: grpc.ChannelCredentials):
+        ...