pyrig 2.2.6__py3-none-any.whl

pyrig/dev/configs/containers/__init__.py

@@ -0,0 +1 @@
+"""__init__ module."""

pyrig/dev/configs/containers/container_file.py

@@ -0,0 +1,111 @@
+"""Configuration management for Containerfile files.
+
+This module provides the ContainerfileConfigFile class for managing the
+project's Containerfile file. It fetches GitHub's standard Python gitignore
+and adds pyrig-specific patterns.
+"""
+
+import json
+from pathlib import Path
+
+from pyrig.dev.configs.base.base import TextConfigFile
+from pyrig.dev.configs.pyproject import PyprojectConfigFile
+from pyrig.main import main
+from pyrig.src.project.mgt import PROJECT_MGT_RUN_ARGS
+
+
+class ContainerfileConfigFile(TextConfigFile):
+    """Configuration file manager for Containerfile.
+
+    Creates a Containerfile file in the project root. It is based on the
+    GitHub Containerfile template.
+    """
+
+    @classmethod
+    def get_filename(cls) -> str:
+        """Get the Containerfile filename.
+
+        Returns:
+            The string "Containerfile".
+        """
+        return "Containerfile"
+
+    @classmethod
+    def get_parent_path(cls) -> Path:
+        """Get the project root directory.
+
+        Returns:
+            Path to the project root.
+        """
+        return Path()
+
+    @classmethod
+    def get_file_extension(cls) -> str:
+        """Get the Containerfile file extension.
+
+        Returns:
+            The string "Containerfile".
+        """
+        return ""
+
+    @classmethod
+    def get_extension_sep(cls) -> str:
+        """Get the Containerfile extension separator.
+
+        Returns:
+            The string "".
+        """
+        return ""
+
+    @classmethod
+    def get_content_str(cls) -> str:
+        """Get the Containerfile content.
+
+        Builds a standard working Containerfile from scratch.
+
+        Returns:
+            The Containerfile content.
+        """
+        return "\n\n".join(cls.get_layers())
+
+    @classmethod
+    def is_correct(cls) -> bool:
+        """Check if the Containerfile is valid.
+
+        Returns:
+            True if each step in the Containerfile is present.
+        """
+        all_layers_in_file = all(
+            layer in cls.get_file_content() for layer in cls.get_layers()
+        )
+        return super().is_correct() or all_layers_in_file
+
+    @classmethod
+    def get_layers(cls) -> list[str]:
+        """Get the layers of the Containerfile.
+
+        Returns:
+            List of strings with each layer.
+        """
+        latest_python_version = PyprojectConfigFile.get_latest_possible_python_version()
+        project_name = PyprojectConfigFile.get_project_name()
+        package_name = PyprojectConfigFile.get_package_name()
+        app_user_name = "appuser"
+        entrypoint_args = [*PROJECT_MGT_RUN_ARGS, package_name]
+        default_cmd_args = [main.__name__]
+        return [
+            f"FROM python:{latest_python_version}-slim",
+            f"WORKDIR /{project_name}",
+            "COPY --from=ghcr.io/astral-sh/uv:latest /uv /usr/local/bin/uv",
+            "COPY README.md LICENSE pyproject.toml uv.lock ./",
+            f"RUN useradd -m -u 1000 {app_user_name}",
+            f"RUN chown -R {app_user_name}:{app_user_name} .",
+            f"USER {app_user_name}",
+            f"COPY --chown=appuser:appuser {package_name} {package_name}",
+            "RUN uv sync --no-group dev",
+            "RUN rm README.md LICENSE pyproject.toml uv.lock",
+            f"ENTRYPOINT {json.dumps(entrypoint_args)}",
+            # if the image is provided a different command, it will run that instead
+            # so adding a default is convenient without restricting usage
+            f"CMD {json.dumps(default_cmd_args)}",
+        ]

pyrig/dev/configs/dot_env.py

@@ -0,0 +1,95 @@
+"""Configuration management for .env environment files.
+
+This module provides the DotEnvConfigFile class for managing .env files
+in pyrig projects. The .env file is used for local environment variables
+and is not committed to version control.
+"""
+
+from pathlib import Path
+from typing import Any
+
+from dotenv import dotenv_values
+
+from pyrig.dev.configs.base.base import ConfigFile
+
+
+class DotEnvConfigFile(ConfigFile):
+    """Configuration file manager for .env environment files.
+
+    Creates an empty .env file if it doesn't exist. The file is used
+    for local environment variables and should not be committed to
+    version control (it's included in .gitignore by default).
+
+    Note:
+        This config file is read-only from pyrig's perspective.
+        Users manage the content manually.
+    """
+
+    @classmethod
+    def load(cls) -> dict[str, str | None]:
+        """Load environment variables from the .env file.
+
+        Returns:
+            Dict mapping variable names to their values.
+        """
+        return dotenv_values(cls.get_path())
+
+    @classmethod
+    def dump(cls, config: dict[str, Any] | list[Any]) -> None:
+        """Prevent writing to .env files.
+
+        Args:
+            config: Must be empty.
+
+        Raises:
+            ValueError: If config is not empty.
+        """
+        # is not supposed to be dumped to, so just raise error
+        if config:
+            msg = f"Cannot dump {config} to .env file."
+            raise ValueError(msg)
+
+    @classmethod
+    def get_file_extension(cls) -> str:
+        """Get the env file extension.
+
+        Returns:
+            The string "env".
+        """
+        return "env"
+
+    @classmethod
+    def get_filename(cls) -> str:
+        """Get an empty filename to produce ".env".
+
+        Returns:
+            Empty string so the path becomes ".env".
+        """
+        return ""  # so it builds the path .env and not env.env
+
+    @classmethod
+    def get_parent_path(cls) -> Path:
+        """Get the project root directory.
+
+        Returns:
+            Path to the project root.
+        """
+        return Path()
+
+    @classmethod
+    def get_configs(cls) -> dict[str, Any]:
+        """Get the expected configuration (empty).
+
+        Returns:
+            An empty dict.
+        """
+        return {}
+
+    @classmethod
+    def is_correct(cls) -> bool:
+        """Check if the .env file exists.
+
+        Returns:
+            True if the file exists or parent validation passes.
+        """
+        return super().is_correct() or cls.get_path().exists()

pyrig/dev/configs/dot_python_version.py

@@ -0,0 +1,88 @@
+"""Configuration management for .python-version files.
+
+This module provides the DotPythonVersionConfigFile class for managing
+the .python-version file used by pyenv and other Python version managers.
+"""
+
+from pathlib import Path
+from typing import Any
+
+from pyrig.dev.configs.base.base import ConfigFile
+from pyrig.dev.configs.pyproject import PyprojectConfigFile
+
+
+class DotPythonVersionConfigFile(ConfigFile):
+    """Configuration file manager for .python-version.
+
+    Creates and maintains the .python-version file used by pyenv and
+    similar tools to specify the Python version for the project.
+
+    Attributes:
+        VERSION_KEY: Dictionary key for the version string.
+    """
+
+    VERSION_KEY = "version"
+
+    @classmethod
+    def get_filename(cls) -> str:
+        """Get an empty filename to produce ".python-version".
+
+        Returns:
+            Empty string so the path becomes ".python-version".
+        """
+        return ""  # so it builds the path .python-version
+
+    @classmethod
+    def get_file_extension(cls) -> str:
+        """Get the python-version file extension.
+
+        Returns:
+            The string "python-version".
+        """
+        return "python-version"
+
+    @classmethod
+    def get_parent_path(cls) -> Path:
+        """Get the project root directory.
+
+        Returns:
+            Path to the project root.
+        """
+        return Path()
+
+    @classmethod
+    def get_configs(cls) -> dict[str, Any]:
+        """Get the expected Python version from pyproject.toml.
+
+        Returns:
+            Dict with the first supported Python version.
+        """
+        return {
+            cls.VERSION_KEY: str(
+                PyprojectConfigFile.get_first_supported_python_version()
+            )
+        }
+
+    @classmethod
+    def load(cls) -> dict[str, Any]:
+        """Load the Python version from the file.
+
+        Returns:
+            Dict with the version string.
+        """
+        return {cls.VERSION_KEY: cls.get_path().read_text(encoding="utf-8")}
+
+    @classmethod
+    def dump(cls, config: dict[str, Any] | list[Any]) -> None:
+        """Write the Python version to the file.
+
+        Args:
+            config: Dict containing the version under VERSION_KEY.
+
+        Raises:
+            TypeError: If config is not a dict.
+        """
+        if not isinstance(config, dict):
+            msg = f"Cannot dump {config} to .python-version file."
+            raise TypeError(msg)
+        cls.get_path().write_text(config[cls.VERSION_KEY], encoding="utf-8")

pyrig/dev/configs/git/__init__.py

@@ -0,0 +1,5 @@
+"""Git-related configuration file management.
+
+This package provides ConfigFile subclasses for managing .gitignore
+and .pre-commit-config.yaml files.
+"""

pyrig/dev/configs/git/gitignore.py

@@ -0,0 +1,181 @@
+"""Configuration management for .gitignore files.
+
+This module provides the GitIgnoreConfigFile class for managing the
+project's .gitignore file. It fetches GitHub's standard Python gitignore
+and adds pyrig-specific patterns.
+"""
+
+import os
+from pathlib import Path
+from typing import Any
+
+import pathspec
+import requests
+
+import pyrig
+from pyrig.dev.configs.base.base import ConfigFile
+from pyrig.dev.configs.dot_env import DotEnvConfigFile
+from pyrig.dev.configs.python.dot_experiment import DotExperimentConfigFile
+from pyrig.dev.utils.resources import return_resource_content_on_fetch_error
+
+
+class GitIgnoreConfigFile(ConfigFile):
+    """Configuration file manager for .gitignore.
+
+    Creates a comprehensive .gitignore file by combining:
+        - GitHub's standard Python.gitignore
+        - VS Code workspace files
+        - pyrig-specific patterns
+        - Common cache directories
+    """
+
+    @classmethod
+    def get_filename(cls) -> str:
+        """Get an empty filename to produce ".gitignore".
+
+        Returns:
+            Empty string so the path becomes ".gitignore".
+        """
+        return ""  # so it builds the path .gitignore and not gitignore.gitignore
+
+    @classmethod
+    def get_parent_path(cls) -> Path:
+        """Get the project root directory.
+
+        Returns:
+            Path to the project root.
+        """
+        return Path()
+
+    @classmethod
+    def get_file_extension(cls) -> str:
+        """Get the gitignore file extension.
+
+        Returns:
+            The string "gitignore".
+        """
+        return "gitignore"
+
+    @classmethod
+    def load(cls) -> list[str]:
+        """Load the .gitignore file as a list of patterns.
+
+        Returns:
+            List of gitignore patterns, one per line.
+        """
+        return cls.get_path().read_text(encoding="utf-8").splitlines()
+
+    @classmethod
+    def dump(cls, config: list[str] | dict[str, Any]) -> None:
+        """Write patterns to the .gitignore file.
+
+        Args:
+            config: List of gitignore patterns.
+
+        Raises:
+            TypeError: If config is not a list.
+        """
+        if not isinstance(config, list):
+            msg = f"Cannot dump {config} to .gitignore file."
+            raise TypeError(msg)
+        cls.get_path().write_text("\n".join(config), encoding="utf-8")
+
+    @classmethod
+    def get_configs(cls) -> list[str]:
+        """Get the expected .gitignore patterns.
+
+        Combines GitHub's Python gitignore with pyrig-specific patterns.
+
+        Returns:
+            List of gitignore patterns.
+        """
+        # fetch the standard github gitignore via https://github.com/github/gitignore/blob/main/Python.gitignore
+        needed = [
+            *cls.get_github_python_gitignore_as_list(),
+            "# vscode stuff",
+            ".vscode/",
+            "",
+            f"# {pyrig.__name__} stuff",
+            ".git/",
+            DotExperimentConfigFile.get_path().as_posix(),
+            "# others",
+            DotEnvConfigFile.get_path().as_posix(),
+            ".coverage",
+            "coverage.xml",
+            ".mypy_cache/",
+            ".pytest_cache/",
+            ".ruff_cache/",
+            ".venv/",
+            "dist/",
+        ]
+
+        dotenv_path = DotEnvConfigFile.get_path().as_posix()
+        if dotenv_path not in needed:
+            needed.extend(["# for secrets used locally", dotenv_path])
+
+        existing = cls.load()
+        needed = [p for p in needed if p not in set(existing)]
+        return existing + needed
+
+    @classmethod
+    @return_resource_content_on_fetch_error(resource_name="GITIGNORE")
+    def get_github_python_gitignore_as_str(cls) -> str:
+        """Fetch GitHub's standard Python gitignore patterns.
+
+        Returns:
+            String of patterns from GitHub's Python.gitignore.
+
+        Raises:
+            RuntimeError: If fetch fails and no .gitignore exists.
+        """
+        url = "https://raw.githubusercontent.com/github/gitignore/main/Python.gitignore"
+        res = requests.get(url, timeout=10)
+        res.raise_for_status()
+        return res.text
+
+    @classmethod
+    def get_github_python_gitignore_as_list(cls) -> list[str]:
+        """Fetch GitHub's standard Python gitignore patterns.
+
+        Returns:
+            List of patterns from GitHub's Python.gitignore.
+
+        Raises:
+            RuntimeError: If fetch fails and no .gitignore exists.
+        """
+        gitignore_str = cls.get_github_python_gitignore_as_str()
+        return gitignore_str.splitlines()
+
+    @classmethod
+    def path_is_in_gitignore(cls, relative_path: str | Path) -> bool:
+        """Check if a path matches any pattern in .gitignore.
+
+        Args:
+            relative_path: Path to check, relative to repository root.
+
+        Returns:
+            True if the path matches any gitignore pattern.
+        """
+        gitignore_path = cls.get_path()
+        if not gitignore_path.exists():
+            return False
+        as_path = Path(relative_path)
+        if as_path.is_absolute():
+            as_path = as_path.relative_to(Path.cwd())
+        is_dir = (
+            bool(as_path.suffix == "")
+            or as_path.is_dir()
+            or str(as_path).endswith(os.sep)
+        )
+        is_dir = is_dir and not as_path.is_file()
+
+        as_posix = as_path.as_posix()
+        if is_dir and not as_posix.endswith("/"):
+            as_posix += "/"
+
+        spec = pathspec.PathSpec.from_lines(
+            "gitwildmatch",
+            cls.load(),
+        )
+
+        return spec.match_file(as_posix)

pyrig/dev/configs/git/pre_commit.py

@@ -0,0 +1,170 @@
+"""Configuration management for pre-commit hooks.
+
+This module provides the PreCommitConfigConfigFile class for managing
+the .pre-commit-config.yaml file. It configures local hooks for linting,
+formatting, type checking, and security scanning.
+"""
+
+import logging
+from pathlib import Path
+from subprocess import CompletedProcess  # nosec: B404
+from typing import Any
+
+from pyrig.dev.configs.base.base import YamlConfigFile
+from pyrig.src.git.git import git_add_file
+from pyrig.src.os.os import run_subprocess
+from pyrig.src.project.mgt import (
+    PROJECT_MGT_RUN_ARGS,
+    get_script_from_args,
+)
+
+logger = logging.getLogger(__name__)
+
+
+class PreCommitConfigConfigFile(YamlConfigFile):
+    """Configuration file manager for .pre-commit-config.yaml.
+
+    Configures local pre-commit hooks for:
+        - ruff linting and formatting
+        - mypy type checking
+        - bandit security scanning
+    """
+
+    @classmethod
+    def get_filename(cls) -> str:
+        """Get the pre-commit config filename.
+
+        Returns:
+            The string ".pre-commit-config".
+        """
+        filename = super().get_filename()
+        return f".{filename.replace('_', '-')}"
+
+    @classmethod
+    def get_parent_path(cls) -> Path:
+        """Get the project root directory.
+
+        Returns:
+            Path to the project root.
+        """
+        return Path()
+
+    @classmethod
+    def get_hook(
+        cls,
+        name: str,
+        args: list[str],
+        *,
+        language: str = "system",
+        pass_filenames: bool = False,
+        always_run: bool = True,
+        **kwargs: Any,
+    ) -> dict[str, Any]:
+        """Create a pre-commit hook configuration.
+
+        Args:
+            name: Hook identifier and display name.
+            args: Command arguments for the hook.
+            language: Hook language (default: "system").
+            pass_filenames: Whether to pass filenames to the hook.
+            always_run: Whether to run on every commit.
+            **kwargs: Additional hook configuration options.
+
+        Returns:
+            Hook configuration dict.
+        """
+        hook: dict[str, Any] = {
+            "id": name,
+            "name": name,
+            "entry": get_script_from_args(args),
+            "language": language,
+            "always_run": always_run,
+            "pass_filenames": pass_filenames,
+            **kwargs,
+        }
+        return hook
+
+    @classmethod
+    def get_configs(cls) -> dict[str, Any]:
+        """Get the expected pre-commit configuration.
+
+        Returns:
+            Configuration dict with local hooks for linting,
+            formatting, type checking, and security scanning.
+        """
+        hooks: list[dict[str, Any]] = [
+            cls.get_hook(
+                "lint-code",
+                ["ruff", "check", "--fix"],
+            ),
+            cls.get_hook(
+                "format-code",
+                ["ruff", "format"],
+            ),
+            cls.get_hook(
+                "check-types",
+                ["ty", "check"],
+            ),
+            cls.get_hook(
+                "check-static-types",
+                ["mypy", "--exclude-gitignore"],
+            ),
+            cls.get_hook(
+                "check-security",
+                ["bandit", "-c", "pyproject.toml", "-r", "."],
+            ),
+        ]
+        return {
+            "repos": [
+                {
+                    "repo": "local",
+                    "hooks": hooks,
+                },
+            ]
+        }
+
+    def __init__(self) -> None:
+        """Initialize the pre-commit config file manager."""
+        super().__init__()
+
+    @classmethod
+    def install(cls) -> CompletedProcess[bytes]:
+        """Install pre-commit hooks into the git repository.
+
+        Returns:
+            The completed process result.
+        """
+        logger.info("Running pre-commit install")
+        return run_subprocess([*PROJECT_MGT_RUN_ARGS, "pre-commit", "install"])
+
+    @classmethod
+    def run_hooks(
+        cls,
+        *,
+        with_install: bool = True,
+        all_files: bool = True,
+        add_before_commit: bool = False,
+        verbose: bool = True,
+        check: bool = True,
+    ) -> None:
+        """Run all pre-commit hooks.
+
+        Args:
+            with_install: Whether to install hooks first.
+            all_files: Whether to run on all files.
+            add_before_commit: Whether to git add files first.
+            verbose: Whether to show verbose output.
+            check: Whether to raise on hook failure.
+        """
+        if add_before_commit:
+            logger.info("Adding all files to git")
+            git_add_file(Path())
+        if with_install:
+            cls.install()
+        logger.info("Running pre-commit run")
+        args = ["pre-commit", "run"]
+        if all_files:
+            args.append("--all-files")
+        if verbose:
+            args.append("--verbose")
+        run_subprocess([*args], check=check)