uv-toolbox 0.1.0__py3-none-any.whl

uv_toolbox/__init__.py

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

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/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/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 ''

uv_toolbox/settings.py

@@ -0,0 +1,465 @@
+from __future__ import annotations
+
+import hashlib
+import os
+import tomllib
+import typing
+import warnings
+from contextlib import contextmanager
+from os.path import expandvars
+from pathlib import Path
+
+from pydantic import (
+    AliasChoices,
+    AliasGenerator,
+    BaseModel,
+    ConfigDict,
+    Field,
+    model_validator,
+)
+from pydantic_settings import (
+    BaseSettings,
+    InitSettingsSource,
+    JsonConfigSettingsSource,
+    PydanticBaseSettingsSource,
+    PyprojectTomlConfigSettingsSource,
+    SettingsConfigDict,
+    TomlConfigSettingsSource,
+    YamlConfigSettingsSource,
+)
+
+from uv_toolbox.errors import (
+    ConfigFileNotFoundError,
+    EnvironmentNotFoundError,
+    MissingConfigFileError,
+    MultipleEnvironmentsError,
+)
+from uv_toolbox.utils import _filter_nulls
+
+if typing.TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    import typer
+
+
+def _to_kebab(name: str) -> str:
+    """Convert snake_case to kebab-case."""
+    return name.replace('_', '-')
+
+
+def _validation_alias(name: str) -> AliasChoices:
+    """Accept both snake_case and kebab-case for settings keys.
+
+    `AliasChoices` order matters: we list the snake_case field name first so if both
+    variants are present (e.g. env var + pyproject), the env var wins.
+    """
+    return AliasChoices(name, _to_kebab(name))
+
+
+_ALIASES = AliasGenerator(
+    validation_alias=_validation_alias,
+    serialization_alias=_to_kebab,
+)
+
+
+class UvToolboxEnvironment(BaseModel):
+    """Definition of a UV toolbox environment.
+
+    Attributes:
+        requirements: A pip requirements string (mutually exclusive with
+            requirements_file).
+        requirements_file: A path to a pip requirements file (mutually
+            exclusive with requirements).
+        executables: List of executable names to create shims for. If not
+            specified, no shims will be created for this environment.
+    """
+
+    name: str
+    requirements: str | None = None
+    requirements_file: Path | None = None
+    environment: dict[str, str] = {}
+    executables: list[str] = []
+
+    model_config = ConfigDict(
+        alias_generator=_ALIASES,
+        populate_by_name=True,
+    )
+
+    @model_validator(mode='after')
+    def check_requirements(self) -> UvToolboxEnvironment:
+        """Validate that only one of requirements or requirements_file is set."""
+        if not (bool(self.requirements) ^ bool(self.requirements_file)):
+            msg = 'Exactly one of requirements or requirements_file must be set.'
+            raise ValueError(msg)
+        return self
+
+    @staticmethod
+    def _normalize_requirements(req: str) -> str:
+        """Normalize requirements string for consistent hashing.
+
+        - Removes comments and blank lines
+        - Strips whitespace
+        - Sorts lines alphabetically for consistency
+        """
+        lines = [line.strip() for line in req.strip().split('\n')]
+        # Remove empty lines and comments
+        lines = [line for line in lines if line and not line.startswith('#')]
+        # Sort for consistency
+        return '\n'.join(sorted(lines))
+
+    def _get_requirements_hash(self) -> str:
+        """Generate a hash of the environment's requirements.
+
+        Returns a 12-character hex string based on the normalized requirements.
+        """
+        if self.requirements:
+            normalized = self._normalize_requirements(self.requirements)
+        else:
+            # Read and normalize requirements file
+            if self.requirements_file is None:  # pragma: no cover
+                # Impossible: check_requirements validator ensures one is set
+                msg = 'Either requirements or requirements_file must be set'
+                raise ValueError(msg)  # pragma: no cover
+            normalized = self._normalize_requirements(
+                self.requirements_file.read_text(),
+            )
+
+        # Use SHA-256 for hashing (truncated to 12 chars for readability)
+        return hashlib.sha256(normalized.encode()).hexdigest()[:12]
+
+    def venv_path(self, settings: UvToolboxSettings) -> Path:
+        """Get the path to the virtual environment for this environment.
+
+        Uses content-based addressing: the venv location is determined by
+        hashing the normalized requirements, ensuring identical requirements
+        share the same venv across projects.
+        """
+        req_hash = self._get_requirements_hash()
+        return settings.resolved_venv_path / req_hash
+
+    def process_env(self, settings: UvToolboxSettings) -> dict[str, str]:
+        """Environment variables for processes run in this environment."""
+        return {
+            **{k: expandvars(v) for k, v in self.environment.items()},
+            'VIRTUAL_ENV': str(self.venv_path(settings=settings)),
+        }
+
+
+class UvToolboxSettings(BaseSettings):
+    """Settings loaded from config files.
+
+    Precedence (highest first):
+      1. CLI args (passed to initialization)
+      2. Environment variables (with `UV_TOOLBOX_` prefix)
+      3. Configuration files, in order:
+        1. uv-toolbox.yaml
+        2. uv-toolbox.json
+        3. uv-toolbox.toml
+        4. pyproject.toml ([tool.uv-toolbox])
+    """
+
+    config_file: Path | None = None
+    venv_path: Path = Path.home() / '.cache' / 'uv-toolbox'
+    default_environment: str | None = None
+    show_commands: bool = False
+    environments: typing.Annotated[
+        list[UvToolboxEnvironment],
+        Field(min_length=1),
+    ]
+
+    model_config = SettingsConfigDict(
+        env_prefix='UV_TOOLBOX_',
+        env_nested_delimiter='__',
+        extra='forbid',
+        pyproject_toml_table_header=('tool', 'uv-toolbox'),
+        alias_generator=_ALIASES,
+        populate_by_name=True,
+    )
+
+    @property
+    def resolved_venv_path(self) -> Path:
+        """Resolve the venv path.
+
+        Behavior:
+        - Relative paths: resolved relative to config file location
+        - Absolute paths: used as-is
+
+        Individual venvs are stored in content-addressed subdirectories based
+        on hashing their requirements.
+        """
+        # Determine base path
+        if self.venv_path.is_absolute():
+            return self.venv_path
+        if self.config_file is None:  # pragma: no cover
+            # Defensive: shouldn't happen in normal CLI use (only in direct model_validate)
+            return Path.cwd() / self.venv_path
+        # Relative path - resolve from config file location
+        return self.config_file.parent / self.venv_path
+
+    def select_environment(self, env_name: str | None) -> UvToolboxEnvironment:
+        """Select an environment by name.
+
+        If env_name is none
+        """
+        env_name = env_name or self.default_environment
+
+        if env_name is not None:
+            for env in self.environments:
+                if env.name == env_name:
+                    return env
+            available = [env.name for env in self.environments]
+            raise EnvironmentNotFoundError(env_name, available)
+
+        if len(self.environments) == 1:
+            return self.environments[0]
+
+        available = [env.name for env in self.environments]
+        raise MultipleEnvironmentsError(available)
+
+    @model_validator(mode='after')
+    def ensure_unique_env_names(
+        self,
+    ) -> UvToolboxSettings:
+        """Validate that environment names are unique."""
+        all_env_names = [env.name for env in self.environments]
+        duplicate_names = {name for name in all_env_names if all_env_names.count(name) > 1}
+        if duplicate_names:
+            msg = f'Duplicate environment names found: {", ".join(sorted(duplicate_names))}'
+            raise ValueError(msg)
+        return self
+
+    @model_validator(mode='after')
+    def ensure_valid_default_environment(
+        self,
+    ) -> UvToolboxSettings:
+        """Validate that the default environment name exists."""
+        if self.default_environment is not None:
+            env_names = {env.name for env in self.environments}
+            if self.default_environment not in env_names:
+                msg = f'Default environment {self.default_environment!r} not found in environments.'
+                raise ValueError(msg)
+        return self
+
+    @classmethod
+    def from_context(
+        cls,
+        ctx: typer.Context,
+        **overrides: object,
+    ) -> UvToolboxSettings:
+        """Create settings from a Typer context and optional overrides.
+
+        Args:
+            ctx: Typer context containing CLI args.
+            **overrides: Additional settings to override.
+
+        Returns:
+            UvToolboxSettings instance.
+        """
+        cli_args = {
+            **(ctx.obj or {}),
+            **_filter_nulls(overrides),
+        }
+        _verify_config_file(cli_args)
+        with _suppress_unused_pyproject_warning():
+            return UvToolboxSettings.model_validate(cli_args)
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,  # noqa: ARG003
+        file_secret_settings: PydanticBaseSettingsSource,  # noqa: ARG003
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        """Customize settings sources for UV Toolbox."""
+        init_kwargs = typing.cast(
+            'InitSettingsSource',
+            init_settings,
+        ).init_kwargs
+        config_file = init_kwargs.get('config_file')
+
+        if config_file is None:
+            config_file = os.environ.get('UV_TOOLBOX_CONFIG_FILE')
+
+        if config_file:
+            config_source = _config_file_source(settings_cls, Path(config_file))
+            return (
+                init_settings,
+                env_settings,
+                config_source,
+            )
+
+        uv_toolbox_yaml = YamlConfigSettingsSource(
+            settings_cls,
+            yaml_file='uv-toolbox.yaml',
+        )
+        uv_toolbox_json = JsonConfigSettingsSource(
+            settings_cls,
+            json_file='uv-toolbox.json',
+        )
+        uv_toolbox_toml = TomlConfigSettingsSource(
+            settings_cls,
+            toml_file='uv-toolbox.toml',
+        )
+        pyproject_toml = PyprojectTomlConfigSettingsSource(settings_cls)
+        return (
+            init_settings,
+            env_settings,
+            uv_toolbox_yaml,
+            uv_toolbox_json,
+            uv_toolbox_toml,
+            pyproject_toml,
+        )
+
+
+def _config_file_source(
+    settings_cls: type[BaseSettings],
+    config_file: Path,
+) -> PydanticBaseSettingsSource:
+    if config_file.name == 'pyproject.toml':
+        return PyprojectTomlConfigSettingsSource(
+            settings_cls,
+            toml_file=config_file,
+        )
+
+    suffix = config_file.suffix.lower()
+    if suffix in {'.yaml', '.yml'}:
+        return YamlConfigSettingsSource(settings_cls, yaml_file=config_file)
+    if suffix == '.json':
+        return JsonConfigSettingsSource(settings_cls, json_file=config_file)
+    if suffix == '.toml':
+        return TomlConfigSettingsSource(settings_cls, toml_file=config_file)
+    msg = f'Unsupported config file extension: {config_file}'
+    raise ValueError(msg)
+
+
+def _pyproject_has_uv_toolbox_config(path: Path) -> bool:
+    if not path.is_file():
+        return False
+    try:
+        data = tomllib.loads(path.read_text())
+    except (OSError, tomllib.TOMLDecodeError):
+        return False
+    tool_section = data.get('tool')
+    if not isinstance(tool_section, dict):
+        return False
+    uv_section = tool_section.get('uv-toolbox')
+    return isinstance(uv_section, dict)
+
+
+def _check_directory_for_config(directory: Path) -> Path | None:
+    """Check a directory for UV Toolbox config files.
+
+    Args:
+        directory: Directory to check
+
+    Returns:
+        Path to config file if found, None otherwise
+    """
+    config_names = [
+        'uv-toolbox.yaml',
+        'uv-toolbox.json',
+        'uv-toolbox.toml',
+    ]
+
+    # Check for dedicated config files
+    for name in config_names:
+        config_path = directory / name
+        if config_path.exists():
+            return config_path
+
+    # Check pyproject.toml with [tool.uv-toolbox] section
+    pyproject = directory / 'pyproject.toml'
+    if pyproject.exists() and _pyproject_has_uv_toolbox_config(pyproject):
+        return pyproject
+
+    return None
+
+
+def _find_config_file(start_path: Path | None = None) -> Path | None:
+    """Find UV Toolbox config file by walking up the directory tree.
+
+    Searches for config files in this order:
+    1. uv-toolbox.yaml
+    2. uv-toolbox.json
+    3. uv-toolbox.toml
+    4. pyproject.toml (with [tool.uv-toolbox] section)
+
+    Stops at:
+    - First config file found
+    - .git directory (project boundary)
+    - Filesystem root
+
+    Args:
+        start_path: Directory to start searching from (defaults to cwd)
+
+    Returns:
+        Path to config file, or None if not found
+    """
+    current = start_path or Path.cwd()
+
+    for parent in [current, *current.parents]:
+        # Check this directory for config files
+        config_file = _check_directory_for_config(parent)
+        if config_file:
+            return config_file
+
+        # Stop at git root as a boundary
+        if (parent / '.git').exists():
+            break
+
+    return None
+
+
+def _verify_config_file(cli_args: dict[str, object]) -> None:
+    config_file = cli_args.get('config_file') or os.getenv(
+        'UV_TOOLBOX_CONFIG_FILE',
+    )
+    if config_file:
+        config_path = Path(str(config_file))
+        if not config_path.exists():
+            raise ConfigFileNotFoundError(config_path)
+        # Store the config file path for later use
+        cli_args['config_file'] = config_path
+        return
+
+    # Search up the directory tree for a config file
+    found_config = _find_config_file()
+    if found_config:
+        # Store the found config file path
+        cli_args['config_file'] = found_config
+        return
+
+    # No config file found - show what we searched for
+    current = Path.cwd()
+    searched_dirs = [current, *current.parents]
+    # Stop at git root if found
+    for i, directory in enumerate(searched_dirs):
+        if (directory / '.git').exists():
+            searched_dirs = searched_dirs[: i + 1]
+            break
+
+    # Show example paths from the current directory
+    config_candidates = [
+        current / 'uv-toolbox.yaml',
+        current / 'uv-toolbox.json',
+        current / 'uv-toolbox.toml',
+        current / 'pyproject.toml',
+    ]
+    raise MissingConfigFileError(config_candidates)
+
+
+@contextmanager
+def _suppress_unused_pyproject_warning() -> Iterator[None]:
+    with warnings.catch_warnings():
+        warnings.filterwarnings(
+            'ignore',
+            message=(
+                r'Config key `pyproject_toml_table_header` is set in model_config '
+                r'but will be ignored because no PyprojectTomlConfigSettingsSource '
+                r'source is configured\..*'
+            ),
+            category=UserWarning,
+        )
+        yield

uv_toolbox/shims.py

@@ -0,0 +1,200 @@
+"""Shim generation for UV Toolbox.
+
+Creates wrapper scripts for explicitly listed executables in virtual environments.
+"""
+
+from __future__ import annotations
+
+import os
+import stat
+import typing
+
+from uv_toolbox.utils import _venv_bin_path
+
+if typing.TYPE_CHECKING:
+    from pathlib import Path
+
+    from uv_toolbox.settings import UvToolboxEnvironment, UvToolboxSettings
+
+
+def _create_unix_shim(
+    shim_path: Path,
+    target_path: Path,
+    venv_path: Path,
+) -> None:
+    """Create a Unix shell script shim.
+
+    Args:
+        shim_path: Path where the shim script should be created.
+        target_path: Path to the actual executable.
+        venv_path: Path to the virtual environment.
+    """
+    python_exe = venv_path / 'bin' / 'python'
+    script = f"""#!/usr/bin/env bash
+VIRTUAL_ENV="{venv_path}"
+exec uv run --no-project --python "{python_exe}" -- "{target_path}" "$@"
+"""
+    shim_path.write_text(script)
+    # Make executable
+    shim_path.chmod(
+        shim_path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH,
+    )
+
+
+def _create_windows_shim(
+    shim_path: Path,
+    target_path: Path,
+    venv_path: Path,
+) -> None:
+    """Create a Windows batch script shim.
+
+    Args:
+        shim_path: Path where the shim script should be created (without extension).
+        target_path: Path to the actual executable.
+        venv_path: Path to the virtual environment.
+    """
+    # Create .bat file
+    bat_path = shim_path.with_suffix('.bat')
+    python_exe = venv_path / 'Scripts' / 'python.exe'
+    script = f"""@echo off
+set VIRTUAL_ENV={venv_path}
+uv run --no-project --python "{python_exe}" -- "{target_path}" %*
+"""
+    bat_path.write_text(script)
+
+
+def _find_windows_executable(bin_path: Path, exe_name: str) -> Path | None:
+    """Find an executable in a Windows venv Scripts directory.
+
+    Args:
+        bin_path: Path to the venv Scripts directory.
+        exe_name: Name of the executable to find.
+
+    Returns:
+        Path to the executable if found, None otherwise.
+    """
+    for ext in ['.exe', '.bat', '.cmd']:
+        exe_path = bin_path / f'{exe_name}{ext}'
+        if exe_path.exists():
+            return exe_path
+    return None
+
+
+def _find_unix_executable(bin_path: Path, exe_name: str) -> Path | None:
+    """Find an executable in a Unix venv bin directory.
+
+    Args:
+        bin_path: Path to the venv bin directory.
+        exe_name: Name of the executable to find.
+
+    Returns:
+        Path to the executable if found, None otherwise.
+    """
+    exe_path = bin_path / exe_name
+    if exe_path.exists() and os.access(exe_path, os.X_OK):
+        return exe_path
+    return None
+
+
+def _find_executable(bin_path: Path, exe_name: str) -> Path | None:
+    """Find an executable in a venv bin directory.
+
+    Args:
+        bin_path: Path to the venv bin directory.
+        exe_name: Name of the executable to find.
+
+    Returns:
+        Path to the executable if found, None otherwise.
+    """
+    if os.name == 'nt':
+        return _find_windows_executable(bin_path, exe_name)
+    return _find_unix_executable(bin_path, exe_name)
+
+
+def _create_shim_for_executable(
+    exe_name: str,
+    venv_path: Path,
+    bin_path: Path,
+    shim_dir: Path,
+) -> None:
+    """Create a shim for a single executable.
+
+    Args:
+        exe_name: Name of the executable.
+        venv_path: Path to the virtual environment.
+        bin_path: Path to the venv bin directory.
+        shim_dir: Directory where the shim should be created.
+    """
+    # Find the executable in the venv
+    target_path = _find_executable(bin_path, exe_name)
+    if target_path is None:
+        # Executable not found - skip silently
+        return
+
+    # Create shim path
+    shim_path = shim_dir / exe_name
+
+    # Create platform-specific shim
+    if os.name == 'nt':
+        _create_windows_shim(shim_path, target_path, venv_path)
+    else:
+        _create_unix_shim(shim_path, target_path, venv_path)
+
+
+def _create_shims_for_environment(
+    env: UvToolboxEnvironment,
+    settings: UvToolboxSettings,
+) -> Path | None:
+    """Create shim directory for a single environment.
+
+    Args:
+        env: The environment to create shims for.
+        settings: The UV toolbox settings.
+
+    Returns:
+        Path to the shim directory if created, None otherwise.
+    """
+    venv_path = env.venv_path(settings=settings)
+
+    # Skip if venv doesn't exist yet
+    if not venv_path.exists():
+        return None
+
+    # Skip if no executables listed
+    if not env.executables:
+        return None
+
+    # Shim directory is inside the venv
+    shim_dir = venv_path / 'shims'
+    shim_dir.mkdir(parents=True, exist_ok=True)
+
+    # Clear existing shims in this venv
+    for shim_file in shim_dir.iterdir():
+        if shim_file.is_file():
+            shim_file.unlink()
+
+    # Create shims for this environment's executables
+    bin_path = _venv_bin_path(venv_path)
+    for exe_name in env.executables:
+        _create_shim_for_executable(exe_name, venv_path, bin_path, shim_dir)
+
+    return shim_dir
+
+
+def create_shims(settings: UvToolboxSettings) -> list[Path]:
+    """Create per-venv shim scripts for explicitly listed executables.
+
+    Args:
+        settings: The UV toolbox settings.
+
+    Returns:
+        List of shim directories in config order (for PATH precedence).
+    """
+    shim_dirs: list[Path] = []
+
+    for env in settings.environments:
+        shim_dir = _create_shims_for_environment(env, settings)
+        if shim_dir is not None:
+            shim_dirs.append(shim_dir)
+
+    return shim_dirs

uv_toolbox/utils.py

@@ -0,0 +1,28 @@
+import os
+from pathlib import Path
+from typing import Any
+
+
+def _filter_nulls(d: dict[str, Any]) -> dict[str, Any]:
+    """Return a copy of the dictionary with all None values removed.
+
+    Args:
+        d: The dictionary to filter.
+
+    Returns:
+        A new dictionary with all None values removed.
+    """
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def _venv_bin_path(venv_path: Path) -> Path:
+    """Return the path to the 'bin' (or 'Scripts' on Windows) directory of the virtualenv.
+
+    Args:
+        venv_path: The path to the virtual environment.
+
+    Returns:
+        The path to the 'bin' or 'Scripts' directory within the virtual
+            environment.
+    """
+    return venv_path / ('Scripts' if os.name == 'nt' else 'bin')

uv_toolbox/uv_helpers.py

@@ -0,0 +1,93 @@
+import shutil
+import tempfile
+from pathlib import Path
+
+from uv_toolbox.process import run_checked
+from uv_toolbox.settings import UvToolboxEnvironment, UvToolboxSettings
+
+
+def create_virtualenv(
+    env: UvToolboxEnvironment,
+    settings: UvToolboxSettings,
+    *,
+    clear: bool = False,
+) -> None:
+    """Create a Python virtual environment at the specified path.
+
+    Args:
+        env: The UV toolbox environment to create the virtualenv for.
+        settings: The UV toolbox settings.
+        clear: If True, clear the existing venv if it already exists.
+    """
+    args = ['uv', 'venv', str(env.venv_path(settings=settings))]
+    if clear:
+        args.append('--clear')
+
+    run_checked(
+        args=args,
+        extra_env=env.process_env(settings=settings),
+        capture_stdout=False,
+        capture_stderr=False,
+        show_command=settings.show_commands,
+    )
+
+
+def install_requirements(
+    env: UvToolboxEnvironment,
+    settings: UvToolboxSettings,
+) -> None:
+    """Install the requirements for the given environment into its virtualenv.
+
+    Args:
+        env: The UV toolbox environment to install requirements for.
+        settings: The UV toolbox settings.
+    """
+    temp_dir: Path | None = None
+
+    if env.requirements_file is not None:
+        reqs_arg = ['-r', str(env.requirements_file)]
+    elif env.requirements is not None:
+        temp_dir = Path(tempfile.mkdtemp())
+        temp_req_file = temp_dir / f'requirements_{env.name}.txt'
+        temp_req_file.write_text(env.requirements)
+        reqs_arg = ['-r', str(temp_req_file)]
+
+    if reqs_arg:
+        run_checked(
+            args=[
+                'uv',
+                'pip',
+                'install',
+                *reqs_arg,
+                '--exact',
+            ],
+            extra_env=env.process_env(settings=settings),
+            capture_stdout=False,
+            capture_stderr=False,
+            show_command=settings.show_commands,
+        )
+
+    if temp_dir is not None:
+        shutil.rmtree(temp_dir)
+
+
+def initialize_virtualenv(
+    env: UvToolboxEnvironment,
+    settings: UvToolboxSettings,
+    *,
+    clear: bool = False,
+) -> None:
+    """Create and set up the virtual environment for the given environment.
+
+    Args:
+        env: The UV toolbox environment to initialize.
+        settings: The UV toolbox settings.
+        clear: If True, clear and recreate the virtual environment.
+    """
+    venv_path = env.venv_path(settings=settings)
+
+    # Only create venv if it doesn't exist or clear is True
+    if not venv_path.exists() or clear:
+        create_virtualenv(env=env, settings=settings, clear=True)
+
+    install_requirements(env=env, settings=settings)

uv_toolbox-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,12 @@
+uv_toolbox/__init__.py,sha256=JIdAYwocL_YJlow7ikHY1lbKDUr7tC1b4BHwtL4R60s,82
+uv_toolbox/cli.py,sha256=lZX-1d4zSlK8bwdMub8vU4O8MhdC0NeqK4xthK9nPpc,4738
+uv_toolbox/errors.py,sha256=SKB3sqOvskBQPhXVXCuGk2WppbaOIMroCBl7_oSZlKI,3466
+uv_toolbox/process.py,sha256=hsI7rRTcZtd8-EHbNDYBPTU6vwBlkGP70mvwnptYBZA,2308
+uv_toolbox/settings.py,sha256=ojVjKheINGFztSeCGWzVKMt5wI1Oz5gEUpUvVlM8lTc,15001
+uv_toolbox/shims.py,sha256=qrYtbquTcJkpTS3JyWJnK6er553UZ7GK2psr_uVgfWc,5517
+uv_toolbox/utils.py,sha256=fdgcSl0jwQmfGBiZaACamcqV3Lkvgt_LllHIP-UEVz0,756
+uv_toolbox/uv_helpers.py,sha256=eCYiN7MGSmRR1K6SKBtCKHAXV15SLuqQYFc1xeMhTrU,2685
+uv_toolbox-0.1.0.dist-info/WHEEL,sha256=e_m4S054HL0hyR3CpOk-b7Q7fDX6BuFkgL5OjAExXas,80
+uv_toolbox-0.1.0.dist-info/entry_points.txt,sha256=WftDfbKQ8qq2Y92Q7GT3gcZBr9IWcGdSMH-A0-YZE7c,79
+uv_toolbox-0.1.0.dist-info/METADATA,sha256=ktmoutjVBKUecMe8ez9DelrDjwlOaK_AqpPL20zXloM,4240
+uv_toolbox-0.1.0.dist-info/RECORD,,

uv_toolbox-0.1.0.dist-info/WHEEL

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

uv_toolbox-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+uv-toolbox = uv_toolbox.cli:main
+uvtb = uv_toolbox.cli:main
+