Skip to main content

An SDK for EarthScope API

Project description

EarthScope SDK

An SDK for interacting with EarthScope's APIs

Getting Started

Installation

Install from PyPI

pip install earthscope-sdk

Usage

For detailed usage info and examples, visit our SDK docs.

# Import and create a client
from earthscope_sdk import EarthScopeClient

client = EarthScopeClient()

# Example client method usage; retrieve your user profile
profile = client.user.get_profile()
print(profile)

# Client cleanup
client.close()

Async Usage

There is also an async client available

import asyncio
from earthscope_sdk import AsyncEarthScopeClient

async def main():
    client = AsyncEarthScopeClient()

    profile = await client.user.get_profile()
    print(profile)

    await client.close()

asyncio.run(main())

Context Managers

Client classes can also be used as context managers to ensure resource cleanup occurs.

# sync
with EarthScopeClient() as client:
   client.user.get_profile()

# async
async with AsyncEarthScopeClient() as client:
   await client.user.get_profile()

Bootstrapping Authentication

There are a few methods of bootstrapping authentication for the SDK.

Once refreshable credentials are available to the SDK, it will transparently handle access token refresh on your behalf.

Same host

If you have the EarthScope CLI installed on the same host that is running your application which uses earthscope-sdk, you can simply log in using the CLI. The CLI shares credentials and configuration with this SDK (when running on the same host).

Running es login will open your browser and prompt you to log in to your EarthScope account.

$ es login
Attempting to automatically open the SSO authorization page in your default browser.
If the browser does not open or you wish to use a different device to authorize this request, open the following URL:

https://login.earthscope.org/activate?user_code=ABCD-EFGH

Successful login! Access token expires at 2024-12-27 18:50:37+00:00

Now when you run your application, earthscope-sdk will find your credentials.

Different hosts

Sometimes your workload runs on different hosts than your main workstation and you cannot feasibly "log in" on all of them. For example, maybe you're running many containers in your workload.

You can still use the EarthScope CLI to facilitate auth for applications on other machines.

  1. Use the CLI on your primary workstation as described above to log in.

  2. Use the CLI to retrieve your refresh token.

    $ es user get-refresh-token
    <your-refresh-token>
    

    Note: your refresh token should be treated as a secret credential. Anyone with a valid refresh token can use it to continually retrieve new access tokens on your behalf.

  3. Pass this refresh token to all the hosts needing auth for the earthscope-sdk. For example, inject the ES_OAUTH2__REFRESH_TOKEN environment variable on these hosts.

    export ES_OAUTH2__REFRESH_TOKEN="<your-refresh-token>"
    

SDK Settings

SDK Settings are provided via the following methods (in order of precedence):

  1. initialization arguments (e.g. via class constructors)
  2. environment variables
  3. dotenv file (.env) variables
  4. user's home directory settings files
    1. ~/.earthscope/config.toml (for configuration)
    2. ~/.earthscope/<profile-name>/tokens.json (for tokens)
  5. legacy EarthScope CLI v0 credentials
  6. default settings

SDK configuration is managed by the SdkSettings class, and calling the constructor performs this settings loading chain.

from earthscope_sdk.config.settings import SdkSettings

settings = SdkSettings()  # loads settings via loading chain

For more details on SDK configuration, including what options are available, see our settings docs.

Contributing

For details on contributing to the EarthScope SDK, please see:

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

earthscope_sdk-1.1.0.tar.gz (38.3 kB view details)

Uploaded Source

Built Distribution

earthscope_sdk-1.1.0-py3-none-any.whl (36.5 kB view details)

Uploaded Python 3

File details

Details for the file earthscope_sdk-1.1.0.tar.gz.

File metadata

  • Download URL: earthscope_sdk-1.1.0.tar.gz
  • Upload date:
  • Size: 38.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.9.23

File hashes

Hashes for earthscope_sdk-1.1.0.tar.gz
Algorithm Hash digest
SHA256 ddfef1f3ee047c93fbe61c83120c5acbf1640a89483b9b92997ab8159bd18975
MD5 22e75a23c497bfdc24105201fb0ffd2a
BLAKE2b-256 3eb8d475a543999b14b65b60137e50fbbb4cd031c557c3ea8ce6d6ef7faad216

See more details on using hashes here.

File details

Details for the file earthscope_sdk-1.1.0-py3-none-any.whl.

File metadata

  • Download URL: earthscope_sdk-1.1.0-py3-none-any.whl
  • Upload date:
  • Size: 36.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.9.23

File hashes

Hashes for earthscope_sdk-1.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 83b16b50c6e0023aa2276101599cf547c3517046b2fe9a6a42af2d881032afed
MD5 f5679f458fc0b427522e9a7599392d45
BLAKE2b-256 6e6947a4f85ba017f99e53aef44972c4a354691aa6357cd3d9928f7de4721bfc

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page