env-module-manager 0.1.2__py3-none-any.whl

env_module_manager-0.1.2.dist-info/METADATA

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: env-module-manager
+Version: 0.1.2
+Summary: Deploy Python and Rust CLI tools behind GNU environment modulefiles
+Project-URL: Homepage, https://github.com/ejb90/module-manager
+Project-URL: Documentation, https://module-manager.readthedocs.io/
+Project-URL: Tests, https://app.codecov.io/gh/ejb90/module-manager
+Project-URL: Repository, https://github.com/ejb90/module-manager
+Author: ejb90
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+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 :: Scientific/Engineering
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: rich-click>=1.8
+Provides-Extra: docs
+Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
+Description-Content-Type: text/markdown
+
+# module-manager
+
+![tests](https://github.com/ejb90/module-manager/actions/workflows/test.yml/badge.svg)
+[![Coverage](https://codecov.io/gh/ejb90/module-manager/branch/main/graph/badge.svg)](https://codecov.io/gh/ejb90/module-manager)
+[![License](https://img.shields.io/github/license/ejb90/module-manager)](LICENSE)
+![Ruff](https://img.shields.io/badge/code%20style-ruff-261230)
+[![Documentation](https://readthedocs.org/projects/module-manager/badge/?version=latest)](https://module-manager.readthedocs.io/en/latest/?badge=latest)
+[![PyPI](https://img.shields.io/pypi/v/env-module-manager)](https://pypi.org/project/env-module-manager/)
+[![Python versions](https://img.shields.io/pypi/pyversions/env-module-manager)](https://pypi.org/project/env-module-manager/)
+
+`module-manager` deploys versioned Python and Rust CLI tools behind GNU
+environment modulefiles for Linux/HPC systems.
+
+It writes tools and modulefiles into predictable versioned locations:
+
+```text
+/prod/tools/<name>/<version>/bin
+/prod/modulefiles/<name>/<version>
+```
+
+## Quick Start
+
+Deploy a Python CLI with `uv tool install`:
+
+```sh
+module-manager deploy-python ruff 0.8.0 \
+  --package 'ruff==0.8.0' \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles \
+  --execute-install
+```
+
+Deploy a Rust binary:
+
+```sh
+module-manager deploy-rust ripgrep 14.1.1 \
+  --binary ./target/release/rg \
+  --prefix /prod/tools \
+  --module-root /prod/modulefiles
+```
+
+Use the generated module:
+
+```sh
+module use /prod/modulefiles
+module load ruff/0.8.0
+ruff --version
+```
+
+## Documentation
+
+Full documentation lives in `docs/` and can be served with MkDocs:
+
+```sh
+uv run mkdocs serve
+```
+
+Start with `docs/index.md` for installation, configuration, Python tools, Rust
+tools, and local development notes.

env_module_manager-0.1.2.dist-info/RECORD

@@ -0,0 +1,10 @@
+module_manager/__init__.py,sha256=_SirP-p9OPx91rWxRMLliccvlfwndGIMT9suKHlM978,82
+module_manager/cli.py,sha256=L9Kref6sQHR9zVQv66tfmx1JYug32VaD_ZUtgkMWaTA,5790
+module_manager/config.py,sha256=_FFvW4umsvOc7JuFm2kbI-hr6p0UyZCl5m4TrbB_ACw,3394
+module_manager/deploy.py,sha256=theHJYijlTkPP87nixB6fKV6mHOrrwfYcPXAKZbcZVg,4438
+module_manager/modulefile.py,sha256=-ZujF2kP4dfCaw8fPaCRTMbNgVvbGn2iWfJXrFEFmww,1979
+env_module_manager-0.1.2.dist-info/METADATA,sha256=syRYdIzSWX4EBa75SpcG3D9oq4yEpSoCpVLCz1Qsl8A,3076
+env_module_manager-0.1.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+env_module_manager-0.1.2.dist-info/entry_points.txt,sha256=yTHfIbCQ9cUZqq2oeUQBgrM6GFKGOzgseOz0oe4YIqQ,59
+env_module_manager-0.1.2.dist-info/licenses/LICENSE,sha256=di0toPB3VLzfEyPm6Ru9_nCyPJmZ8z5Lc_GRRj9PfAY,1062
+env_module_manager-0.1.2.dist-info/RECORD,,

env_module_manager-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

env_module_manager-0.1.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+module-manager = module_manager.cli:main

env_module_manager-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ellis
+
+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.

module_manager/__init__.py

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

module_manager/cli.py

@@ -0,0 +1,178 @@
+"""Command-line interface for deploying CLI tools as environment modules."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TypeVar
+
+import rich_click as click
+from click import Command
+
+from . import __version__
+from .config import AppConfig, load_config
+from .deploy import deploy_python_tool, deploy_rust_tool
+
+click.rich_click.TEXT_MARKUP = "rich"
+click.rich_click.STYLE_COMMAND = "bold cyan"
+click.rich_click.STYLE_OPTION = "bold green"
+click.rich_click.STYLE_ARGUMENT = "bold yellow"
+click.rich_click.STYLE_SWITCH = "bold magenta"
+click.rich_click.STYLE_METAVAR = "yellow"
+click.rich_click.HEADER_TEXT = "module-manager"
+click.rich_click.FOOTER_TEXT = (
+    "Examples: [cyan]module-manager deploy-python ruff 0.8.0 --package "
+    "ruff==0.8.0 --prefix /prod/tools --module-root /prod/modulefiles[/cyan]"
+)
+
+PATH = click.Path(path_type=Path)
+ClickCommand = TypeVar("ClickCommand", bound=Command)
+
+
+def common_options(command: ClickCommand) -> ClickCommand:
+    """Attach options shared by Python and Rust deployment commands."""
+    command = click.option(
+        "--homepage",
+        help="Optional upstream homepage shown in module help.",
+    )(command)
+    command = click.option(
+        "--description",
+        help="Text shown by module help and module-whatis.",
+    )(command)
+    command = click.option(
+        "--prefix",
+        type=PATH,
+        help="Root installation prefix, for example /prod/tools.",
+    )(command)
+    command = click.option(
+        "--module-root",
+        type=PATH,
+        help="Root of the module tree, for example /prod/modulefiles.",
+    )(command)
+    command = click.argument("version")(command)
+    command = click.argument("name")(command)
+    return command
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__)
+@click.option(
+    "--config",
+    type=PATH,
+    envvar="MODULE_MANAGER_CONFIG",
+    help="TOML config path. Defaults to ~/.config/module-manager/config.toml.",
+)
+@click.pass_context
+def main(ctx: click.Context, config: Path | None) -> None:
+    """[bold]Deploy CLI tools behind GNU environment modulefiles.[/bold].
+
+    Build versioned modulefiles for Python tools installed with
+    [cyan]uv tool install[/cyan] and Rust binaries copied into a production
+    prefix.
+    """
+    ctx.obj = load_config(config)
+
+
+@main.command("deploy-python")
+@common_options
+@click.option("--package", "package", required=True, help="Package spec passed to uv tool install.")
+@click.option("--python", "python", help="Python interpreter/version passed to uv.")
+@click.option(
+    "--index",
+    "indexes",
+    multiple=True,
+    help="Additional package index URL passed to uv. May be used more than once.",
+)
+@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(
+    "--execute-install",
+    is_flag=True,
+    help="Run uv tool install before writing the modulefile.",
+)
+@click.pass_obj
+def deploy_python(
+    config: AppConfig,
+    name: str,
+    version: str,
+    module_root: Path | None,
+    prefix: Path | None,
+    description: str | None,
+    homepage: str | None,
+    package: str,
+    python: str | None,
+    indexes: tuple[str, ...],
+    find_links: tuple[str, ...],
+    execute_install: bool,
+) -> None:
+    """Write a modulefile for a [cyan]uv tool install[/cyan] Python CLI."""
+    resolved_module_root = require_path(module_root or config.module_root, "module root", "--module-root")
+    resolved_prefix = require_path(prefix or config.prefix, "install prefix", "--prefix")
+    paths = deploy_python_tool(
+        name=name,
+        version=version,
+        package=package,
+        module_root=resolved_module_root,
+        prefix=resolved_prefix,
+        description=description,
+        homepage=homepage,
+        python=python,
+        indexes=indexes or config.indexes,
+        find_links=find_links or config.find_links,
+        execute_install=execute_install,
+    )
+    print_result(paths.modulefile, paths.install_root, paths.bin_dir)
+
+
+@main.command("deploy-rust")
+@common_options
+@click.option(
+    "--binary",
+    type=PATH,
+    help="Compiled binary to copy into the versioned prefix.",
+)
+@click.pass_obj
+def deploy_rust(
+    config: AppConfig,
+    name: str,
+    version: str,
+    module_root: Path | None,
+    prefix: Path | None,
+    description: str | None,
+    homepage: str | None,
+    binary: Path | None,
+) -> None:
+    """Copy a Rust CLI binary and write a modulefile for it."""
+    resolved_module_root = require_path(module_root or config.module_root, "module root", "--module-root")
+    resolved_prefix = require_path(prefix or config.prefix, "install prefix", "--prefix")
+    paths = deploy_rust_tool(
+        name=name,
+        version=version,
+        module_root=resolved_module_root,
+        prefix=resolved_prefix,
+        binary=binary.expanduser() if binary else None,
+        description=description,
+        homepage=homepage,
+    )
+    print_result(paths.modulefile, paths.install_root, paths.bin_dir)
+
+
+def require_path(value: Path | None, label: str, option: str) -> Path:
+    """Return a configured path or raise a Click usage error."""
+    if value is None:
+        msg = (
+            f"Missing {label}. Provide {option}, set the matching MODULE_MANAGER_* "
+            "environment variable, or configure it in TOML."
+        )
+        raise click.UsageError(msg)
+    return value.expanduser()
+
+
+def print_result(modulefile: Path, install_root: Path, bin_dir: Path) -> None:
+    """Print the paths produced by a deployment command."""
+    click.echo(f"modulefile: {modulefile}")
+    click.echo(f"install root: {install_root}")
+    click.echo(f"bin dir: {bin_dir}")

module_manager/config.py

@@ -0,0 +1,105 @@
+"""Configuration loading for module-manager."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+import tomllib
+
+DEFAULT_CONFIG_PATH = Path("~/.config/module-manager/config.toml")
+
+
+@dataclass(frozen=True)
+class AppConfig:
+    """Resolved defaults loaded from files and environment variables."""
+
+    prefix: Path | None = None
+    module_root: Path | None = None
+    indexes: tuple[str, ...] = ()
+    find_links: tuple[str, ...] = ()
+
+
+def default_config_path() -> Path:
+    """Return the default per-user config path."""
+    return DEFAULT_CONFIG_PATH.expanduser()
+
+
+def load_config(path: Path | None = None) -> AppConfig:
+    """Load configuration from TOML and overlay environment variables."""
+    config_path = (path or default_config_path()).expanduser()
+    file_config = load_file_config(config_path)
+    return overlay_env_config(file_config)
+
+
+def load_file_config(path: Path) -> AppConfig:
+    """Load configuration defaults from a TOML file if it exists."""
+    if not path.exists():
+        return AppConfig()
+
+    data = tomllib.loads(path.read_text(encoding="utf-8"))
+    python_data = table(data.get("python"), "python")
+    return AppConfig(
+        prefix=optional_path(data.get("prefix"), "prefix"),
+        module_root=optional_path(data.get("module_root"), "module_root"),
+        indexes=string_tuple(python_data.get("indexes"), "python.indexes"),
+        find_links=string_tuple(python_data.get("find_links"), "python.find_links"),
+    )
+
+
+def overlay_env_config(config: AppConfig) -> AppConfig:
+    """Apply MODULE_MANAGER_* environment variables to file config."""
+    return AppConfig(
+        prefix=env_path("MODULE_MANAGER_PREFIX") or config.prefix,
+        module_root=env_path("MODULE_MANAGER_MODULE_ROOT") or config.module_root,
+        indexes=env_tuple("MODULE_MANAGER_INDEXES") or env_tuple("MODULE_MANAGER_INDEX") or config.indexes,
+        find_links=env_tuple("MODULE_MANAGER_FIND_LINKS") or config.find_links,
+    )
+
+
+def table(value: object, key: str) -> dict[str, Any]:
+    """Return a TOML table or raise a useful type error."""
+    if value is None:
+        return {}
+    if isinstance(value, dict):
+        return value
+    msg = f"{key} must be a TOML table"
+    raise TypeError(msg)
+
+
+def optional_path(value: object, key: str) -> Path | None:
+    """Parse an optional TOML string as a path."""
+    if value is None:
+        return None
+    if isinstance(value, str):
+        return Path(value).expanduser()
+    msg = f"{key} must be a string"
+    raise TypeError(msg)
+
+
+def string_tuple(value: object, key: str) -> tuple[str, ...]:
+    """Parse an optional TOML string list."""
+    if value is None:
+        return ()
+    if isinstance(value, list) and all(isinstance(item, str) for item in value):
+        return tuple(value)
+    msg = f"{key} must be a list of strings"
+    raise TypeError(msg)
+
+
+def env_path(name: str) -> Path | None:
+    """Read a path from an environment variable."""
+    value = os.environ.get(name)
+    if not value:
+        return None
+    return Path(value).expanduser()
+
+
+def env_tuple(name: str) -> tuple[str, ...]:
+    """Read comma-separated string values from an environment variable."""
+    value = os.environ.get(name)
+    if not value:
+        return ()
+    return tuple(item.strip() for item in value.split(",") if item.strip())

module_manager/deploy.py

@@ -0,0 +1,150 @@
+"""Deployment routines for Python and Rust command-line tools."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import shutil
+import stat
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+from .modulefile import ModuleSpec, render_modulefile
+
+
+class MissingExecutableError(RuntimeError):
+    """Raised when a required external executable is unavailable."""
+
+
+@dataclass(frozen=True)
+class DeploymentPaths:
+    """Filesystem paths created or targeted by a deployment."""
+
+    install_root: Path
+    bin_dir: Path
+    modulefile: Path
+
+
+def deployment_paths(module_root: Path, prefix: Path, name: str, version: str) -> DeploymentPaths:
+    """Compute versioned installation and modulefile paths for a tool."""
+    install_root = prefix / name / version
+    return DeploymentPaths(
+        install_root=install_root,
+        bin_dir=install_root / "bin",
+        modulefile=module_root / name / version,
+    )
+
+
+def uv_install_command(
+    package: str,
+    python: str | None = None,
+    indexes: tuple[str, ...] = (),
+    find_links: tuple[str, ...] = (),
+) -> list[str]:
+    """Build the uv command used to install a Python CLI tool."""
+    command = ["uv", "tool", "install"]
+    if python:
+        command.extend(["--python", python])
+    for index in indexes:
+        command.extend(["--index", index])
+    for link in find_links:
+        command.extend(["--find-links", link])
+    command.append(package)
+    return command
+
+
+def write_text(path: Path, content: str) -> None:
+    """Write UTF-8 text to a path, creating parent directories first."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def require_executable(name: str) -> str:
+    """Return an executable path or raise a clear runtime error."""
+    executable = shutil.which(name)
+    if executable is None:
+        msg = f"Required executable not found on PATH: {name}"
+        raise MissingExecutableError(msg)
+    return executable
+
+
+def deploy_python_tool(
+    *,
+    name: str,
+    version: str,
+    package: str,
+    module_root: Path,
+    prefix: Path,
+    description: str | None = None,
+    homepage: str | None = None,
+    python: str | None = None,
+    indexes: tuple[str, ...] = (),
+    find_links: tuple[str, ...] = (),
+    execute_install: bool = False,
+) -> DeploymentPaths:
+    """Deploy metadata for a Python tool and optionally install it with uv."""
+    paths = deployment_paths(module_root, prefix, name, version)
+    paths.bin_dir.mkdir(parents=True, exist_ok=True)
+    tool_dir = paths.install_root / "uv-tools"
+    command = uv_install_command(package, python, indexes, find_links)
+
+    if execute_install:
+        require_executable("uv")
+        env = os.environ.copy()
+        env["UV_TOOL_DIR"] = str(tool_dir)
+        env["UV_TOOL_BIN_DIR"] = str(paths.bin_dir)
+        subprocess.run(command, check=True, env=env)
+
+    install_hint = (
+        f"UV_TOOL_DIR={shlex.quote(str(tool_dir))} "
+        f"UV_TOOL_BIN_DIR={shlex.quote(str(paths.bin_dir))} "
+        f"{shlex.join(command)}"
+    )
+    modulefile = render_modulefile(
+        ModuleSpec(
+            name=name,
+            version=version,
+            root=paths.install_root,
+            bin_dir=paths.bin_dir,
+            description=description,
+            homepage=homepage,
+            install_hint=install_hint,
+        )
+    )
+    write_text(paths.modulefile, modulefile)
+    return paths
+
+
+def deploy_rust_tool(
+    *,
+    name: str,
+    version: str,
+    module_root: Path,
+    prefix: Path,
+    binary: Path | None = None,
+    description: str | None = None,
+    homepage: str | None = None,
+) -> DeploymentPaths:
+    """Deploy metadata for a Rust tool and optionally copy its binary."""
+    paths = deployment_paths(module_root, prefix, name, version)
+    paths.bin_dir.mkdir(parents=True, exist_ok=True)
+
+    if binary:
+        target = paths.bin_dir / name
+        shutil.copy2(binary, target)
+        target.chmod(target.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+    modulefile = render_modulefile(
+        ModuleSpec(
+            name=name,
+            version=version,
+            root=paths.install_root,
+            bin_dir=paths.bin_dir,
+            description=description,
+            homepage=homepage,
+            install_hint=f"copy binary to {paths.bin_dir / name}",
+        )
+    )
+    write_text(paths.modulefile, modulefile)
+    return paths

module_manager/modulefile.py

@@ -0,0 +1,72 @@
+"""Rendering helpers for GNU/Tcl environment modulefiles."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+def tcl_quote(value: str) -> str:
+    """Quote a string for the small Tcl subset used in modulefiles."""
+    escaped = value.replace("\\", "\\\\").replace('"', '\\"').replace("$", "\\$")
+    return f'"{escaped}"'
+
+
+@dataclass(frozen=True)
+class ModuleSpec:
+    """Data required to render one versioned environment modulefile."""
+
+    name: str
+    version: str
+    root: Path
+    bin_dir: Path
+    description: str | None = None
+    family: str | None = None
+    homepage: str | None = None
+    install_hint: str | None = None
+
+    @property
+    def module_path(self) -> str:
+        """Return the canonical module name/version path."""
+        return f"{self.name}/{self.version}"
+
+
+def render_modulefile(spec: ModuleSpec) -> str:
+    """Render a Tcl modulefile for the given module specification."""
+    description = spec.description or f"{spec.name} {spec.version}"
+    lines = [
+        "#%Module1.0",
+        f"## {spec.module_path}",
+        "",
+        "proc ModulesHelp { } {",
+        f"    puts stderr {tcl_quote(description)}",
+    ]
+
+    if spec.homepage:
+        lines.append(f"    puts stderr {tcl_quote('Homepage: ' + spec.homepage)}")
+    if spec.install_hint:
+        lines.append(f"    puts stderr {tcl_quote('Install: ' + spec.install_hint)}")
+
+    lines.extend(
+        [
+            "}",
+            "",
+            f"module-whatis {tcl_quote(description)}",
+        ]
+    )
+
+    if spec.family:
+        lines.append(f"family {tcl_quote(spec.family)}")
+
+    lines.extend(
+        [
+            "",
+            f"set root {tcl_quote(str(spec.root))}",
+            f"set bindir {tcl_quote(str(spec.bin_dir))}",
+            "",
+            "prepend-path PATH $bindir",
+            f"setenv {spec.name.upper().replace('-', '_')}_ROOT $root",
+            "",
+        ]
+    )
+    return "\n".join(lines)