earthscope-cli 1.1.0__tar.gz → 1.1.2__tar.gz

earthscope_cli-1.1.2/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: earthscope-cli
+Version: 1.1.2
+Summary: A CLI for the EarthScope API
+Author-email: EarthScope <data-help@earthscope.org>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://gitlab.com/earthscope/public/earthscope-cli
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer<0.24.0
+Requires-Dist: typer-di>=0.1.3
+Requires-Dist: earthscope-sdk>=1.3.1
+Requires-Dist: rich>=13.8.0
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: bumpver; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: twine>=6.0.1; extra == "dev"
+Requires-Dist: pip-tools; extra == "dev"
+Dynamic: license-file
+
+# EarthScope CLI
+
+A CLI for interacting with EarthScope's APIs
+
+## Getting Started
+
+### Requirements
+
+To use the CLI you must have:
+
+- Registered an account with Earthscope ([sign up now](https://earthscope.org/user/login)). See [here](https://www.earthscope.org/data/authentication) for more information
+- Python >= 3.9
+
+### Installation
+
+Install from PyPI
+
+```shell
+pip install earthscope-cli
+```
+
+### Usage
+
+A new `es` command is available in your terminal. Use `--help` with any command to explore commands and options.
+
+```shell
+es --help
+es user --help
+```
+
+#### Login to your EarthScope account
+
+```shell
+es login
+```
+
+This will open your browser to a confirmation page with the same code shown on your command line.
+If you are on a device that does not have a web browser, you can copy the displayed url in a browser on another device (personal computer, mobile device, etc...) and complete the confirmation there.
+
+The `es login` command will save your token locally. If this token is deleted, you will need to re-authenticate (login) to retrieve your token again.
+
+#### Get your access token
+
+```shell
+es user get-access-token
+```
+
+The `get-access-token` command will display your access token. If your access token is close to expiration or expired,
+the default behavior is to automatically refresh your token.
+
+If you want to manually refresh your token:
+
+```shell
+es user refresh-access-token
+```
+
+Never share your tokens. If you think your token has been compromised, please revoke your refresh token and re-authenticate (login):
+
+```shell
+es user revoke-refresh-token
+es login
+```
+
+#### Get your user profile
+
+```shell
+es user get-profile
+```
+
+## Documentation
+
+For detailed usage examples, authentication guides, and advanced features, see the [full documentation](https://docs.earthscope.org/projects/CLI).
+
+## EarthScope SDK
+
+If you would like to use EarthScope APIs from python, please use the [earthscope-sdk](https://gitlab.com/earthscope/public/earthscope-sdk/) directly.
+
+## FAQ/troubleshooting
+
+- **How long does my access token last?**
+  - Your access token lasts 24 hours. Your refresh token can be used to refresh your access token.
+- **How long does my refresh token last?**
+  - Your refresh token will never expire - unless you are inactive (do not use it) for one year.
+    If it does expire, you will need to re-authenticate to get a new access and refresh token.
+- **What is a refresh token and how does the CLI use it?**
+  - A refresh token is a special token that is used to renew your access token without you needing to log in again.
+    The refresh token is obtained from your access token, and using the `es user get-access-token` command will automatically
+    renew your access token if it is close to expiration. You can 'manually' refresh your access token by using the command `es user refresh-access-token`.
+    If your access token is compromised, you can revoke your refresh token using `es user revoke-refresh-token`. Once your access token expires,
+    it can no longer be renewed and you will need to re-login.
+- **Should I hard-code my access token into my script?**
+  - No. We recommend you use the cli commands to retrieve your access tokens in your scripts.
+    This way your access token will not be compromised by anyone viewing your script.
+    The access token only lasts 24 hours and cannot be used afterwards unless refreshed.

{earthscope_cli-1.1.0 → earthscope_cli-1.1.2}/pyproject.toml

@@ -4,13 +4,13 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "earthscope-cli"
-version = "1.1.0"
+version = "1.1.2"
 description = "A CLI for the EarthScope API"
 readme = "README.md"
 authors = [{ name = "EarthScope", email = "data-help@earthscope.org" }]
-license = { file = "LICENSE" }
+license = "Apache-2.0"
+license-files = ["LICENSE"]
 classifiers = [
-    "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python",
     "Programming Language :: Python :: 3",
     "Operating System :: OS Independent",
@@ -18,9 +18,9 @@ classifiers = [
 
 #Suggestion not to pin dependencies since the package should work in many different python environments
 dependencies = [
-    "typer-slim>=0.17.3",
+    "typer<0.24.0",
     "typer-di>=0.1.3",
-    "earthscope-sdk>=1.3.0",
+    "earthscope-sdk>=1.3.1",
     "rich>=13.8.0",
 ]
 requires-python = ">=3.9"
@@ -32,7 +32,7 @@ dev = [
     "build",
     "pre-commit",
     "pytest",
-    "twine",
+    "twine>=6.0.1",
     "pip-tools",
 ]
 
@@ -43,7 +43,7 @@ Homepage = "https://gitlab.com/earthscope/public/earthscope-cli"
 es = "earthscope_cli.main:app"
 
 [tool.bumpver]
-current_version = "1.1.0"
+current_version = "1.1.2"
 version_pattern = "MAJOR.MINOR.PATCH[PYTAGNUM]"
 commit_message = "chore: bump version {old_version} -> {new_version}"
 commit = true

earthscope_cli-1.1.2/src/earthscope_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.1.2"

{earthscope_cli-1.1.0 → earthscope_cli-1.1.2}/src/earthscope_cli/common.py

@@ -1,12 +1,9 @@
-from contextlib import suppress
 from typing import Annotated, Optional
 
 import typer
+from rich import print
 from typer_di import Depends
 
-with suppress(ModuleNotFoundError):
-    from rich import print
-
 GLOBAL_HELP_PANEL = "Global Options"
 
 

{earthscope_cli-1.1.0 → earthscope_cli-1.1.2}/src/earthscope_cli/debug.py

@@ -1,13 +1,9 @@
-from contextlib import suppress
-
 import typer
+from rich import print
 from typer_di import Depends, TyperDI
 
 from earthscope_cli.common import get_sdk
 
-with suppress(ModuleNotFoundError):
-    from rich import print
-
 app = TyperDI()
 
 

{earthscope_cli-1.1.0 → earthscope_cli-1.1.2}/src/earthscope_cli/dropoff/render.py

@@ -2,7 +2,7 @@ import threading
 from typing import Dict, List, Optional
 
 from earthscope_sdk.client.dropoff._multipart_uploader import UploadStatus
-from earthscope_sdk.client.dropoff.models import DropoffObject
+from earthscope_sdk.client.dropoff.models import DropoffObject, DropoffSummary
 from rich import print
 from rich.console import Group
 from rich.live import Live
@@ -84,6 +84,31 @@ def print_dropoff_objects_table(
     print()
 
 
+def print_dropoff_summary(summary: DropoffSummary, *, prefix: Optional[str] = None):
+    if not summary.status_counts:
+        print(f"[yellow]No objects found in prefix '{prefix}'")
+        return
+
+    title = "Dropoff Summary"
+    if prefix:
+        title += f" for {prefix}"
+
+    table = Table(
+        title=title,
+        show_header=True,
+        title_style="bold magenta",
+        header_style="bold magenta",
+    )
+    table.add_column("Status")
+    table.add_column("Count")
+    for status in summary.status_counts:
+        table.add_row(status.status, str(status.count))
+
+    print()
+    print(table)
+    print()
+
+
 class AggregateBytesColumn(ProgressColumn):
     """
     Custom column that shows aggregate bytes across all uploads.
@@ -181,6 +206,23 @@ class CompositeProgressBarColumn(ProgressColumn):
         return result
 
 
+class UploadSummary:
+    def __init__(self, total: int, succeeded: int):
+        self.total = total
+        self.succeeded = succeeded
+        self.failed = total - succeeded
+
+    def print(self):
+        color = (
+            "green"
+            if self.failed == 0
+            else ("red" if self.succeeded == 0 else "yellow")
+        )
+        print(
+            f"[{color}]Summary: {self.succeeded}/{self.total} files succeeded, {self.failed} failed"
+        )
+
+
 class ConcurrentUploadProgressDisplay:
     """
     Rich progress display for concurrent file uploads.

{earthscope_cli-1.1.0 → earthscope_cli-1.1.2}/src/earthscope_cli/dropoff/typer.py

@@ -12,13 +12,17 @@ from typer_di import Depends, TyperDI
 from earthscope_cli.common import get_sdk_refreshed
 from earthscope_cli.dropoff.render import (
     ConcurrentUploadProgressDisplay,
+    UploadSummary,
     print_dropoff_objects_table,
+    print_dropoff_summary,
 )
 from earthscope_cli.dropoff.util import (
     DropoffOptions,
+    FilterOptions,
     collect_files,
     get_category,
     get_dropoff_options,
+    get_filter_options,
 )
 
 app = TyperDI()
@@ -67,10 +71,38 @@ def get_object_history(
     print(f"[yellow]No history found for category '{cat_str}' with key '{key}'")
 
 
+@app.command(name="get-summary")
+def get_summary(
+    sdk: Annotated[EarthScopeClient, Depends(get_sdk_refreshed)],
+    options: Annotated[DropoffOptions, Depends(get_dropoff_options)],
+    filters: Annotated[FilterOptions, Depends(get_filter_options)],
+    prefix: Annotated[
+        str,
+        typer.Option(help="The prefix of the objects to get the summary for"),
+    ],
+):
+    """
+    Get a summary of a dropoff prefix.
+
+    es dropoff get-summary -c <type> --prefix <prefix>
+    es dropoff get-summary -c miniseed --prefix demo/
+    es dropoff get-summary -c miniseed --prefix demo/ --submitted-after 2025-01-01T00:00:00Z
+    es dropoff get-summary -c miniseed --prefix demo/ --submitted-before 2025-12-31T23:59:59Z
+    """
+    result = sdk.dropoff.get_summary(
+        category=options.category.value,
+        prefix=prefix,
+        submitted_after=filters.submitted_after,
+        submitted_before=filters.submitted_before,
+    )
+    print_dropoff_summary(result, prefix=prefix)
+
+
 @app.command(name="list-objects")
 def list_objects(
     sdk: Annotated[EarthScopeClient, Depends(get_sdk_refreshed)],
     options: Annotated[DropoffOptions, Depends(get_dropoff_options)],
+    filters: Annotated[FilterOptions, Depends(get_filter_options)],
     prefix: Annotated[
         str,
         typer.Option(help="Filter by object prefix"),
@@ -83,12 +115,18 @@ def list_objects(
     es dropoff list-objects -c miniseed
     es dropoff list-objects -c miniseed --prefix demo/
     es dropoff list-objects -c miniseed --offset 100 --limit 100
+    es dropoff list-objects -c miniseed --status FAILED
+    es dropoff list-objects -c miniseed --submitted-after 2025-01-01T00:00:00Z
+    es dropoff list-objects -c miniseed --submitted-before 2025-12-31T23:59:59Z
     """
     result = sdk.dropoff.list_objects(
         category=options.category.value,
         prefix=prefix,
         offset=options.offset,
         limit=options.limit,
+        submitted_after=filters.submitted_after,
+        submitted_before=filters.submitted_before,
+        status=filters.status,
     )
 
     suffix = ""
@@ -104,7 +142,9 @@ def list_objects(
             next_offset=result.offset + result.limit,
         )
 
-    print(f"[yellow]No objects found for category '{cat_str}'{suffix}")
+    print(
+        f"[yellow]No objects matched specified criteria: category='{cat_str}', prefix='{prefix}', offset={options.offset}, limit={options.limit}', submitted_after={filters.submitted_after}, submitted_before={filters.submitted_before}, status={filters.status}'"
+    )
 
 
 @app.command(name="upload")
@@ -176,22 +216,27 @@ def upload(
     don't overwrite each other and maintains meaningful organization in S3.
     """
     # Parse the input path to get a list of files
+    total_collected = 0
+    succeeded = 0
     files: list[tuple[Path, str]] = []
     for p, k in collect_files(paths):
+        total_collected += 1
         try:
             Validator(p, category=category).validate_all()
         except Exception as e:
             print(f"[red]{e}")
-            raise typer.Exit(code=1)
         else:
             files.append((p, k))
 
     if not files:
-        print(f"[red]No files found in paths: {paths}")
+        paths_str = ", ".join(str(p) for p in paths)
+        print(f"[red]No valid {category.value} files found in paths: {paths_str}")
+        UploadSummary(total=total_collected, succeeded=succeeded).print()
         raise typer.Exit(code=1)
 
+    display = ConcurrentUploadProgressDisplay(len(files))
     try:
-        with ConcurrentUploadProgressDisplay(len(files)) as display:
+        with display:
             sdk.dropoff.put_objects(
                 objects=files,
                 category=category,
@@ -203,3 +248,6 @@ def upload(
     except KeyboardInterrupt:
         print()
         print("[yellow]Upload interrupted. Use the same command to resume the upload.")
+    finally:
+        succeeded = len(display.completed_files)
+        UploadSummary(total=total_collected, succeeded=succeeded).print()

{earthscope_cli-1.1.0 → earthscope_cli-1.1.2}/src/earthscope_cli/dropoff/util.py

@@ -18,6 +18,13 @@ class PaginationOptions:
     limit: int
 
 
+@dataclass
+class FilterOptions:
+    submitted_before: Optional[datetime] = None
+    submitted_after: Optional[datetime] = None
+    status: Optional[str] = None
+
+
 @dataclass
 class DropoffOptions(PaginationOptions):
     category: DropoffCategory
@@ -86,6 +93,48 @@ def get_category(
     return DropoffCategory(cat_str)
 
 
+def get_filter_options(
+    submitted_after: Annotated[
+        Optional[datetime],
+        typer.Option(
+            "--submitted-after",
+            help="Filter results submitted after this datetime (ISO 8601)",
+            formats=[
+                "%Y-%m-%dT%H:%M:%S%z",
+                "%Y-%m-%dT%H:%M:%SZ",
+                "%Y-%m-%d%z",
+                "%Y-%m-%dZ",
+            ],
+        ),
+    ] = None,
+    submitted_before: Annotated[
+        Optional[datetime],
+        typer.Option(
+            "--submitted-before",
+            help="Filter results submitted before this datetime (ISO 8601)",
+            formats=[
+                "%Y-%m-%dT%H:%M:%S%z",
+                "%Y-%m-%dT%H:%M:%SZ",
+                "%Y-%m-%d%z",
+                "%Y-%m-%dZ",
+            ],
+        ),
+    ] = None,
+    status: Annotated[
+        Optional[str],
+        typer.Option(
+            "--status",
+            help="Filter results by status",
+        ),
+    ] = None,
+) -> FilterOptions:
+    return FilterOptions(
+        submitted_before=submitted_before,
+        submitted_after=submitted_after,
+        status=status,
+    )
+
+
 def get_dropoff_options(
     category: Annotated[DropoffCategory, Depends(get_category)],
     offset: Annotated[

{earthscope_cli-1.1.0 → earthscope_cli-1.1.2}/src/earthscope_cli/login.py

@@ -1,15 +1,12 @@
-from contextlib import suppress
 from textwrap import dedent
 from typing import TYPE_CHECKING
 
 import typer
+from rich import print
 from typer_di import Depends, TyperDI
 
 from earthscope_cli.common import get_sdk
 
-with suppress(ModuleNotFoundError):
-    from rich import print
-
 if TYPE_CHECKING:
     from earthscope_sdk import EarthScopeClient
 

{earthscope_cli-1.1.0 → earthscope_cli-1.1.2}/src/earthscope_cli/main.py

@@ -1,4 +1,3 @@
-from contextlib import suppress
 from typing import Annotated
 
 import typer
@@ -10,15 +9,13 @@ from earthscope_sdk.auth.error import (
     NoTokensError,
     UnauthorizedError,
 )
+from rich import print
 
 from earthscope_cli import __version__ as cli_version
 from earthscope_cli import debug, login, user
 from earthscope_cli.dropoff.typer import app as dropoff_app
 from earthscope_cli.util import ErrorHandlingTyper
 
-with suppress(ModuleNotFoundError):
-    from rich import print
-
 app = ErrorHandlingTyper(
     pretty_exceptions_enable=False,
 )

{earthscope_cli-1.1.0 → earthscope_cli-1.1.2}/src/earthscope_cli/user.py

@@ -1,14 +1,10 @@
-from contextlib import suppress
-
 import typer
+from rich import print
 from typer_di import Depends, TyperDI
 
 from earthscope_cli import login
 from earthscope_cli.common import get_sdk, get_sdk_refreshed
 
-with suppress(ModuleNotFoundError):
-    from rich import print
-
 app = TyperDI()
 
 # Register aliases to login/logout

earthscope_cli-1.1.2/src/earthscope_cli.egg-info/PKG-INFO

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: earthscope-cli
+Version: 1.1.2
+Summary: A CLI for the EarthScope API
+Author-email: EarthScope <data-help@earthscope.org>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://gitlab.com/earthscope/public/earthscope-cli
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: typer<0.24.0
+Requires-Dist: typer-di>=0.1.3
+Requires-Dist: earthscope-sdk>=1.3.1
+Requires-Dist: rich>=13.8.0
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: bumpver; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: twine>=6.0.1; extra == "dev"
+Requires-Dist: pip-tools; extra == "dev"
+Dynamic: license-file
+
+# EarthScope CLI
+
+A CLI for interacting with EarthScope's APIs
+
+## Getting Started
+
+### Requirements
+
+To use the CLI you must have:
+
+- Registered an account with Earthscope ([sign up now](https://earthscope.org/user/login)). See [here](https://www.earthscope.org/data/authentication) for more information
+- Python >= 3.9
+
+### Installation
+
+Install from PyPI
+
+```shell
+pip install earthscope-cli
+```
+
+### Usage
+
+A new `es` command is available in your terminal. Use `--help` with any command to explore commands and options.
+
+```shell
+es --help
+es user --help
+```
+
+#### Login to your EarthScope account
+
+```shell
+es login
+```
+
+This will open your browser to a confirmation page with the same code shown on your command line.
+If you are on a device that does not have a web browser, you can copy the displayed url in a browser on another device (personal computer, mobile device, etc...) and complete the confirmation there.
+
+The `es login` command will save your token locally. If this token is deleted, you will need to re-authenticate (login) to retrieve your token again.
+
+#### Get your access token
+
+```shell
+es user get-access-token
+```
+
+The `get-access-token` command will display your access token. If your access token is close to expiration or expired,
+the default behavior is to automatically refresh your token.
+
+If you want to manually refresh your token:
+
+```shell
+es user refresh-access-token
+```
+
+Never share your tokens. If you think your token has been compromised, please revoke your refresh token and re-authenticate (login):
+
+```shell
+es user revoke-refresh-token
+es login
+```
+
+#### Get your user profile
+
+```shell
+es user get-profile
+```
+
+## Documentation
+
+For detailed usage examples, authentication guides, and advanced features, see the [full documentation](https://docs.earthscope.org/projects/CLI).
+
+## EarthScope SDK
+
+If you would like to use EarthScope APIs from python, please use the [earthscope-sdk](https://gitlab.com/earthscope/public/earthscope-sdk/) directly.
+
+## FAQ/troubleshooting
+
+- **How long does my access token last?**
+  - Your access token lasts 24 hours. Your refresh token can be used to refresh your access token.
+- **How long does my refresh token last?**
+  - Your refresh token will never expire - unless you are inactive (do not use it) for one year.
+    If it does expire, you will need to re-authenticate to get a new access and refresh token.
+- **What is a refresh token and how does the CLI use it?**
+  - A refresh token is a special token that is used to renew your access token without you needing to log in again.
+    The refresh token is obtained from your access token, and using the `es user get-access-token` command will automatically
+    renew your access token if it is close to expiration. You can 'manually' refresh your access token by using the command `es user refresh-access-token`.
+    If your access token is compromised, you can revoke your refresh token using `es user revoke-refresh-token`. Once your access token expires,
+    it can no longer be renewed and you will need to re-login.
+- **Should I hard-code my access token into my script?**
+  - No. We recommend you use the cli commands to retrieve your access tokens in your scripts.
+    This way your access token will not be compromised by anyone viewing your script.
+    The access token only lasts 24 hours and cannot be used afterwards unless refreshed.

{earthscope_cli-1.1.0 → earthscope_cli-1.1.2}/src/earthscope_cli.egg-info/requires.txt

@@ -1,6 +1,6 @@
-typer-slim>=0.17.3
+typer<0.24.0
 typer-di>=0.1.3
-earthscope-sdk>=1.3.0
+earthscope-sdk>=1.3.1
 rich>=13.8.0
 
 [dev]
@@ -9,5 +9,5 @@ bumpver
 build
 pre-commit
 pytest
-twine
+twine>=6.0.1
 pip-tools