uv-toolbox 0.1.0__tar.gz

uv_toolbox-0.1.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: uv-toolbox
+Version: 0.1.0
+Summary: Manage Python tool environments with declarative configuration and content-addressed storage.
+Keywords: uv,virtual-environment,venv,tools,python,dependency-management,cli,content-addressed
+Author: James Trousdale
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: System :: Systems Administration
+Requires-Dist: typer==0.21.1
+Requires-Dist: pydantic>=2.7.0,<3
+Requires-Dist: pydantic-settings>=2.7.0,<3
+Requires-Dist: pyyaml>=6,<7
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/hotdog-werx/uv-toolbox
+Project-URL: Repository, https://github.com/hotdog-werx/uv-toolbox
+Project-URL: Bug Tracker, https://github.com/hotdog-werx/uv-toolbox/issues
+Project-URL: Changelog, https://github.com/hotdog-werx/uv-toolbox/blob/master/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# uv-toolbox
+
+[![CI](https://github.com/hotdog-werx/uv-toolbox/actions/workflows/ci-checks.yaml/badge.svg)](https://github.com/hotdog-werx/uv-toolbox/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/uv-toolbox.svg)](https://pypi.org/project/uv-toolbox/)
+[![Python Version](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![codecov](https://codecov.io/gh/hotdog-werx/uv-toolbox/branch/master/graph/badge.svg)](https://codecov.io/gh/hotdog-werx/uv-toolbox)
+
+`uv-toolbox` is a CLI tool for managing Python tool environments. It will help
+you create multiple virtual environments and manage their dependencies through a
+declarative configuration file.
+
+Here is an example in YAML format:
+
+```yaml
+environments:
+  - name: env1
+    requirements: |
+      ruff==0.13.0
+      black
+    executables: [ruff, black]
+  - name: env2
+    requirements: |
+      isort
+      flake8
+    executables: [isort, flake8]
+```
+
+### Configuration Options
+
+**Virtual Environment Location:**
+
+By default, virtual environments are stored in `~/.cache/uv-toolbox/` using
+**content-addressed storage**. This means:
+
+- **Automatic deduplication**: Identical requirements across projects share the
+  same venv
+- **No naming conflicts**: Venvs are organized by content hash, not names
+- **Works from subdirectories**: Run commands from anywhere in your project
+
+```yaml
+# Default: centralized, content-addressed storage
+# (no venv_path needed - defaults to ~/.cache/uv-toolbox)
+environments:
+  - name: formatting
+    requirements: ruff==0.13.0
+  - name: testing
+    requirements: pytest==8.0.0
+
+# Optional: local storage (per-project)
+venv_path: .uv-toolbox
+```
+
+**How it works:**
+
+- Each environment's venv location is determined by hashing its requirements
+- Projects with identical requirements automatically share the same venv
+- Config files are discovered by walking up the directory tree
+
+**Executables:**
+
+The `executables` field controls which tools are exposed via shims:
+
+```yaml
+environments:
+  - name: formatting
+    requirements: ruff==0.13.0
+    executables: [ruff] # Only ruff will be available in PATH via shims
+```
+
+- **Optional**: Only needed if you want to use `uv-toolbox shim`
+- **Explicit control**: List exactly which executables to expose
+- **Prevents PATH pollution**: Python/pip from the venv won't be added to PATH
+
+## Usage
+
+Install environments:
+
+```bash
+uv-toolbox install
+```
+
+Run a command inside an environment (uses the configured default if set,
+otherwise pass `--env`):
+
+```bash
+uv-toolbox exec --env env1 -- ruff --version
+```
+
+Add shim scripts to your PATH for direct tool access:
+
+```bash
+eval "$(uv-toolbox shim)"
+```
+
+This creates wrapper scripts for executables listed in the `executables` field
+of each environment. Only explicitly listed executables are exposed, preventing
+Python/pip from polluting your PATH.

uv_toolbox-0.1.0/README.md

@@ -0,0 +1,98 @@
+# uv-toolbox
+
+[![CI](https://github.com/hotdog-werx/uv-toolbox/actions/workflows/ci-checks.yaml/badge.svg)](https://github.com/hotdog-werx/uv-toolbox/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/uv-toolbox.svg)](https://pypi.org/project/uv-toolbox/)
+[![Python Version](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![codecov](https://codecov.io/gh/hotdog-werx/uv-toolbox/branch/master/graph/badge.svg)](https://codecov.io/gh/hotdog-werx/uv-toolbox)
+
+`uv-toolbox` is a CLI tool for managing Python tool environments. It will help
+you create multiple virtual environments and manage their dependencies through a
+declarative configuration file.
+
+Here is an example in YAML format:
+
+```yaml
+environments:
+  - name: env1
+    requirements: |
+      ruff==0.13.0
+      black
+    executables: [ruff, black]
+  - name: env2
+    requirements: |
+      isort
+      flake8
+    executables: [isort, flake8]
+```
+
+### Configuration Options
+
+**Virtual Environment Location:**
+
+By default, virtual environments are stored in `~/.cache/uv-toolbox/` using
+**content-addressed storage**. This means:
+
+- **Automatic deduplication**: Identical requirements across projects share the
+  same venv
+- **No naming conflicts**: Venvs are organized by content hash, not names
+- **Works from subdirectories**: Run commands from anywhere in your project
+
+```yaml
+# Default: centralized, content-addressed storage
+# (no venv_path needed - defaults to ~/.cache/uv-toolbox)
+environments:
+  - name: formatting
+    requirements: ruff==0.13.0
+  - name: testing
+    requirements: pytest==8.0.0
+
+# Optional: local storage (per-project)
+venv_path: .uv-toolbox
+```
+
+**How it works:**
+
+- Each environment's venv location is determined by hashing its requirements
+- Projects with identical requirements automatically share the same venv
+- Config files are discovered by walking up the directory tree
+
+**Executables:**
+
+The `executables` field controls which tools are exposed via shims:
+
+```yaml
+environments:
+  - name: formatting
+    requirements: ruff==0.13.0
+    executables: [ruff] # Only ruff will be available in PATH via shims
+```
+
+- **Optional**: Only needed if you want to use `uv-toolbox shim`
+- **Explicit control**: List exactly which executables to expose
+- **Prevents PATH pollution**: Python/pip from the venv won't be added to PATH
+
+## Usage
+
+Install environments:
+
+```bash
+uv-toolbox install
+```
+
+Run a command inside an environment (uses the configured default if set,
+otherwise pass `--env`):
+
+```bash
+uv-toolbox exec --env env1 -- ruff --version
+```
+
+Add shim scripts to your PATH for direct tool access:
+
+```bash
+eval "$(uv-toolbox shim)"
+```
+
+This creates wrapper scripts for executables listed in the `executables` field
+of each environment. Only explicitly listed executables are exposed, preventing
+Python/pip from polluting your PATH.

uv_toolbox-0.1.0/pyproject.toml

@@ -0,0 +1,65 @@
+[project]
+name = "uv-toolbox"
+description = "Manage Python tool environments with declarative configuration and content-addressed storage."
+readme = "README.md"
+requires-python = ">=3.11"
+version = "0.1.0"
+license = "MIT"
+authors = [{ name = "James Trousdale" }]
+keywords = [
+  "uv",
+  "virtual-environment",
+  "venv",
+  "tools",
+  "python",
+  "dependency-management",
+  "cli",
+  "content-addressed",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Topic :: System :: Systems Administration",
+]
+
+dependencies = [
+  "typer ==0.21.1",
+  "pydantic >=2.7.0, <3",
+  "pydantic-settings >=2.7.0, <3",
+  'PyYAML >=6,<7',
+]
+
+[project.urls]
+Homepage = "https://github.com/hotdog-werx/uv-toolbox"
+Repository = "https://github.com/hotdog-werx/uv-toolbox"
+"Bug Tracker" = "https://github.com/hotdog-werx/uv-toolbox/issues"
+Changelog = "https://github.com/hotdog-werx/uv-toolbox/blob/master/CHANGELOG.md"
+
+[project.scripts]
+uv-toolbox = "uv_toolbox.cli:main"
+uvtb = "uv_toolbox.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8.0.0", "pytest-mock>=3.12.0", "pytest-cov>=4.0.0"]
+
+[tool.ruff]
+extend = "./.pkglink/.codeguide/configs/ruff.toml"
+
+[tool.releez]
+create-pr = true
+run-changelog-format = true
+hooks = { changelog-format = ["mise", "exec", "--", "poe", "format-dprint", "{changelog}"] }
+
+[build-system]
+requires = ["uv_build>=0.9.27,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = ["uv_toolbox"]
+module-root = ""

uv_toolbox-0.1.0/uv_toolbox/__init__.py

@@ -0,0 +1,3 @@
+import importlib.metadata
+
+__version__ = importlib.metadata.version('uv_toolbox')

uv_toolbox-0.1.0/uv_toolbox/cli.py

@@ -0,0 +1,166 @@
+import os
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from uv_toolbox.errors import CommandDelimiterRequiredError, UvToolboxError
+from uv_toolbox.process import run_checked
+from uv_toolbox.settings import UvToolboxSettings
+from uv_toolbox.shims import create_shims
+from uv_toolbox.utils import _filter_nulls
+from uv_toolbox.uv_helpers import initialize_virtualenv
+
+app = typer.Typer(help='CLI tool for managing UV tool environments.')
+
+
+@app.callback()
+def _root(
+    ctx: typer.Context,
+    config_file: Annotated[
+        Path | None,
+        typer.Option(
+            ...,
+            '--config',
+            '-c',
+            help='Path to a uv-toolbox config file.',
+        ),
+    ] = None,
+) -> None:
+    """UV Toolbox CLI."""
+    ctx.obj = _filter_nulls({'config_file': config_file})
+
+
+@app.command(name='install')
+def install(
+    ctx: typer.Context,
+    *,
+    venv_path: Annotated[
+        Path | None,
+        typer.Option(
+            ...,
+            '--venv-path',
+            help='Path to the directory where virtual environments are stored.',
+        ),
+    ] = None,
+    clear: Annotated[
+        bool,
+        typer.Option(
+            ...,
+            '--clear',
+            '-c',
+            help='Clear and recreate the virtual environments.',
+        ),
+    ] = False,
+) -> None:
+    """Install UV tool environments."""
+    settings = UvToolboxSettings.from_context(ctx, venv_path=venv_path)
+    for env in settings.environments:
+        try:
+            initialize_virtualenv(env=env, settings=settings, clear=clear)
+        except UvToolboxError as exc:
+            typer.secho(str(exc), err=True, fg=typer.colors.RED)
+            raise typer.Exit(code=1) from exc
+
+
+@app.command(name='exec')
+def exec_(
+    ctx: typer.Context,
+    *,
+    command: Annotated[
+        list[str],
+        typer.Argument(
+            ...,
+            help='Command to run in the environment.',
+        ),
+    ],
+    env_name: Annotated[
+        str | None,
+        typer.Option(
+            ...,
+            '--env',
+            '-e',
+            help='Environment name (required when multiple environments exist).',
+        ),
+    ] = None,
+    clear: Annotated[
+        bool,
+        typer.Option(
+            ...,
+            '--clear',
+            '-c',
+            help='Clear and recreate the virtual environment.',
+        ),
+    ] = False,
+    venv_path: Annotated[
+        Path | None,
+        typer.Option(
+            ...,
+            '--venv-path',
+            help='Path to the directory where virtual environments are stored.',
+        ),
+    ] = None,
+) -> None:
+    """Execute a command within a UV tool environment."""
+    if '--' not in sys.argv:
+        raise CommandDelimiterRequiredError
+    settings = UvToolboxSettings.from_context(ctx, venv_path=venv_path)
+    try:
+        env = settings.select_environment(
+            env_name=env_name,
+        )
+
+        if not env.venv_path(settings=settings).exists() or clear:
+            initialize_virtualenv(
+                env=env,
+                settings=settings,
+                clear=clear,
+            )
+
+        # Use uv run with --no-project to prevent automatic project detection
+        # VIRTUAL_ENV is set via extra_env to specify which venv to use
+        run_checked(
+            args=['uv', 'run', '--no-project', '--', *command],
+            capture_stdout=False,
+            capture_stderr=False,
+            extra_env=env.process_env(settings=settings),
+            show_command=settings.show_commands,
+        )
+    except UvToolboxError as exc:
+        typer.secho(str(exc), err=True, fg=typer.colors.RED)
+        raise typer.Exit(code=1) from exc
+
+
+@app.command(name='shim')
+def shim(
+    ctx: typer.Context,
+    venv_path: Annotated[
+        Path | None,
+        typer.Option(
+            ...,
+            '--venv-path',
+            help='Path to the directory where virtual environments are stored.',
+        ),
+    ] = None,
+) -> None:
+    """Create shim scripts for tools and emit shell code to add shims to PATH."""
+    settings = UvToolboxSettings.from_context(ctx, venv_path=venv_path)
+
+    try:
+        shim_dirs = create_shims(settings=settings)
+        if shim_dirs:
+            # Join all shim directories in config order
+            shim_path = os.pathsep.join(str(d) for d in shim_dirs)
+            typer.echo(f'export PATH="{shim_path}{os.pathsep}$PATH"')
+        else:
+            # No shims created (no venvs or no executables)
+            typer.echo('# No shims to add to PATH')
+    except UvToolboxError as exc:
+        typer.secho(str(exc), err=True, fg=typer.colors.RED)
+        raise typer.Exit(code=1) from exc
+
+
+def main() -> None:
+    """Main entry point for the CLI."""
+    app()

uv_toolbox-0.1.0/uv_toolbox/errors.py

@@ -0,0 +1,111 @@
+from __future__ import annotations
+
+import typing
+
+if typing.TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+
+class UvToolboxError(RuntimeError):
+    """Base error for uv-toolbox.."""
+
+
+class MissingCliError(UvToolboxError):
+    """Raised when a required CLI executable is missing."""
+
+    cli_names: list[str]
+
+    def __init__(self, cli_names: str | Sequence[str]) -> None:
+        self.cli_names = [cli_names] if isinstance(cli_names, str) else list(cli_names)
+        if len(self.cli_names) == 1:
+            message = f'Required CLI {self.cli_names[0]!r} is not installed or not on PATH.'
+        else:
+            joined = ', '.join(repr(name) for name in self.cli_names)
+            message = f'Required CLIs {joined} are not installed or not on PATH.'
+        super().__init__(message)
+
+
+class ExternalCommandError(UvToolboxError):
+    """Raised when an external command returns a non-zero status."""
+
+    cmd_args: list[str]
+    returncode: int
+    stderr: str
+
+    def __init__(
+        self,
+        *,
+        cmd_args: Sequence[str],
+        returncode: int,
+        stderr: str | None = None,
+    ) -> None:
+        self.cmd_args = list(cmd_args)
+        self.returncode = returncode
+        self.stderr = (stderr or '').strip()
+
+        cmd = ' '.join(self.cmd_args)
+        message = f'Command failed ({self.returncode}): {cmd}'
+        if self.stderr:
+            message = f'{message}\n{self.stderr}'
+        super().__init__(message)
+
+
+class EnvironmentNotFoundError(UvToolboxError):
+    """Raised when the requested environment name does not exist."""
+
+    env_name: str
+    available: list[str]
+
+    def __init__(self, env_name: str, available: list[str]) -> None:
+        self.env_name = env_name
+        self.available = available
+        available_list = ', '.join(available) or '<none>'
+        super().__init__(
+            f'Environment {env_name!r} not found. Available environments: {available_list}.',
+        )
+
+
+class MultipleEnvironmentsError(UvToolboxError):
+    """Raised when multiple environments exist but none was selected."""
+
+    available: list[str]
+
+    def __init__(self, available: list[str]) -> None:
+        self.available = available
+        available_list = ', '.join(available) or '<none>'
+        super().__init__(
+            f'Multiple environments configured; use --env to select one. Available environments: {available_list}.',
+        )
+
+
+class CommandDelimiterRequiredError(UvToolboxError):
+    """Raised when an exec command is missing the required `--` delimiter."""
+
+    def __init__(self) -> None:
+        super().__init__('Commands must be passed after `--`.')
+
+
+class ConfigFileNotFoundError(UvToolboxError):
+    """Raised when an explicit config file path does not exist."""
+
+    config_file: Path
+
+    def __init__(self, config_file: Path) -> None:
+        self.config_file = config_file
+        super().__init__(f'Configuration file not found: {config_file}')
+
+
+class MissingConfigFileError(UvToolboxError):
+    """Raised when no configuration file can be found."""
+
+    searched_files: list[Path]
+
+    def __init__(self, searched_files: list[Path]) -> None:
+        self.searched_files = searched_files
+        searched = ', '.join(str(path) for path in searched_files)
+        super().__init__(
+            'No configuration file found. '
+            f'Searched: {searched}. '
+            'Use --config or UV_TOOLBOX_CONFIG_FILE to specify a file.',
+        )

uv_toolbox-0.1.0/uv_toolbox/process.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import os
+import subprocess
+import typing
+
+import typer
+
+from uv_toolbox.errors import ExternalCommandError, MissingCliError
+
+if typing.TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+
+def _print_command(args: Sequence[str]) -> None:
+    """Print a command in a nice format to stderr.
+
+    Args:
+        args: The command and arguments to print.
+    """
+    cmd = ' '.join(args)
+    typer.secho(f'▶ {cmd}', fg=typer.colors.BRIGHT_BLACK, err=True)
+
+
+def run_checked(  # noqa: PLR0913
+    args: Sequence[str],
+    *,
+    cwd: Path | None = None,
+    capture_stdout: bool = True,
+    capture_stderr: bool = True,
+    extra_env: dict[str, str] | None = None,
+    show_command: bool = False,
+) -> str:
+    """Run a command and raise a UvToolboxError on failure.
+
+    Args:
+        args: The command and arguments to execute.
+        cwd: Optional working directory for the command.
+        capture_stdout: If false, stdout is not captured.
+        capture_stderr: If false, stderr is not captured.
+        extra_env: Additional environment variables to set for the command.
+        show_command: If true, print the command before executing.
+
+    Returns:
+        The stripped stdout of the command.
+
+    Raises:
+        MissingCliError: If the executable is not found.
+        ExternalCommandError: If the command exits non-zero.
+    """
+    if show_command:
+        _print_command(args)
+
+    try:
+        stdout = subprocess.PIPE if capture_stdout else None
+        stderr = subprocess.PIPE if capture_stderr else None
+        res = subprocess.run(  # noqa: S603
+            list(args),
+            cwd=cwd,
+            check=True,
+            text=True,
+            stdout=stdout,
+            stderr=stderr,
+            env={
+                **os.environ,
+                **(extra_env or {}),
+            },
+        )
+    except FileNotFoundError as exc:
+        raise MissingCliError(args[0]) from exc
+    except subprocess.CalledProcessError as exc:
+        stderr = (exc.stderr or '').strip() if capture_stderr else ''
+        raise ExternalCommandError(
+            cmd_args=args,
+            returncode=exc.returncode,
+            stderr=stderr,
+        ) from exc
+
+    return (res.stdout or '').strip() if capture_stdout else ''