earthscope-sdk 0.2.0__tar.gz → 1.0.0b0__tar.gz

{earthscope-sdk-0.2.0 → earthscope_sdk-1.0.0b0}/PKG-INFO

@@ -1,8 +1,8 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: earthscope-sdk
-Version: 0.2.0
+Version: 1.0.0b0
 Summary: An SDK for EarthScope API
-Author-email: EarthScope <software@unavco.org>
+Author-email: EarthScope <data-help@earthscope.org>
 License:                                  Apache License
                                    Version 2.0, January 2004
                                 http://www.apache.org/licenses/
@@ -210,130 +210,159 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.7
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown
-Provides-Extra: dev
 License-File: LICENSE
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic-settings[toml]>=2.7.0
+Provides-Extra: dev
+Requires-Dist: bumpver; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: pip-tools; extra == "dev"
+Requires-Dist: pytest-httpx; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
 
 # EarthScope SDK
 
-An SDK for authenticating with the EarthScope API
+An SDK for interacting with EarthScope's APIs
 
 ## Getting Started
 
-### USAGE
+### Installation
 
-1. **(Optional) Suggest setting up and activating a python virtual environment so as not to clutter your system python**
+Install from PyPI
 
-   ```shell
-   python3 -m venv venv
-   . venv/bin/activate
+```shell
+pip install earthscope-sdk
+```
+
+### Usage
+
+For detailed usage options and examples, visit [our usage docs](docs/usage.md).
+
+```py
+# 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
+
+```py
+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.
+
+```py
+# 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](TODO) 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.
+
+```console
+$ 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](TODO) to facilitate auth for applications on other machines.
+
+1. Use the CLI on your primary workstation [as described above](#same-host) to log in.
+
+1. Use the CLI to retrieve your refresh token.
+
+   ```console
+   $ es user get-refresh-token
+   <your-refresh-token>
    ```
 
-2. **Install earthscope-sdk**
+   > **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**.
+
+1. 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.
 
    ```shell
-   pip install earthscope-sdk
-   ```
-   For developers:
-   ```bash
-   pip -e install earthscope-sdk[dev]
+   export ES_OAUTH2__REFRESH_TOKEN="<your-refresh-token>"
    ```
-   
-3. **Create/Use required subclasses**
-   \
-   To use the **Device Authorization Flow** you will need to create a subclass of the DeviceCodeFlow class. Similarly, to use
-   the **Machine-to-Machine Client Credentials Flow** you will need to create a subclass of the ClientCredientialFlow class.
-
-   Simple subclasses exist for your use that you can import and use which will allow for locally loading and saving access tokens:
-   *DeviceCodeFlowSimple* and *ClientCredentialsFlowSimple* (see below for examples on useage)
-   <br/><br/>
-   Creating your own subclass:
-    \
-   Implementing the following methods in the subclass is required:
-   * `load_tokens` should implement the ability to load saved tokens
-   * `save_tokens` should implement the ability to save tokens locally
-   
-   additionally for DeviceCodeFlow only:
-   * `prompt_user` should provide the user with the SSO authorization uri
-
-   You will need to instantiate your subclass with the following instance attributes:
-
-   For DeviceCodeFlow:
-   * `audience`, `domain`, `client_id`, and `scope`.
-
-   For ClientCredentialsFlow:
-   * `audience`, `client_credentials`, and `domain`.
-   
-      where client_credentials contains the machine-to-machine `client_id` and `client_secret`.
-
-   These values are all obtained from [Auth0](https://manage.auth0.com/).
-   <br/><br/>
-4. **Use the SDK**
-   \
-   You can now use the subclasses to define actions such as logging in/out, retrieving or refreshing access tokens, etc...
-   \
-   **NOTE: Never share your access token or refresh tokens**
-   
-   Additionally, once the subclasses have been instantiated, you can pass your access token as a parameter to retrieve
-   your user/anonymous user information using the earthscope_sdk.user.user *get_user* and *lookup_anon* functions.
-  
- 
-5. **Example useages:**
-   \
-   Note: To see an example of an application using this SDK (and creating custom subclass), check out the [EarthScope CLI Repository](https://gitlab.com/earthscope/public/earthscope-cli).
-   <br/><br/>
-   How to use the existing simple subclass for device code flow:
-   \
-   *simple example python code*:
-    ```
-    import requests
-    from pathlib import Path
-     
-    from earthscope_sdk.auth.device_code_flow import DeviceCodeFlowSimple
-    from earthscope_sdk.auth.auth_flow import NoTokensError
-    
-   # choose where you want the token saved - the default file name is sso_tokens.json
-   # if you want to keep the default name, set the path to a directory. Include a file name to rename. 
-   token_path = "/Users/my_user/token_dir"
-   
-   url = "https://data-idm.unavco.org/path/to/data_file"
-   # example: "https://data-idm.unavco.org/archive/gnss/rinex/obs/2022/298/ar272980.22d.Z"
-   
-    # instantiate the device code flow subclass
-    device_flow = DeviceCodeFlowSimple(Path(token_path))
-    try:
-        # get access token from local path
-        device_flow.get_access_token_refresh_if_necessary()
-    except NoTokensError:
-        # if no token was found locally, do the device code flow
-        device_flow.do_flow()
-    token = device_flow.access_token
-     
-    # request a file and provide the token in the Authorization header
-   file_name = Path(url).name
-   directory_to_save_file = Path.cwd() # where you want to save the downloaded file 
-   
-    r = requests.get(url, headers={"authorization": f"Bearer {token}"})
-    if r.status_code == requests.codes.ok:
-        # save the file
-        with open(Path(directory_to_save_file / file_name), 'wb') as f:
-            for data in r:
-                f.write(data)
-    else:
-        #problem occured
-        print(f"failure: {r.status_code}, {r.reason}")
-     ```
-   
-   Instantiate the subclass and set the token_path where you want to load/save the token. 
-   If you provide only a directory, the file will be saved as sso_tokens.json. 
-   We hard-code this variable in this simple example, but we recommend setting this path as an environment variable and 
-   reading the environment varibale in your code.
-
-
-   the **get_access_token_refresh_if_necessary** method will retrieve the token and refresh the token if it is expired. 
-   If there is no token, then the **do_flow** method will begin the device code flow and once you complete the flow, 
-   the token will be saved at the token_path. You can use the **requests** library to download the file you want 
-   (or files in a loop) and pass in the access token in the Authorization header. 
-   
-Learn more about [data access methods](https://www.unavco.org/data/gps-gnss/data-access-methods/data-access-methods.html).
+
+## SDK Settings
+
+SDK Settings are provided via the following methods (in order of precedence):
+
+1. initialization arguments (e.g. via class constructors)
+1. environment variables
+1. dotenv file (.env) variables
+1. user's home directory settings files
+   1. `~/.earthscope/config.toml` (for configuration)
+   1. `~/.earthscope/<profile-name>/tokens.json` (for tokens)
+1. legacy EarthScope CLI v0 credentials
+1. default settings
+
+SDK configuration is managed by the `SdkSettings` class, and calling the constructor performs this settings loading chain.
+
+```py
+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](docs/settings.md).
+
+## Contributing
+
+For details on contributing to the EarthScope SDK, please see:
+
+- [design docs](docs/design.md)
+- [development docs](docs/development.md)

earthscope_sdk-1.0.0b0/README.md

@@ -0,0 +1,141 @@
+# EarthScope SDK
+
+An SDK for interacting with EarthScope's APIs
+
+## Getting Started
+
+### Installation
+
+Install from PyPI
+
+```shell
+pip install earthscope-sdk
+```
+
+### Usage
+
+For detailed usage options and examples, visit [our usage docs](docs/usage.md).
+
+```py
+# 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
+
+```py
+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.
+
+```py
+# 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](TODO) 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.
+
+```console
+$ 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](TODO) to facilitate auth for applications on other machines.
+
+1. Use the CLI on your primary workstation [as described above](#same-host) to log in.
+
+1. Use the CLI to retrieve your refresh token.
+
+   ```console
+   $ 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**.
+
+1. 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.
+
+   ```shell
+   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)
+1. environment variables
+1. dotenv file (.env) variables
+1. user's home directory settings files
+   1. `~/.earthscope/config.toml` (for configuration)
+   1. `~/.earthscope/<profile-name>/tokens.json` (for tokens)
+1. legacy EarthScope CLI v0 credentials
+1. default settings
+
+SDK configuration is managed by the `SdkSettings` class, and calling the constructor performs this settings loading chain.
+
+```py
+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](docs/settings.md).
+
+## Contributing
+
+For details on contributing to the EarthScope SDK, please see:
+
+- [design docs](docs/design.md)
+- [development docs](docs/development.md)

{earthscope-sdk-0.2.0 → earthscope_sdk-1.0.0b0}/pyproject.toml

@@ -4,11 +4,11 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "earthscope-sdk"
-version = "0.2.0"
+version = "1.0.0b0"
 description = "An SDK for EarthScope API"
 readme = "README.md"
-authors = [{ name = "EarthScope", email = "software@unavco.org"}]
-license = { file = "LICENSE"}
+authors = [{ name = "EarthScope", email = "data-help@earthscope.org" }]
+license = { file = "LICENSE" }
 classifiers = [
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python",
@@ -17,29 +17,35 @@ classifiers = [
 ]
 
 #Suggestion not to pin dependencies since the package should work in many different python environments
-dependencies = [
-    "pyjwt >= 2.4.0",
-    "requests >= 2.27.1"
-]
-requires-python = ">=3.7"
+dependencies = ["httpx>=0.27.0", "pydantic-settings[toml]>=2.7.0"]
+requires-python = ">=3.9"
 
 [project.optional-dependencies]
-dev = ["black", "bumpver", "build", "pytest", "twine", "pip-tools"]
+dev = [
+    "bumpver",
+    "build",
+    "pytest",
+    "twine",
+    "pip-tools",
+    "pytest-httpx",
+    "pytest-asyncio",
+    "ruff",
+]
 
 [project.urls]
 Homepage = "https://gitlab.com/earthscope/public/earthscope-sdk"
 
 [tool.bumpver]
-current_version = "0.2.0"
-version_pattern = "MAJOR.MINOR.PATCH"
-commit_message = "bump version {old_version} -> {new_version}"
+current_version = "1.0.0b0"
+version_pattern = "MAJOR.MINOR.PATCH[PYTAGNUM]"
+commit_message = "chore: bump version {old_version} -> {new_version}"
 commit = true
 tag = true
 push = false
 
 [tool.bumpver.file_patterns]
-"pyproject.toml" = [
-    'current_version = "{version}"',
-    'version = "{version}"',
-]
+"pyproject.toml" = ['current_version = "{version}"', 'version = "{version}"']
 "src/earthscope_sdk/__init__.py" = ["{version}"]
+
+[tool.pytest.ini_options]
+asyncio_default_fixture_loop_scope = "function"

earthscope_sdk-1.0.0b0/src/earthscope_sdk/__init__.py

@@ -0,0 +1,5 @@
+__version__ = "1.0.0b0"
+
+from earthscope_sdk.client import AsyncEarthScopeClient, EarthScopeClient
+
+__all__ = ["AsyncEarthScopeClient", "EarthScopeClient"]