hypershell 2.7.1__tar.gz → 2.7.2__tar.gz

{hypershell-2.7.1 → 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.1 → 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.1 → hypershell-2.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hypershell
-Version: 2.7.1
+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
@@ -42,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
@@ -58,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.1 → 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.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.1 → 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.1 → 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

{hypershell-2.7.1 → 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.1 → hypershell-2.7.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "hypershell"
-version = "2.7.1"
+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"

{hypershell-2.7.1 → 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

{hypershell-2.7.1 → hypershell-2.7.2}/share/man/man1/hs.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "HS" "1" "Jun 07, 2025" "2.7.1" "hypershell"
+.TH "HS" "1" "Jun 07, 2025" "2.7.2" "hypershell"
 .SH NAME
 hs \- Process shell commands over a distributed, asynchronous queue
 .SH SYNOPSIS

{hypershell-2.7.1 → hypershell-2.7.2}/share/man/man1/hsx.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "HS" "1" "Jun 07, 2025" "2.7.1" "hypershell"
+.TH "HS" "1" "Jun 07, 2025" "2.7.2" "hypershell"
 .SH NAME
 hs \- Process shell commands over a distributed, asynchronous queue
 .SH SYNOPSIS

{hypershell-2.7.1 → hypershell-2.7.2}/share/man/man1/hyper-shell.1

@@ -27,7 +27,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
 ..
-.TH "HYPER-SHELL" "1" "Jun 07, 2025" "2.7.1" "hypershell"
+.TH "HYPER-SHELL" "1" "Jun 07, 2025" "2.7.2" "hypershell"
 .SH NAME
 hyper-shell \- Process shell commands over a distributed, asynchronous queue
 .SH SYNOPSIS

{hypershell-2.7.1 → hypershell-2.7.2}/src/hypershell/config.py

@@ -386,23 +386,19 @@ class ConfigWhichApp(Application):
 
 
 if os.name == 'nt':
-    CONFIG_PATH_INFO: Final[str] = f"""\
-  --system         %ProgramData%\\HyperShell\\Config.toml
-  --user           %AppData%\\HyperShell\\Config.toml
-  --local          {path.local.config}\
-"""
+    CONFIG_PATH_SYSTEM: Final[str] = '%ProgramData%\\HyperShell\\Config.toml'
+    CONFIG_PATH_USER: Final[str] = '%AppData%\\HyperShell\\Config.toml'
+    CONFIG_PATH_LOCAL: Final[str] = path.local.config
 else:
-    CONFIG_PATH_INFO: Final[str] = f"""\
-  --system         /etc/hypershell.toml
-  --user           ~/.hypershell/config.toml
-  --local          {path.local.config}\
-"""
+    CONFIG_PATH_SYSTEM: Final[str] = '/etc/hypershell.toml'
+    CONFIG_PATH_USER: Final[str] = '~/.hypershell/config.toml'
+    CONFIG_PATH_LOCAL: Final[str] = path.local.config
 
 
 PROGRAM = 'hs config'
 USAGE = f"""\
 Usage:
-  {PROGRAM} [-h]
+  {PROGRAM} [-h] [--system | --user | --local]
   {GET_SYNOPSIS}
   {SET_SYNOPSIS}
   {EDIT_SYNOPSIS}
@@ -421,10 +417,10 @@ Commands:
   which            {ConfigWhichApp.__doc__}
 
 Options:
-  -h, --help       Show this message and exit.
-
-Files:
-{CONFIG_PATH_INFO}\
+      --system     Show system-level config path.
+      --user       Show user-level config path.
+      --local      Show local-level config path.
+  -h, --help       Show this message and exit.\
 """
 
 
@@ -433,8 +429,13 @@ class ConfigApp(ApplicationGroup):
 
     interface = Interface(PROGRAM, USAGE, HELP)
     interface.add_argument('command')
-
-    commands = {'get': ConfigGetApp,
-                'set': ConfigSetApp,
-                'edit': ConfigEditApp,
-                'which': ConfigWhichApp, }
+    interface.add_argument('--system', action='version', version=CONFIG_PATH_SYSTEM)
+    interface.add_argument('--user', action='version', version=CONFIG_PATH_USER)
+    interface.add_argument('--local', action='version', version=CONFIG_PATH_LOCAL)
+
+    commands = {
+        'get': ConfigGetApp,
+        'set': ConfigSetApp,
+        'edit': ConfigEditApp,
+        'which': ConfigWhichApp,
+    }

{hypershell-2.7.1 → hypershell-2.7.2}/uv.lock

@@ -602,7 +602,7 @@ wheels = [
 
 [[package]]
 name = "hypershell"
-version = "2.7.1"
+version = "2.7.2"
 source = { editable = "." }
 dependencies = [
     { name = "cmdkit", extra = ["toml"] },