env-module-manager 0.7.0__tar.gz → 0.9.0__tar.gz

{env_module_manager-0.7.0 → env_module_manager-0.9.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: env-module-manager
-Version: 0.7.0
+Version: 0.9.0
 Summary: Deploy Python, Rust, shell, and collective CLI environments behind GNU environment modulefiles
 Project-URL: Homepage, https://github.com/ejb90/module-manager
 Project-URL: Documentation, https://module-manager.readthedocs.io/
@@ -73,12 +73,17 @@ Deploy a Python CLI with `uv tool install`:
 ```sh
 module-manager deploy-python ruff 0.8.0 \
   --package 'ruff==0.8.0' \
+  --default-index https://packages.example/simple \
   --constraints /prod/constraints/runtime.txt \
+  --uv-executable /opt/uv/bin/uv \
   --prefix /prod/tools \
   --module-root /prod/modulefiles \
   --execute-install
 ```
 
+Set `MODULE_MANAGER_UV_EXECUTABLE=/opt/uv/bin/uv` to use the same uv path by
+default.
+
 Deploy a Rust binary:
 
 ```sh
@@ -94,6 +99,16 @@ Generate a constraints file for a Python CLI:
 module-manager auto-constraints ruff==0.8.0 --output constraints.txt
 ```
 
+Deploy from a direct wheel or Git URL:
+
+```sh
+module-manager deploy-python my-tool 1.0.0 \
+  --package 'my-tool @ file:///prod/wheels/my_tool-1.0.0-py3-none-any.whl' \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles \
+  --execute-install
+```
+
 Deploy a shell script:
 
 ```sh

{env_module_manager-0.7.0 → env_module_manager-0.9.0}/README.md

@@ -41,12 +41,17 @@ Deploy a Python CLI with `uv tool install`:
 ```sh
 module-manager deploy-python ruff 0.8.0 \
   --package 'ruff==0.8.0' \
+  --default-index https://packages.example/simple \
   --constraints /prod/constraints/runtime.txt \
+  --uv-executable /opt/uv/bin/uv \
   --prefix /prod/tools \
   --module-root /prod/modulefiles \
   --execute-install
 ```
 
+Set `MODULE_MANAGER_UV_EXECUTABLE=/opt/uv/bin/uv` to use the same uv path by
+default.
+
 Deploy a Rust binary:
 
 ```sh
@@ -62,6 +67,16 @@ Generate a constraints file for a Python CLI:
 module-manager auto-constraints ruff==0.8.0 --output constraints.txt
 ```
 
+Deploy from a direct wheel or Git URL:
+
+```sh
+module-manager deploy-python my-tool 1.0.0 \
+  --package 'my-tool @ file:///prod/wheels/my_tool-1.0.0-py3-none-any.whl' \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles \
+  --execute-install
+```
+
 Deploy a shell script:
 
 ```sh

env_module_manager-0.9.0/docs/collective-environments.md

@@ -0,0 +1,198 @@
+# Collective Environments
+
+Collective environments package several tools behind one modulefile. Use them
+when a shared workflow needs Python CLIs, Rust binaries, and shell scripts to
+appear together from one `module load`.
+
+Create a TOML manifest:
+
+```toml
+name = "dev-tools"
+version = "2026.05"
+description = "Shared developer command-line tools"
+prefix = "/prod/tools"
+module_root = "/prod/modulefiles"
+default = true
+
+[[tools]]
+type = "python"
+name = "ruff"
+version = "0.8.0"
+package = "ruff==0.8.0"
+python = "3.12"
+indexes = ["https://packages.example/simple"]
+default_index = "https://packages.example/simple"
+find_links = ["/prod/wheels"]
+no_index = false
+index_strategy = "first-index"
+constraints = ["/prod/constraints/runtime.txt"]
+no_cache = false
+refresh = false
+refresh_packages = ["ruff"]
+force = false
+reinstall = false
+uv_config_file = "/prod/config/uv.toml"
+uv_executable = "/opt/uv/bin/uv"
+
+[[tools]]
+type = "rust"
+name = "ripgrep"
+version = "14.1.1"
+binary = "./target/release/rg"
+
+[[tools]]
+type = "script"
+name = "lab-helper"
+version = "1.0.0"
+script = "./scripts/lab-helper"
+```
+
+Deploy the environment:
+
+```sh
+module-manager deploy-env --file dev-tools.toml
+```
+
+Use `--uv-executable` when all Python tools in the manifest should use a
+specific uv executable:
+
+```sh
+module-manager deploy-env --file dev-tools.toml --uv-executable /opt/uv/bin/uv
+```
+
+You can also set the same default with `MODULE_MANAGER_UV_EXECUTABLE`, or set
+`uv_executable` on an individual Python tool in the manifest when only that
+entry needs a different executable.
+
+This writes one shared environment:
+
+```text
+/prod/tools/dev-tools/2026.05/bin
+/prod/modulefiles/dev-tools/2026.05
+```
+
+The generated modulefile prepends the shared `bin` directory to `PATH`, so all
+tools in the manifest are available after:
+
+```sh
+module use /prod/modulefiles
+module load dev-tools
+```
+
+Relative `binary` and `script` paths are resolved relative to the manifest file.
+Relative Python `constraints` paths are resolved the same way.
+
+## Multiple Python Tools
+
+A collective environment can install several Python CLIs into the same shared
+`bin` directory. Each Python tool can use its own package spec and uv resolver
+options:
+
+```toml
+name = "python-dev-tools"
+version = "2026.05"
+prefix = "/prod/tools"
+module_root = "/prod/modulefiles"
+
+[[tools]]
+type = "python"
+name = "ruff"
+version = "0.8.0"
+package = "ruff==0.8.0"
+python = "3.12"
+constraints = ["constraints.txt"]
+
+[[tools]]
+type = "python"
+name = "gitconductor"
+version = "0.7.0"
+package = "gitconductor==0.7.0"
+default_index = "https://packages.example/simple"
+constraints = ["constraints.txt"]
+refresh_packages = ["gitconductor"]
+
+[[tools]]
+type = "python"
+name = "internal-review"
+version = "1.4.2"
+package = "internal-review @ file:///prod/wheels/internal_review-1.4.2-py3-none-any.whl"
+find_links = ["/prod/wheels"]
+no_index = true
+```
+
+Deploy it with:
+
+```sh
+module-manager deploy-env --file python-dev-tools.toml
+```
+
+After `module load python-dev-tools`, the `ruff`, `gitconductor`, and
+`internal-review` executables are available from one module.
+
+## Python Tools and Bash Scripts
+
+Use script entries for Bash helpers that should live alongside Python CLIs:
+
+```toml
+name = "release-tools"
+version = "2026.05"
+description = "Release automation helpers"
+prefix = "/prod/tools"
+module_root = "/prod/modulefiles"
+
+[[tools]]
+type = "python"
+name = "gitconductor"
+version = "0.7.0"
+package = "gitconductor==0.7.0"
+constraints = ["constraints.txt"]
+
+[[tools]]
+type = "python"
+name = "changelog-builder"
+version = "2.1.0"
+package = "changelog-builder @ git+https://github.com/org/changelog-builder.git@v2.1.0"
+
+[[tools]]
+type = "script"
+name = "release-check"
+version = "1.0.0"
+script = "./scripts/release-check.sh"
+
+[[tools]]
+type = "script"
+name = "publish-docs"
+version = "1.0.0"
+script = "./scripts/publish-docs.sh"
+```
+
+Deploy it with:
+
+```sh
+module-manager deploy-env --file release-tools.toml
+```
+
+The script files are copied into the shared environment `bin` directory and
+marked executable, so they appear on `PATH` next to the Python entry points.
+
+## Preview
+
+Use `--dry-run` to preview the install, copy, and modulefile actions without
+creating files:
+
+```sh
+module-manager deploy-env --file dev-tools.toml --dry-run
+```
+
+## Overrides
+
+The manifest can define `prefix`, `module_root`, and `default`, but CLI options
+can override them:
+
+```sh
+module-manager deploy-env \
+  --file dev-tools.toml \
+  --prefix /scratch/tools \
+  --module-root /scratch/modulefiles \
+  --no-default
+```

{env_module_manager-0.7.0 → env_module_manager-0.9.0}/docs/configuration.md

@@ -18,6 +18,7 @@ module_root = "/prod/modulefiles"
 indexes = ["https://packages.example/simple"]
 find_links = ["/prod/wheels"]
 uv_config_file = "/prod/config/uv.toml"
+uv_executable = "/opt/uv/bin/uv"
 ```
 
 `prefix` and `module_root` must resolve to different directories. Using the
@@ -37,10 +38,15 @@ export MODULE_MANAGER_PREFIX=/prod/tools
 export MODULE_MANAGER_MODULE_ROOT=/prod/modulefiles
 export MODULE_MANAGER_INDEXES=https://packages.example/simple,https://mirror.example/simple
 export MODULE_MANAGER_FIND_LINKS=/prod/wheels,/prod/more-wheels
+export MODULE_MANAGER_UV_EXECUTABLE=/opt/uv/bin/uv
 ```
 
 `MODULE_MANAGER_CONFIG` can point to an alternate TOML config file.
 
+`MODULE_MANAGER_UV_EXECUTABLE` sets the `uv` executable used by
+`deploy-python`, `deploy-env`, and `auto-constraints`. CLI `--uv-executable`
+options override it when provided.
+
 There is no `MODULE_MANAGER_*` environment variable for uv configuration files.
 Use uv's own `UV_CONFIG_FILE` environment variable when you want to set that via
 the environment.

{env_module_manager-0.7.0 → env_module_manager-0.9.0}/docs/python-tools.md

@@ -11,6 +11,24 @@ Other uv settings, including `UV_CONFIG_FILE`, are preserved.
 Python package dependency because `module-manager` shells out to the `uv`
 executable and is intended to be installable by `uv` itself.
 
+If `uv` is not on `PATH`, or you want a pinned executable, pass
+`--uv-executable`:
+
+```sh
+module-manager deploy-python ruff 0.8.0 \
+  --package 'ruff==0.8.0' \
+  --uv-executable /opt/uv/bin/uv \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles \
+  --execute-install
+```
+
+The same default can be set for Python workflows with an environment variable:
+
+```sh
+export MODULE_MANAGER_UV_EXECUTABLE=/opt/uv/bin/uv
+```
+
 ## Deploy from PyPI
 
 ```sh
@@ -34,20 +52,37 @@ unchanged.
 ```sh
 module-manager deploy-python gitconductor 0.1.0 \
   --package gitconductor==0.1.0 \
+  --default-index https://packages.example/simple \
   --index https://packages.example/simple \
   --prefix /prod/tools \
   --module-root /prod/modulefiles \
   --execute-install
 ```
 
-`--index` may be used more than once.
+`--index` may be used more than once. Use `--default-index` to replace uv's
+default package index, or `--no-index` when resolution should use only direct
+URLs and `--find-links` locations.
 
 ## Deploy from a Wheelhouse
 
+Use `--find-links` when wheels are staged in a directory or simple HTML page:
+
+```sh
+module-manager deploy-python gitconductor 0.1.0 \
+  --package gitconductor==0.1.0 \
+  --find-links /prod/wheels \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles \
+  --execute-install
+```
+
+Add `--no-index` to make the install fully wheelhouse-only:
+
 ```sh
 module-manager deploy-python gitconductor 0.1.0 \
   --package gitconductor==0.1.0 \
   --find-links /prod/wheels \
+  --no-index \
   --prefix /prod/tools \
   --module-root /prod/modulefiles \
   --execute-install
@@ -55,6 +90,28 @@ module-manager deploy-python gitconductor 0.1.0 \
 
 `--find-links` may be used more than once.
 
+## Deploy from a Wheel URL
+
+Pass a direct wheel URL or file URL as the package spec:
+
+```sh
+module-manager deploy-python gitconductor 0.1.0 \
+  --package 'gitconductor @ https://packages.example/files/gitconductor-0.1.0-py3-none-any.whl' \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles \
+  --execute-install
+```
+
+For a local wheel file:
+
+```sh
+module-manager deploy-python gitconductor 0.1.0 \
+  --package 'gitconductor @ file:///prod/wheels/gitconductor-0.1.0-py3-none-any.whl' \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles \
+  --execute-install
+```
+
 ## Use Constraint Files
 
 Pass requirement constraint files to `uv tool install`:
@@ -70,6 +127,24 @@ module-manager deploy-python gitconductor 0.1.0 \
 
 `--constraints` may be used more than once.
 
+## Cache and Refresh Controls
+
+Pass uv cache controls through when you need fresh index or package metadata:
+
+```sh
+module-manager deploy-python gitconductor 0.1.0 \
+  --package gitconductor==0.1.0 \
+  --refresh \
+  --refresh-package gitconductor \
+  --no-cache \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles \
+  --execute-install
+```
+
+Use `--force` or `--reinstall` when re-running an install into an existing
+versioned tool environment.
+
 ## Generate Constraint Files
 
 Use `auto-constraints` to compile a package and its dependencies into a
@@ -78,6 +153,7 @@ constraints file:
 ```sh
 module-manager auto-constraints gitconductor==0.7.0 \
   --index https://packages.example/simple \
+  --uv-executable /opt/uv/bin/uv \
   --output constraints.txt
 ```
 
@@ -111,8 +187,8 @@ through the environment.
 
 ## Deploy from VCS
 
-`--package` is passed directly to `uv tool install`, so VCS package specs are
-supported.
+`--package` is passed directly to `uv tool install`, so Git package specs are
+supported. Pin a tag, branch, or commit to keep deployments reproducible.
 
 ```sh
 module-manager deploy-python mytool 1.0.0 \
@@ -122,6 +198,16 @@ module-manager deploy-python mytool 1.0.0 \
   --execute-install
 ```
 
+For an SSH Git URL:
+
+```sh
+module-manager deploy-python mytool 1.0.0 \
+  --package 'git+ssh://git@github.com/org/repo.git@v1.0.0' \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles \
+  --execute-install
+```
+
 For a package in a repository subdirectory:
 
 ```sh

{env_module_manager-0.7.0 → env_module_manager-0.9.0}/docs/reference.md

@@ -49,9 +49,19 @@ module-manager deploy-python NAME VERSION \
   --package PACKAGE \
   [--python PYTHON] \
   [--index URL] \
+  [--default-index URL] \
   [--find-links PATH_OR_URL] \
+  [--no-index] \
+  [--index-strategy STRATEGY] \
+  [--keyring-provider PROVIDER] \
   [--constraints PATH] \
+  [--no-cache] \
+  [--refresh] \
+  [--refresh-package PACKAGE] \
+  [--force] \
+  [--reinstall] \
   [--uv-config-file PATH] \
+  [--uv-executable PATH] \
   [--prefix PATH] \
   [--module-root PATH] \
   [--no-default] \
@@ -66,7 +76,8 @@ module-manager auto-constraints PACKAGE \
   [--python PYTHON] \
   [--index URL] \
   [--find-links PATH_OR_URL] \
-  [--uv-config-file PATH]
+  [--uv-config-file PATH] \
+  [--uv-executable PATH]
 ```
 
 ## Rust Command
@@ -77,6 +88,7 @@ module-manager deploy-rust NAME VERSION \
   [--prefix PATH] \
   [--module-root PATH] \
   [--no-default] \
+  [--uv-executable PATH] \
   [--dry-run]
 ```
 

{env_module_manager-0.7.0 → env_module_manager-0.9.0}/module_manager/__init__.py

@@ -1,3 +1,3 @@
 """Deployment helpers for HPC environment module files."""
 
-__version__ = "0.7.0"
+__version__ = "0.9.0"

{env_module_manager-0.7.0 → env_module_manager-0.9.0}/module_manager/cli.py

@@ -203,23 +203,50 @@ def main(ctx: click.Context, config: Path | None) -> None:
     multiple=True,
     help="Additional package index URL passed to uv. May be used more than once.",
 )
+@click.option("--default-index", help="Default package index URL passed to uv.")
 @click.option(
     "--find-links",
     "find_links",
     multiple=True,
     help="Directory or HTML page of packages passed to uv. May be used more than once.",
 )
+@click.option("--no-index", is_flag=True, help="Ignore registry indexes and use direct URLs or find-links.")
+@click.option(
+    "--index-strategy",
+    type=click.Choice(["first-index", "unsafe-first-match", "unsafe-best-match"]),
+    help="Package index strategy passed to uv.",
+)
+@click.option(
+    "--keyring-provider",
+    type=click.Choice(["disabled", "subprocess"]),
+    help="Keyring provider passed to uv.",
+)
 @click.option(
     "--constraints",
     "constraints",
     multiple=True,
     help="Requirements constraint file passed to uv. May be used more than once.",
 )
+@click.option("--no-cache", is_flag=True, help="Avoid reading from or writing to the uv cache.")
+@click.option("--refresh", is_flag=True, help="Refresh all uv cached data.")
+@click.option(
+    "--refresh-package",
+    "refresh_packages",
+    multiple=True,
+    help="Refresh cached data for a package. May be used more than once.",
+)
+@click.option("--force", is_flag=True, help="Replace existing executable entries.")
+@click.option("--reinstall", is_flag=True, help="Reinstall all packages in the tool environment.")
 @click.option(
     "--uv-config-file",
     type=PATH,
     help="uv.toml file passed to uv tool install with --config-file.",
 )
+@click.option(
+    "--uv-executable",
+    type=PATH,
+    help="uv executable path. Defaults to uv on PATH.",
+)
 @click.option(
     "--execute-install",
     is_flag=True,
@@ -238,9 +265,19 @@ def deploy_python(
     package: str,
     python: str | None,
     indexes: tuple[str, ...],
+    default_index: str | None,
     find_links: tuple[str, ...],
+    no_index: bool,
+    index_strategy: str | None,
+    keyring_provider: str | None,
     constraints: tuple[str, ...],
+    no_cache: bool,
+    refresh: bool,
+    refresh_packages: tuple[str, ...],
+    force: bool,
+    reinstall: bool,
     uv_config_file: Path | None,
+    uv_executable: Path | None,
     execute_install: bool,
 ) -> None:
     """Write a modulefile for a [cyan]uv tool install[/cyan] Python CLI.
@@ -257,9 +294,19 @@ def deploy_python(
         package: Package spec passed to `uv tool install`.
         python: Optional Python interpreter or version passed to uv.
         indexes: Additional package index URLs passed to uv.
+        default_index: Default package index URL passed to uv.
         find_links: Wheelhouse directories or HTML package pages passed to uv.
+        no_index: Whether uv should ignore registry indexes.
+        index_strategy: Package index strategy passed to uv.
+        keyring_provider: Keyring provider passed to uv.
         constraints: Requirements constraint files passed to uv.
+        no_cache: Whether uv should avoid reading from or writing to cache.
+        refresh: Whether uv should refresh cached data.
+        refresh_packages: Packages whose cached data uv should refresh.
+        force: Whether uv should replace existing executable entries.
+        reinstall: Whether uv should reinstall all packages.
         uv_config_file: Optional uv configuration file passed to `uv tool`.
+        uv_executable: Optional uv executable path.
         execute_install: Whether to run `uv tool install` immediately.
 
     Raises:
@@ -282,9 +329,19 @@ def deploy_python(
         homepage=homepage,
         python=python,
         indexes=indexes or config.indexes,
+        default_index=default_index,
         find_links=find_links or config.find_links,
+        no_index=no_index,
+        index_strategy=index_strategy,
+        keyring_provider=keyring_provider,
         constraints=constraints,
+        no_cache=no_cache,
+        refresh=refresh,
+        refresh_packages=refresh_packages,
+        force=force,
+        reinstall=reinstall,
         uv_config_file=(uv_config_file.expanduser() if uv_config_file else config.uv_config_file),
+        uv_executable=(uv_executable.expanduser() if uv_executable else config.uv_executable),
         execute_install=execute_install,
         make_default=make_default,
     )
@@ -325,6 +382,11 @@ def deploy_python(
     type=PATH,
     help="uv.toml file passed to uv with --config-file.",
 )
+@click.option(
+    "--uv-executable",
+    type=PATH,
+    help="uv executable path. Defaults to uv on PATH.",
+)
 @click.pass_obj
 def auto_constraints(
     config: AppConfig,
@@ -334,6 +396,7 @@ def auto_constraints(
     indexes: tuple[str, ...],
     find_links: tuple[str, ...],
     uv_config_file: Path | None,
+    uv_executable: Path | None,
 ) -> None:
     """Generate a constraints file for a Python package.
 
@@ -345,6 +408,7 @@ def auto_constraints(
         indexes: Additional package index URLs passed to uv.
         find_links: Wheelhouse directories or HTML package pages passed to uv.
         uv_config_file: Optional uv configuration file passed to uv.
+        uv_executable: Optional uv executable path.
 
     Raises:
         click.ClickException: If uv cannot generate constraints.
@@ -358,6 +422,7 @@ def auto_constraints(
             indexes=indexes or config.indexes,
             find_links=find_links or config.find_links,
             uv_config_file=(uv_config_file.expanduser() if uv_config_file else config.uv_config_file),
+            uv_executable=(uv_executable.expanduser() if uv_executable else config.uv_executable),
         )
     except ConstraintGenerationError as error:
         raise click.ClickException(str(error)) from error
@@ -543,6 +608,11 @@ def deploy_script(
     is_flag=True,
     help="Print actions that would run without creating files.",
 )
+@click.option(
+    "--uv-executable",
+    type=PATH,
+    help="uv executable path for Python tools. Defaults to uv on PATH.",
+)
 @click.pass_obj
 def deploy_env(
     config: AppConfig,
@@ -551,6 +621,7 @@ def deploy_env(
     prefix: Path | None,
     make_default: bool | None,
     dry_run: bool,
+    uv_executable: Path | None,
 ) -> None:
     """Deploy a collective environment from a TOML manifest.
 
@@ -562,6 +633,7 @@ def deploy_env(
         prefix: Optional install prefix overriding manifest and configuration.
         make_default: Optional override for manifest default behavior.
         dry_run: Whether to report actions without mutating the filesystem.
+        uv_executable: Optional uv executable path for Python tools.
 
     Raises:
         click.ClickException: If the manifest cannot be parsed.
@@ -588,7 +660,13 @@ def deploy_env(
             make_default=make_default,
         )
 
-    result = deploy_environment(spec=spec, module_root=resolved_module_root, prefix=resolved_prefix, dry_run=dry_run)
+    result = deploy_environment(
+        spec=spec,
+        module_root=resolved_module_root,
+        prefix=resolved_prefix,
+        uv_executable=(uv_executable.expanduser() if uv_executable else config.uv_executable),
+        dry_run=dry_run,
+    )
     print_environment_result(result, dry_run)