mapchete-hub-cli 2025.8.0__tar.gz

mapchete_hub_cli-2025.8.0/.gitignore

@@ -0,0 +1,15 @@
+*.coverage*
+*.egg-info
+.eggs
+*.pyc
+__pycache__
+.pytest_cache
+*.gpkg
+htmlcov
+.env
+.credentials.map
+ec2_user_data.sh
+spot_config.json
+dask-worker-space/
+dist/
+.vscode/

mapchete_hub_cli-2025.8.0/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2018 - 2025 EOX IT Services
+
+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.

mapchete_hub_cli-2025.8.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: mapchete-hub-cli
+Version: 2025.8.0
+Summary: CLI and Python bindings to mapchete Hub API.
+Project-URL: Homepage, https://gitlab.eox.at/maps/mapchete_hub_cli
+Author-email: Joachim Ungar <joachim.ungar@eox.at>, Petr Sevcik <petr.sevcik@eox.at>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Dist: click
+Requires-Dist: click-spinner
+Requires-Dist: oyaml
+Requires-Dist: pydantic
+Requires-Dist: python-dateutil
+Requires-Dist: requests
+Requires-Dist: tqdm
+Provides-Extra: test
+Requires-Dist: mapchete-hub>=2023.12.0; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Requires-Dist: pytest-env; extra == 'test'
+Requires-Dist: requests; extra == 'test'
+Provides-Extra: zones
+Requires-Dist: mapchete; extra == 'zones'
+Requires-Dist: shapely; extra == 'zones'
+Requires-Dist: tilematrix; extra == 'zones'
+Description-Content-Type: text/x-rst
+
+mapchete Hub CLI
+================
+
+A command line interface for mapchete Hub.
+
+.. image:: https://img.shields.io/pypi/v/mapchete-hub-cli.svg
+  :target: https://pypi.org/project/mapchete-hub-cli/
+
+.. image:: https://img.shields.io/pypi/l/mapchete-hub-cli.svg
+  :target: https://github.com/mapchete/mapchete-hub-cli/blob/main/LICENSE
+
+.. image:: https://img.shields.io/github/actions/workflow/status/mapchete/mapchete-hub-cli/python-package.yml?label=tests
+  :target: https://github.com/mapchete/mapchete-hub-cli/actions
+
+.. image:: https://codecov.io/gh/mapchete/mapchete-hub-cli/graph/badge.svg?token=P1NV2UFVWK
+  :target: https://codecov.io/gh/mapchete/mapchete-hub-cli
+
+.. image:: https://img.shields.io/github/repo-size/mapchete/mapchete-hub-cli
+  :target: https://github.com/mapchete/mapchete-hub-cli
+
+About mapchete Hub CLI
+========================
+
+The mapchete Hub CLI provides a user-friendly command line interface (``mhub``) to interact with a running mapchete Hub instance. It simplifies the process of submitting, monitoring, and managing processing jobs without needing to write custom scripts or use tools like `curl`.
+
+This CLI is the recommended tool for users who want to script workflows or manage mapchete Hub jobs from their terminal.
+
+
+Key Features
+============
+
+* **💻 Full Job Lifecycle Management**: Intuitive commands to ``execute``, ``job`` (status), ``jobs`` (list), ``cancel``, and ``retry`` processing jobs.
+* **⚙️ Inspection**: List available ``processes`` on a remote mapchete Hub and check remote package ``--remote-versions``.
+* **🔒 Authentication Support**: Handles basic authentication via command line options (``-u``, ``-p``) or environment variables.
+* **🤖 Script-Friendly**: Designed for easy integration into automated scripts and workflows.
+
+
+Installation
+============
+
+Install the CLI and its dependencies from PyPI:
+
+.. code-block:: bash
+
+   pip install mapchete-hub-cli
+
+
+Quickstart
+==========
+
+**1. Point to your mapchete Hub**
+
+All commands require you to specify the mapchete Hub's URL using the ``-h`` or ``--host`` option. If the mapchete Hub is running on the same machine with default settings (``0.0.0.0:5000``), you may not need this option.
+
+**2. List Available Processes**
+
+You can see what processes are available on the target mapchete Hub instance:
+
+.. code-block:: bash
+
+   mhub -h 0.0.0.0:5000 processes
+
+**3. Prepare a mapchete File**
+
+Create a `mapchete process file <https://github.com/mapchete/mapchete>`_ using YAML syntax. **Note that all input and output paths must be absolute**, as they are resolved on the remote server.
+
+For example, `hillshade.mapchete`:
+
+.. code-block:: yaml
+
+   process: mapchete.processes.examples.hillshade
+   zoom_levels:
+     - 10
+   pyramid:
+     grid: geodetic
+   input:
+     dem: https://data.example.com/path/to/dem.tif
+   output:
+     path: s3://my-bucket/path/to/hillshade_output
+     format: GTiff
+
+**4. Execute the Process**
+
+Use the ``execute`` command to send the job to the mapchete Hub.
+
+.. code-block:: bash
+
+   mhub -h 0.0.0.0:5000 execute hillshade.mapchete
+
+The mapchete Hub will return a unique `job_id`:
+
+.. code-block:: text
+
+   6227b68b-b7e6-4f40-a396-85763197f481
+
+**5. Check Job Status and Progress**
+
+Use the `job_id` with the ``job`` command to get a detailed status report, or ``progress`` for a quick look at the progress percentage.
+
+.. code-block:: bash
+
+   # Get detailed status
+   mhub -h 0.0.0.0:5000 job 6227b68b-b7e6-4f40-a396-85763197f481
+
+   # Get just the progress
+   mhub -h 0.0.0.0:5000 progress 6227b68b-b7e6-4f40-a396-85763197f481
+
+**6. Manage Jobs**
+
+You can also list all jobs or cancel a running job:
+
+.. code-block:: bash
+
+   # List all jobs on the mapchete Hub
+   mhub -h 0.0.0.0:5000 jobs
+
+   # Cancel a specific job
+   mhub -h 0.0.0.0:5000 cancel 6227b68b-b7e6-4f40-a396-85763197f481
+
+
+Contributing
+============
+
+This is an open-source project and we welcome contributions! Please see the `Contributing Guide <https://github.com/mapchete/mapchete/blob/main/CONTRIBUTING.md>`_ in the main ``mapchete`` repository for guidelines on how to get started.
+
+Acknowledgements
+================
+
+The initial development of this project was made possible with the resources and support of `EOX IT Services GmbH <https://eox.at/>`_.

mapchete_hub_cli-2025.8.0/README.rst

@@ -0,0 +1,129 @@
+mapchete Hub CLI
+================
+
+A command line interface for mapchete Hub.
+
+.. image:: https://img.shields.io/pypi/v/mapchete-hub-cli.svg
+  :target: https://pypi.org/project/mapchete-hub-cli/
+
+.. image:: https://img.shields.io/pypi/l/mapchete-hub-cli.svg
+  :target: https://github.com/mapchete/mapchete-hub-cli/blob/main/LICENSE
+
+.. image:: https://img.shields.io/github/actions/workflow/status/mapchete/mapchete-hub-cli/python-package.yml?label=tests
+  :target: https://github.com/mapchete/mapchete-hub-cli/actions
+
+.. image:: https://codecov.io/gh/mapchete/mapchete-hub-cli/graph/badge.svg?token=P1NV2UFVWK
+  :target: https://codecov.io/gh/mapchete/mapchete-hub-cli
+
+.. image:: https://img.shields.io/github/repo-size/mapchete/mapchete-hub-cli
+  :target: https://github.com/mapchete/mapchete-hub-cli
+
+About mapchete Hub CLI
+========================
+
+The mapchete Hub CLI provides a user-friendly command line interface (``mhub``) to interact with a running mapchete Hub instance. It simplifies the process of submitting, monitoring, and managing processing jobs without needing to write custom scripts or use tools like `curl`.
+
+This CLI is the recommended tool for users who want to script workflows or manage mapchete Hub jobs from their terminal.
+
+
+Key Features
+============
+
+* **💻 Full Job Lifecycle Management**: Intuitive commands to ``execute``, ``job`` (status), ``jobs`` (list), ``cancel``, and ``retry`` processing jobs.
+* **⚙️ Inspection**: List available ``processes`` on a remote mapchete Hub and check remote package ``--remote-versions``.
+* **🔒 Authentication Support**: Handles basic authentication via command line options (``-u``, ``-p``) or environment variables.
+* **🤖 Script-Friendly**: Designed for easy integration into automated scripts and workflows.
+
+
+Installation
+============
+
+Install the CLI and its dependencies from PyPI:
+
+.. code-block:: bash
+
+   pip install mapchete-hub-cli
+
+
+Quickstart
+==========
+
+**1. Point to your mapchete Hub**
+
+All commands require you to specify the mapchete Hub's URL using the ``-h`` or ``--host`` option. If the mapchete Hub is running on the same machine with default settings (``0.0.0.0:5000``), you may not need this option.
+
+**2. List Available Processes**
+
+You can see what processes are available on the target mapchete Hub instance:
+
+.. code-block:: bash
+
+   mhub -h 0.0.0.0:5000 processes
+
+**3. Prepare a mapchete File**
+
+Create a `mapchete process file <https://github.com/mapchete/mapchete>`_ using YAML syntax. **Note that all input and output paths must be absolute**, as they are resolved on the remote server.
+
+For example, `hillshade.mapchete`:
+
+.. code-block:: yaml
+
+   process: mapchete.processes.examples.hillshade
+   zoom_levels:
+     - 10
+   pyramid:
+     grid: geodetic
+   input:
+     dem: https://data.example.com/path/to/dem.tif
+   output:
+     path: s3://my-bucket/path/to/hillshade_output
+     format: GTiff
+
+**4. Execute the Process**
+
+Use the ``execute`` command to send the job to the mapchete Hub.
+
+.. code-block:: bash
+
+   mhub -h 0.0.0.0:5000 execute hillshade.mapchete
+
+The mapchete Hub will return a unique `job_id`:
+
+.. code-block:: text
+
+   6227b68b-b7e6-4f40-a396-85763197f481
+
+**5. Check Job Status and Progress**
+
+Use the `job_id` with the ``job`` command to get a detailed status report, or ``progress`` for a quick look at the progress percentage.
+
+.. code-block:: bash
+
+   # Get detailed status
+   mhub -h 0.0.0.0:5000 job 6227b68b-b7e6-4f40-a396-85763197f481
+
+   # Get just the progress
+   mhub -h 0.0.0.0:5000 progress 6227b68b-b7e6-4f40-a396-85763197f481
+
+**6. Manage Jobs**
+
+You can also list all jobs or cancel a running job:
+
+.. code-block:: bash
+
+   # List all jobs on the mapchete Hub
+   mhub -h 0.0.0.0:5000 jobs
+
+   # Cancel a specific job
+   mhub -h 0.0.0.0:5000 cancel 6227b68b-b7e6-4f40-a396-85763197f481
+
+
+Contributing
+============
+
+This is an open-source project and we welcome contributions! Please see the `Contributing Guide <https://github.com/mapchete/mapchete/blob/main/CONTRIBUTING.md>`_ in the main ``mapchete`` repository for guidelines on how to get started.
+
+Acknowledgements
+================
+
+The initial development of this project was made possible with the resources and support of `EOX IT Services GmbH <https://eox.at/>`_.

mapchete_hub_cli-2025.8.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mapchete-hub-cli"
+dynamic = ["version"]
+description = "CLI and Python bindings to mapchete Hub API."
+readme = "README.rst"
+license = "MIT"
+authors = [
+    { name = "Joachim Ungar", email = "joachim.ungar@eox.at" },
+    { name = "Petr Sevcik", email = "petr.sevcik@eox.at" }
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Scientific/Engineering :: GIS",
+]
+dependencies = [
+    "click",
+    "click_spinner",
+    "python-dateutil",
+    "oyaml",
+    "pydantic",
+    "requests",
+    "tqdm",
+]
+
+[project.optional-dependencies]
+zones = [
+    "mapchete",
+    "shapely",
+    "tilematrix"
+]
+test = [
+    "mapchete_hub>=2023.12.0",
+    "pytest",
+    "pytest-cov",
+    "pytest-env",
+    "requests",
+]
+
+[project.scripts]
+mhub = "mapchete_hub_cli.cli.main:mhub"
+
+[project.entry-points."mapchete_hub_cli.cli.commands"]
+cancel = "mapchete_hub_cli.cli.cancel:cancel"
+clean = "mapchete_hub_cli.cli.clean:clean"
+execute = "mapchete_hub_cli.cli.execute:execute"
+job = "mapchete_hub_cli.cli.job:job"
+jobs = "mapchete_hub_cli.cli.jobs:jobs"
+processes = "mapchete_hub_cli.cli.processes:processes"
+progress = "mapchete_hub_cli.cli.progress:progress"
+show_remote_version = "mapchete_hub_cli.cli.show_remote_version:show_remote_version"
+retry = "mapchete_hub_cli.cli.retry:retry"
+test-run = "mapchete_hub_cli.cli.test:test_run"
+
+
+[project.urls]
+Homepage = "https://gitlab.eox.at/maps/mapchete_hub_cli"
+
+[tool.hatch.version]
+path = "src/mapchete_hub_cli/__init__.py"
+
+[tool.hatch.build.targets.sdist]
+include = [
+    "/src",
+]

mapchete_hub_cli-2025.8.0/src/mapchete_hub_cli/__init__.py

@@ -0,0 +1,22 @@
+from mapchete_hub_cli.client import (
+    COMMANDS,
+    DEFAULT_TIMEOUT,
+    JOB_STATUSES,
+    MHUB_CLI_ZONES_WAIT_TILES_COUNT,
+    MHUB_CLI_ZONES_WAIT_TIME_SECONDS,
+    Client,
+    Job,
+    load_mapchete_config,
+)
+
+__all__ = [
+    "Client",
+    "Job",
+    "COMMANDS",
+    "DEFAULT_TIMEOUT",
+    "JOB_STATUSES",
+    "MHUB_CLI_ZONES_WAIT_TILES_COUNT",
+    "MHUB_CLI_ZONES_WAIT_TIME_SECONDS",
+    "load_mapchete_config",
+]
+__version__ = "2025.8.0"

mapchete_hub_cli-2025.8.0/src/mapchete_hub_cli/cli/__init__.py

@@ -0,0 +1,4 @@
+from mapchete_hub_cli.cli.main import mhub
+
+
+__all__ = ["mhub"]

mapchete_hub_cli-2025.8.0/src/mapchete_hub_cli/cli/cancel.py

@@ -0,0 +1,55 @@
+import logging
+
+import click
+
+from mapchete_hub_cli.cli import options
+from mapchete_hub_cli.client import Client, Jobs
+
+logger = logging.getLogger(__name__)
+
+
+@click.command(short_help="Cancel jobs.")
+@options.opt_job_ids
+@options.opt_output_path
+@options.opt_status
+@options.opt_command
+@options.opt_since_no_default
+@options.opt_until
+@options.opt_job_name
+@options.opt_force
+@options.opt_debug
+@click.pass_context
+def cancel(ctx, job_ids, debug=False, force=False, **kwargs):
+    """Cancel jobs and their follow-up jobs if batch was submitted."""
+    client = Client(**ctx.obj)
+    try:
+        kwargs.update(from_date=kwargs.pop("since"), to_date=kwargs.pop("until"))
+
+        if job_ids:
+            jobs = Jobs.from_jobs([client.job(job_id) for job_id in job_ids])
+
+        else:
+            if all([v is None for v in kwargs.values()]):  # pragma: no cover
+                click.echo(ctx.get_help())
+                raise click.UsageError(
+                    "Please either provide one or more job IDs or other search values."
+                )
+            jobs = client.jobs(**kwargs)
+
+        unfinished_jobs = jobs.unfinished_jobs(msg_writer=click.echo)
+
+        if not unfinished_jobs:  # pragma: no cover
+            click.echo("No revokable jobs found.")
+            return
+
+        for job in unfinished_jobs:
+            click.echo(job.job_id)
+        if force or click.confirm(
+            f"Do you really want to cancel {len(unfinished_jobs)} job(s)?", abort=True
+        ):
+            unfinished_jobs.cancel(msg_writer=click.echo)
+
+    except Exception as e:  # pragma: no cover
+        if debug:
+            raise
+        raise click.ClickException(e)

mapchete_hub_cli-2025.8.0/src/mapchete_hub_cli/cli/clean.py

@@ -0,0 +1,79 @@
+import logging
+
+import click
+
+from mapchete_hub_cli.cli import options
+from mapchete_hub_cli.client import Client
+
+logger = logging.getLogger(__name__)
+
+
+@click.command(short_help="Abort stalled jobs.")
+@click.pass_context
+@click.option(
+    "--inactive-since",
+    type=click.STRING,
+    default="5h",
+    help="Time since jobs have been inactive.",
+    show_default=True,
+)
+@click.option(
+    "--pending-since",
+    type=click.STRING,
+    default="3d",
+    help="Time since jobs have been pending.",
+    show_default=True,
+)
+@click.option(
+    "--skip-dashboard-check", is_flag=True, help="Skip dashboard availability check."
+)
+@click.option("--retry", is_flag=True, help="Retry instead of cancel stalled jobs.")
+@options.opt_use_old_image
+@options.opt_force
+@options.opt_debug
+def clean(
+    ctx: click.Context,
+    inactive_since: str = "5h",
+    pending_since: str = "3d",
+    skip_dashboard_check: bool = False,
+    retry: bool = False,
+    use_old_image: bool = False,
+    force: bool = False,
+    debug: bool = False,
+):
+    """
+    Checks for probably stalled jobs and offers to cancel or retry them.
+
+    The check looks at three properties:\n
+    - jobs which are pending for too long\n
+    - jobs which are parsing|initializing|running but have been inactive for too long\n
+    - jobs which are running, have a scheduler but scheduler dashboard is not available\n
+    """
+    try:
+        stalled_jobs = Client(**ctx.obj).stalled_jobs(
+            inactive_since=inactive_since,
+            pending_since=pending_since,
+            check_inactive_dashboard=not skip_dashboard_check,
+            msg_writer=click.echo,
+        )
+        if stalled_jobs:  # pragma: no cover
+            click.echo(f"found {len(stalled_jobs)} potentially stalled jobs:")
+            for job in stalled_jobs:
+                click.echo(job.job_id)
+            if force or click.confirm(
+                f"Do you really want to cancel {'and retry ' if retry else ''}{len(stalled_jobs)} job(s)?",
+                abort=True,
+            ):
+                if retry:
+                    stalled_jobs.cancel_and_retry(
+                        msg_writer=click.echo, use_old_image=use_old_image
+                    )
+                else:
+                    stalled_jobs.cancel(msg_writer=click.echo)
+        else:
+            click.echo("No stalled jobs found.")
+
+    except Exception as exc:  # pragma: no cover
+        if debug:
+            raise
+        raise click.ClickException(str(exc))