hypershell 2.7.0__tar.gz → 2.7.2__tar.gz

hypershell-2.7.2/.github/FUNDING.yml

@@ -0,0 +1,12 @@
+# These are supported funding model platforms
+
+github: glentner
+patreon: # Replace with a single Patreon username
+open_collective: # Replace with a single Open Collective username
+ko_fi: # Replace with a single Ko-fi username
+tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+liberapay: # Replace with a single Liberapay username
+issuehunt: # Replace with a single IssueHunt username
+otechie: # Replace with a single Otechie username
+custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

hypershell-2.7.2/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+name: Publish
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Publish to PyPI
+        run: uv build && uv publish --token ${{ secrets.PYPI_TOKEN }}

hypershell-2.7.2/.github/workflows/tests.yml

@@ -0,0 +1,24 @@
+name: Tests
+on:
+  push:
+    branches: [ master, develop ]
+  pull_request:
+    branches: [ develop ]
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [ '3.9', '3.10', '3.11', '3.12', '3.13' ]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          cache-dependency-glob: "uv.lock"
+
+      - name: Run tests
+        run: uv run --python ${{ matrix.python-version }} pytest -v

{hypershell-2.7.0 → hypershell-2.7.2}/Apptainer

@@ -3,7 +3,7 @@ From: python:3.13-slim
 Stage: final
 
 %labels
-  Version="2.7.0"
+  Version="2.7.2"
   Author="glentner@purdue.edu"
 
 %files

{hypershell-2.7.0 → hypershell-2.7.2}/Dockerfile

@@ -1,7 +1,7 @@
 FROM python:3.13-slim
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
 
-LABEL version="2.7.0"
+LABEL version="2.7.2"
 LABEL authors="glentner@purdue.edu"
 LABEL org.opencontainers.image.source="https://github.com/hypershell/hypershell"
 LABEL org.opencontainers.image.description="HyperShell Base Image"

{hypershell-2.7.0 → hypershell-2.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypershell
-Version: 2.7.0
+Version: 2.7.2
 Summary: A cross-platform, high-throughput computing utility for processing shell commands over a distributed, asynchronous queue.
 Author-email: Geoffrey Lentner <glentner@purdue.edu>
 License-Expression: Apache-2.0
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Utilities
 Requires-Python: >=3.9
 Requires-Dist: cmdkit[toml]>=2.7.7
@@ -41,14 +42,14 @@ HyperShell v2: Distributed Task Execution for HPC
     :target: https://github.com/hypershell/hypershell/releases
     :alt: Github Release
 
-.. image:: https://static.pepy.tech/badge/hypershell/month
-    :target: https://pypi.org/project/hypershell/
-    :alt: PyPI Monthly Downloads
-
 .. image:: https://img.shields.io/badge/Python-3.9+-blue.svg
     :target: https://www.python.org/downloads
     :alt: Python Versions
 
+.. image:: https://static.pepy.tech/badge/hypershell/month
+    :target: https://pypi.org/project/hypershell/
+    :alt: PyPI Monthly Downloads
+
 .. image:: https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg
     :target: https://www.contributor-covenant.org/version/2/1/code_of_conduct/
     :alt: Code of Conduct
@@ -57,6 +58,10 @@ HyperShell v2: Distributed Task Execution for HPC
     :target: https://hypershell.readthedocs.io/en/latest/?badge=latest
     :alt: Documentation Status
 
+.. image:: https://github.com/hypershell/hypershell/actions/workflows/tests.yml/badge.svg
+    :target: https://github.com/hypershell/hypershell/actions/workflows/tests.yml
+    :alt: Tests
+
 |
 
 *HyperShell* is an elegant, cross-platform, high-throughput computing utility for

{hypershell-2.7.0 → hypershell-2.7.2}/README.rst

@@ -9,14 +9,14 @@ HyperShell v2: Distributed Task Execution for HPC
     :target: https://github.com/hypershell/hypershell/releases
     :alt: Github Release
 
-.. image:: https://static.pepy.tech/badge/hypershell/month
-    :target: https://pypi.org/project/hypershell/
-    :alt: PyPI Monthly Downloads
-
 .. image:: https://img.shields.io/badge/Python-3.9+-blue.svg
     :target: https://www.python.org/downloads
     :alt: Python Versions
 
+.. image:: https://static.pepy.tech/badge/hypershell/month
+    :target: https://pypi.org/project/hypershell/
+    :alt: PyPI Monthly Downloads
+
 .. image:: https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg
     :target: https://www.contributor-covenant.org/version/2/1/code_of_conduct/
     :alt: Code of Conduct
@@ -25,6 +25,10 @@ HyperShell v2: Distributed Task Execution for HPC
     :target: https://hypershell.readthedocs.io/en/latest/?badge=latest
     :alt: Documentation Status
 
+.. image:: https://github.com/hypershell/hypershell/actions/workflows/tests.yml/badge.svg
+    :target: https://github.com/hypershell/hypershell/actions/workflows/tests.yml
+    :alt: Tests
+
 |
 
 *HyperShell* is an elegant, cross-platform, high-throughput computing utility for

hypershell-2.7.2/docs/_include/config_desc.rst

@@ -0,0 +1 @@
+Manage configuration.

hypershell-2.7.2/docs/_include/config_help.rst

@@ -0,0 +1,26 @@
+Commands
+^^^^^^^^
+
+``get``
+    Get configuration option.
+
+``set``
+    Set configuration option.
+
+``edit``
+    Edit configuration with default editor.
+
+``which``
+    Show origin of configuration option.
+
+Options
+^^^^^^^
+
+``--system``
+    Show system-level config path.
+
+``--user``
+    Show user-level config path.
+
+``--local``
+    Show local-level config path.

hypershell-2.7.2/docs/_include/config_usage.rst

@@ -0,0 +1,9 @@
+``hs`` ``config`` ``[-h]`` ``[--system | --local | --user]``
+
+``hs`` ``config`` ``get`` ``[-h]`` ``SECTION[...].VAR`` ``[-x]`` ``[-r]`` ``[--system | --user | --local | --default]``
+
+``hs`` ``config`` ``set`` ``[-h]`` ``SECTION[...].VAR`` ``VALUE`` ``[--system | --user | --local]``
+
+``hs`` ``config`` ``edit`` ``[-h]`` ``[--system | --user | --local]``
+
+``hs`` ``config`` ``which`` ``[-h]`` ``SECTION[...].VAR`` ``[--site]``

{hypershell-2.7.0 → hypershell-2.7.2}/docs/blog/index.rst

@@ -153,6 +153,7 @@ a few quality of life improvements, and a fix for SSH-mode.
     :hidden:
     :maxdepth: 1
 
+    20250504_2_7_0_release
     20250405_2_6_6_release
     20250215_2_6_5_release
     20241231_2_6_1_release

hypershell-2.7.2/docs/cli/config.rst

@@ -0,0 +1,18 @@
+.. _cli_config:
+
+Config
+======
+
+Usage
+-----
+
+.. include:: ../_include/config_usage.rst
+
+Description
+-----------
+
+.. include:: ../_include/config_desc.rst
+
+|
+
+.. include:: ../_include/config_help.rst

{hypershell-2.7.0 → hypershell-2.7.2}/docs/cli/index.rst

@@ -27,6 +27,7 @@ Subcommands
     run <task_run>
     list <task_search>
     update <task_update>
+    config <config>
     config get <config_get>
     config set <config_set>
     config edit <config_edit>

{hypershell-2.7.0 → hypershell-2.7.2}/docs/conf.py

@@ -72,7 +72,7 @@ html_css_files = [
     "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/solid.min.css",
     "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/brands.min.css",
 ]
-html_favicon = '_static/logo.svg'
+html_favicon = '_static/logo-dark-mode.png'
 html_theme_options = {
     # 'announcement': 'See Installation page for not on PyPI package name issue!',
     'sidebar_hide_name': True,

{hypershell-2.7.0 → hypershell-2.7.2}/docs/getting_started.rst

@@ -13,7 +13,7 @@ the top-level entry point *script* on your `PATH`. The well-known `uv <https://d
 utility handles all of this nicely for unprivileged users installing for themselves.
 
 See the :ref:`installation <install>` guide for more options and additional notes and
-recommendations.
+recommendations, including package `extras` for PostgreSQL, UUIDv7, etc.
 
 
 .. tab:: uv
@@ -56,7 +56,7 @@ will manage tasks entirely within memory.
 
     .. code-block:: shell
 
-        seq 4 | hs cluster -t 'echo {}'
+        seq 4 | hsx -t 'echo {}'
 
     .. details:: Output
 
@@ -81,7 +81,7 @@ see additional detail about what is running, where, and when.
 
     .. code-block:: shell
 
-        hs cluster tasks.in -N16 --ssh-group=xyz --capture
+        hsx tasks.in -N16 --ssh-group=xyz --capture
 
     .. details:: Logs
 
@@ -107,7 +107,7 @@ example we stagger the launch process over one minute.
 
     .. code-block:: shell
 
-        hs cluster tasks.in -N128 -b128 --launcher=srun --max-retries=2 --delay-start=-60 >task.out
+        hsx tasks.in -N128 -b128 --launcher=srun --max-retries=2 --delay-start=-60 >task.out
 
     .. details:: Logs
 
@@ -175,7 +175,7 @@ expansion. Many meta-patterns are supported (see full overview of :ref:`template
 
     .. code-block:: shell
 
-        hs cluster tasks.in -N12 -t './some_program.py {} >outputs/{/-}.out'
+        hsx tasks.in -N12 -t './some_program.py {} >outputs/{/-}.out'
 
 Capturing `stdout` and `stderr` is supported directly in fact with the ``--capture`` option.
 See the full documentation for environment variables under :ref:`configuration <config>`.

{hypershell-2.7.0 → hypershell-2.7.2}/docs/index.rst

@@ -15,10 +15,18 @@ Release v\ |release| (:ref:`Getting Started <getting_started>`)
     :target: https://www.python.org/downloads
     :alt: Python Versions
 
+.. image:: https://static.pepy.tech/badge/hypershell/month
+    :target: https://pypi.org/project/hypershell/
+    :alt: PyPI Monthly Downloads
+
 .. image:: https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg
     :target: https://www.contributor-covenant.org/version/2/1/code_of_conduct/
     :alt: Code of Conduct
 
+.. image:: https://github.com/hypershell/hypershell/actions/workflows/tests.yml/badge.svg
+    :target: https://github.com/hypershell/hypershell/actions/workflows/tests.yml
+    :alt: Tests
+
 |
 
 .. include:: _include/desc.rst

hypershell-2.7.2/docs/install.rst

@@ -0,0 +1,322 @@
+.. _install:
+
+Installation
+============
+
+|
+
+Installing *HyperShell* can take several forms. At the end of the day it is a Python package
+and needs to live within some prefix and be tied to some Python runtime. As a system utility
+we probably do not want to expose our dependencies to other user environments incidentally.
+For these reasons, it is recommended to isolate *HyperShell* within its own virtual environment
+and only exposed the top-level entry point *script* to the users `PATH`.
+
+-------------------
+
+Basic Installation
+------------------
+
+|
+
+The `uv <https://docs.astral.sh/uv/>`_ utility wraps all of this up nicely for user-level
+installations. On any platform, if installing for yourself, especially if you lack root
+or administrative privileges, we recommend the following.
+
+.. admonition:: Install HyperShell using uv
+    :class: note
+
+    .. code-block:: shell
+
+        uv tool install hypershell
+
+
+For `macOS` users we can accomplish the same thing with `Homebrew <https://brew.sh>`_.
+This formula essentially does the same thing but managed by ``brew`` instead.
+
+
+.. admonition:: Install HyperShell using Homebrew
+    :class: note
+
+    .. code-block:: shell
+
+        brew tap hypershell/tap
+        brew install hypershell
+
+
+The `macOS` Homebrew installation method automatically includes the package extras needed
+for using PostgreSQL as a backend but does not include the UUIDv7 extra. When installing
+the package directly from the package index, the following extras are available
+
+* ``postgres``: includes ``psycopg2`` for using PostgreSQL
+* ``uuid7``: includes ``uuid-utils`` and to auto-enable use of UUIDv7 for task IDs.
+
+For example, you could install HyperShell with the following:
+
+.. admonition:: Install HyperShell with PostgreSQL support
+    :class: note
+
+    .. code-block:: shell
+
+        uv tool install 'hypershell[postgres]' --python 3.13
+
+
+-------------------
+
+Linux Packages
+--------------
+
+|
+
+We want to support Linux package managers directly to make it easy to use HyperShell as a system-level
+tool with minimal effort to add to your environment. The following Linux distributions are currently
+being considered but may or may not be available currently.
+
+|
+
+Debian / Ubuntu (coming soon)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. admonition:: Install as a Debian package
+    :class: note
+
+    .. code-block:: shell
+
+        sudo apt install hypershell
+
+|
+
+Ubuntu (coming soon)
+^^^^^^^^^^^^^^^^^^^^
+
+Installing as a `snap` allows for a self-contained package and even control over the
+level of `confinement`, unlike other container formats. This is particularly nice for
+Ubuntu-like distributions on small devices (such as Raspberry Pi).
+
+.. admonition:: Install as a Snap package
+    :class: note
+
+    .. code-block:: shell
+
+        sudo snap install hypershell
+
+|
+
+Fedora / Alma / Rocky / RHEL
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+We are now shipping in `Fedora <https://packages.fedoraproject.org/pkgs/hypershell/hypershell/>`_
+(Fedora 42, Fedora Rawhide, EPEL 10.0, EPEL 10.1).
+
+Note `issue 35 <https://github.com/hypershell/hypershell/issues/35>`_ where ``/usr/bin/hs`` is in
+conflict with another `package <https://crates.io/crates/heatseeker>`_. For the time being,
+the ``hs`` command is renamed to ``hsh`` (though this is not ideal and may change later).
+
+.. admonition:: Install from EPEL
+    :class: note
+
+    .. code-block:: shell
+
+        sudo dnf install hypershell
+
+.. admonition:: Install from EPEL
+    :class: note
+
+    .. code-block:: shell
+
+        sudo yum install hypershell
+
+
+-------------------
+
+Docker and Apptainer
+--------------------
+
+|
+
+The project includes both a ``Dockerfile`` and ``Apptainer`` build definition.
+Using the software within a container is of limited utility however as the entire point
+of HyperShell is to run other programs (and in a distributed fashion).
+Deploying the `server` as a Docker container (e.g., within a `Kubernetes` environment)
+is indeed useful though as it allows you to run it in a persistent fashion alongside of an HPC
+environment.
+
+In a purely containerized environment HyperShell can be included in your own container image.
+HyperShell has both improved ergonomics and performance over scheduling "jobs" directly
+within a Kubernetes-like environment (e.g., ``kubectl``),
+with much better throughput and responsiveness.
+
+The fact that your configuration can be entirely defined in terms of environment variables
+makes it easy to setup your deployment without needing to embed the configuration.
+
+
+-------------------
+
+HPC Module (LMOD)
+-----------------
+
+|
+
+System administrators may want to install and expose `HyperShell` in a custom location.
+On something like an HPC cluster this could be an entirely different file system.
+Let us assume this is the case, and that we already have our own Python installation
+managed by some `module` system.
+
+Here we will create an isolated prefix for the installation with version number included
+and only expose the entry-point scripts to users, along with shell completions and the
+manual page. Some desired runtime, ``python3.13``, is already loaded.
+
+If there is not already a preferred Python module it might be easier to use
+`conda-forge <https://conda-forge.org>`_ (or `mamba <https://mamba.readthedocs.io>`_)
+or ``uv`` directly to create a virtual environment.
+
+.. admonition:: Create installation manually on a shared system
+    :class: note
+
+    .. code-block:: shell
+
+        mkdir -p /apps/x86_64-any/hypershell/$VERSION
+        cd /apps/x86_64-any/hypershell/$VERSION
+
+        git clone --depth=1 --branch=$VERSION https://github.com/hypershell/hypershell src
+
+        python3.13 -m venv libexec
+        libexec/bin/pip install ./src
+        libexec/bin/pip install psycopg2
+
+        mkdir -p bin
+        ln -sf ../libexec/bin/hs bin/hs
+        ln -sf ../libexec/bin/hsx bin/hsx
+        ln -sf src/share
+
+|
+
+Based on this installation, a simple `LMOD <https://lmod.readthedocs.io/en/latest/>`_
+configuration file might then be:
+
+.. admonition:: Module file definition (e.g., /etc/module/x86_64-any/hypershell/<VERSION>.lua)
+    :class: note
+
+    .. code-block:: lua
+
+        local appname = "hypershell"
+        local version = "<version>" -- replace with actual version
+        local appsdir = "/apps/x86_64-any"
+        local modroot = pathJoin(appsdir, appname, version)
+
+        whatis("Name: HyperShell")
+        whatis("Version: " .. version)
+        whatis("Description: A cross-platform, high-throughput computing utility for processing
+        shell commands over a distributed, asynchronous queue.")
+
+        prepend_path("PATH", pathJoin(modroot, "bin"))
+        prepend_path("MANPATH", pathJoin(modroot, "share", "man"))
+
+        -- Raw source b/c `complete -F _hs hs` does not persist with source_sh
+        execute { cmd="source " .. pathJoin(modroot, "share", "bash_completion.d", "hs"), modeA={"load"} }
+
+Presumably, users would then be able to activate the software by loading the module as such.
+
+.. admonition:: Load module
+    :class: note
+
+    .. code-block:: shell
+
+        module load hypershell
+
+------
+
+Runtime Package Resolution
+--------------------------
+
+|
+
+.. include:: _include/config_pythonpath.rst
+
+For example, from the above installation we might add the following to our module:
+
+.. admonition:: Extra setting for LMOD
+    :class: note
+
+    .. code-block:: lua
+
+        ...
+        prepend_path("HYPERSHELL_PYTHONPATH", pathJoin(modroot, "frozen-python.path"))
+        ...
+
+And we can include the following paths in our frozen set.
+
+.. admonition:: Contents of ``frozen-python.path``
+    :class: note
+
+    .. code-block:: shell
+
+        /apps/x86_64-any/hypershell/<version>/libexec/lib/python3.13
+        /apps/x86_64-any/hypershell/<version>/libexec/lib/python3.13/lib-dynload
+        /apps/x86_64-any/hypershell/<version>/libexec/lib/python3.13/site-packages
+
+
+------
+
+Shell Completions
+-----------------
+
+|
+
+On `Linux` and `macOS` platforms we provide shell completion definitions for Bash-like
+environments (specialized ZShell completions coming-soon). As suggested by the LMOD
+definition file included above, sourcing the ``/share/bash_completion.d/hs`` file enables
+completions for the entire command-line interface.
+
+Some completions are simple, like what options are available for the given subcommand.
+Some completions are basic, such as ``--bind <tab>`` returning either ``localhost`` or ``0.0.0.0``.
+Some are more sophisticated.
+
+Some examples (but not everything):
+
+* ``hs config get <tab>`` will autocomplete all options.
+* ``hs config set OPT <tab>`` will autocomplete the current value for OPT.
+* ``hs client ... --host <tab>`` will parse your host file and return possible known hosts.
+* ``hs server ... --auth <tab>`` will auto-generate secure keys at random.
+* ``hs server ... --port <tab>`` will select an available port on your machine.
+* ``hs list <tab>`` will complete known fields.
+* ``hs list ... -t <tab>`` will complete known tags in the database.
+* ``hs list ... -t key:<tab>`` will complete known values for that key in the database.
+* ``hsx ... --ssh-group <tab>`` will autocomplete known groups in your config.
+
+
+-------------------
+
+Development
+-----------
+
+|
+
+As a library dependency, `HyperShell` can easily be added to your project using whatever package
+tooling you like. For development of `HyperShell` itself, contributors should create their own fork
+of the repository on `GitHub <https://github.com/hypershell/hypershell>`_ and clone the fork locally.
+We use `uv <https://docs.astral.sh/uv/>`_ for managing the development environment. The
+``uv.lock`` file is included in the repository, simply run the following command to initialize
+your virtual environment.
+
+.. admonition:: Install development dependencies inside local forked repository
+    :class: note
+
+    .. code-block:: shell
+
+        uv sync --all-packages --python 3.13
+
+
+Unit and integration tests can be run using `pytest <https://pytest.org>`_.
+Tests should pass for Python 3.9 and beyond.
+These are largely lightweight tests in isolated ``HYPERSHELL_SITE`` directories
+but can be slow because of the time to launch processes.
+Use ``-n`` to parallelize tests.
+
+.. admonition:: Run tests
+    :class: note
+
+    .. code-block:: shell
+
+        uv run --python 3.13 pytest -v -n 8
+
+|

{hypershell-2.7.0 → hypershell-2.7.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hypershell"
-version = "2.7.0"
+version = "2.7.2"
 description = "A cross-platform, high-throughput computing utility for processing shell commands over a distributed, asynchronous queue."
 readme = "README.rst"
 license = "Apache-2.0"
@@ -25,6 +25,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Operating System :: POSIX :: Linux",
     "Operating System :: MacOS",
     "Operating System :: Microsoft :: Windows",
@@ -54,7 +55,8 @@ dev = [
     "uuid-utils>=0.10.0",
     "pytest>=8.1.1",
     "hypothesis>=6.100.0",
-    "sphinx-autobuild>=2024.2.4"
+    "sphinx-autobuild>=2024.2.4",
+    "pytest-xdist>=3.7.0",
 ]
 docs = [
     "sphinx>=6.0,<8.0",
@@ -81,3 +83,11 @@ hsx = "hypershell:main_x"
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
+
+[tool.pytest.ini_options]
+addopts = ["--strict-markers", ]
+markers = [
+    'unit', # Unit tests are short, interface driven tests on discrete components.",
+    'integration', # Integration tests are often longer and deal with the interaction between systems.",
+    'parameterize', # Placeholder for parameterized tests (not a real type).",
+]

{hypershell-2.7.0 → hypershell-2.7.2}/share/bash_completion.d/hs

@@ -52,7 +52,7 @@ function _hs_initdb ()
 
 function _hs_config ()
 {
-	local all_opts="get set edit which -h --help"
+	local all_opts="get set edit which -h --help --system --user --local"
 
 	local i=1 opt= subcmd_i=
 	while [[ ${i} -lt ${COMP_CWORD} ]]; do