pyrig 2.2.6__py3-none-any.whl

pyrig/dev/configs/pyproject.py

@@ -0,0 +1,436 @@
+"""Configuration management for pyproject.toml.
+
+This module provides the PyprojectConfigFile class for managing the
+project's pyproject.toml file. It handles project metadata, dependencies,
+tool configurations (ruff, mypy, pytest, bandit), and build settings.
+
+The configuration enforces pyrig's opinionated defaults:
+    - All ruff rules enabled (with minimal exceptions)
+    - Strict mypy type checking
+    - Bandit security scanning
+    - uv as the build backend
+"""
+
+import re
+from functools import cache
+from pathlib import Path
+from subprocess import CompletedProcess  # nosec: B404
+from typing import Any, Literal
+
+import requests
+from packaging.version import Version
+
+from pyrig.dev.cli.commands.init_project import STANDARD_DEV_DEPS
+from pyrig.dev.configs.base.base import TomlConfigFile
+from pyrig.dev.utils.resources import return_resource_content_on_fetch_error
+from pyrig.dev.utils.versions import VersionConstraint, adjust_version_to_level
+from pyrig.src.git.git import get_repo_owner_and_name_from_git
+from pyrig.src.modules.package import (
+    get_pkg_name_from_cwd,
+    get_pkg_name_from_project_name,
+    get_project_name_from_cwd,
+)
+from pyrig.src.os.os import run_subprocess
+from pyrig.src.testing.convention import (
+    COVERAGE_THRESHOLD,
+    TESTS_PACKAGE_NAME,
+)
+
+
+class PyprojectConfigFile(TomlConfigFile):
+    """Configuration file manager for pyproject.toml.
+
+    Manages the central project configuration including:
+        - Project metadata (name, description, dependencies)
+        - Build system configuration (uv)
+        - Tool configurations (ruff, mypy, pytest, bandit)
+        - CLI entry points
+
+    The class provides utilities for querying project information
+    and managing dependencies.
+    """
+
+    @classmethod
+    def dump(cls, config: dict[str, Any] | list[Any]) -> None:
+        """Write configuration to pyproject.toml.
+
+        Normalizes dependencies before writing.
+
+        Args:
+            config: The configuration dict to write.
+
+        Raises:
+            TypeError: If config is not a dict.
+        """
+        if not isinstance(config, dict):
+            msg = f"Cannot dump {config} to pyproject.toml file."
+            raise TypeError(msg)
+        # remove the versions from the dependencies
+        cls.remove_wrong_dependencies(config)
+        super().dump(config)
+
+    @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 pyproject.toml configuration.
+
+        Returns:
+            Complete configuration dict with project metadata,
+            dependencies, build system, and tool configurations.
+        """
+        from pyrig.dev.cli import (  # noqa: PLC0415
+            cli,
+        )
+
+        repo_owner, _ = get_repo_owner_and_name_from_git(check_repo_url=False)
+
+        return {
+            "project": {
+                "name": get_project_name_from_cwd(),
+                "version": cls.get_project_version(),
+                "description": cls.get_project_description(),
+                "readme": "README.md",
+                "authors": [
+                    {"name": repo_owner},
+                ],
+                "license-files": ["LICENSE"],
+                "requires-python": cls.get_project_requires_python(),
+                "classifiers": [
+                    *cls.make_python_version_classifiers(),
+                ],
+                "scripts": {
+                    cls.get_project_name(): f"{cli.__name__}:{cli.main.__name__}"
+                },
+                "dependencies": cls.make_dependency_versions(cls.get_dependencies()),
+            },
+            "dependency-groups": {
+                "dev": cls.make_dependency_versions(
+                    cls.get_dev_dependencies(),
+                    additional=cls.get_standard_dev_dependencies(),
+                )
+            },
+            "build-system": {
+                "requires": ["uv_build"],
+                "build-backend": "uv_build",
+            },
+            "tool": {
+                "uv": {
+                    "build-backend": {
+                        "module-name": get_pkg_name_from_cwd(),
+                        "module-root": "",
+                    }
+                },
+                "ruff": {
+                    "exclude": [".*", "**/migrations/*.py"],
+                    "lint": {
+                        "select": ["ALL"],
+                        "ignore": ["D203", "D213", "COM812", "ANN401"],
+                        "fixable": ["ALL"],
+                        "per-file-ignores": {
+                            f"**/{TESTS_PACKAGE_NAME}/**/*.py": ["S101"],
+                        },
+                        "pydocstyle": {"convention": "google"},
+                    },
+                },
+                "mypy": {
+                    "strict": True,
+                    "warn_unreachable": True,
+                    "show_error_codes": True,
+                    "files": ".",
+                },
+                "pytest": {
+                    "ini_options": {
+                        "testpaths": [TESTS_PACKAGE_NAME],
+                        "addopts": f"--cov={cls.get_package_name()} --cov-report=term-missing --cov-fail-under={COVERAGE_THRESHOLD}",  # noqa: E501
+                    }
+                },
+                "bandit": {
+                    "exclude_dirs": [
+                        ".*",
+                    ],
+                    "assert_used": {
+                        "skips": [
+                            f"*/{TESTS_PACKAGE_NAME}/*.py",
+                        ],
+                    },
+                },
+            },
+        }
+
+    @classmethod
+    def remove_wrong_dependencies(cls, config: dict[str, Any]) -> None:
+        """Normalize dependencies by removing version specifiers.
+
+        Args:
+            config: The configuration dict to modify in place.
+        """
+        # removes the versions from the dependencies
+        config["project"]["dependencies"] = cls.make_dependency_versions(
+            config["project"]["dependencies"]
+        )
+        config["dependency-groups"]["dev"] = cls.make_dependency_versions(
+            config["dependency-groups"]["dev"]
+        )
+
+    @classmethod
+    def get_project_description(cls) -> str:
+        """Get the project description from pyproject.toml.
+
+        Returns:
+            The project description or empty string.
+        """
+        return str(cls.load().get("project", {}).get("description", ""))
+
+    @classmethod
+    def get_project_version(cls) -> str:
+        """Get the project version from pyproject.toml.
+
+        Returns:
+            The project version or empty string.
+        """
+        return str(cls.load().get("project", {}).get("version", ""))
+
+    @classmethod
+    def make_python_version_classifiers(cls) -> list[str]:
+        """Make the Python version classifiers.
+
+        Returns:
+            List of Python version classifiers.
+        """
+        versions = cls.get_supported_python_versions()
+        return [
+            f"Programming Language :: Python :: {v.major}.{v.minor}" for v in versions
+        ]
+
+    @classmethod
+    def get_project_requires_python(cls, default: str = ">=3.12") -> str:
+        """Get the project's requires-python from pyproject.toml.
+
+        Returns:
+            The project's requires-python or empty string.
+        """
+        return str(cls.load().get("project", {}).get("requires-python", default))
+
+    @classmethod
+    def make_dependency_versions(
+        cls,
+        dependencies: list[str],
+        additional: list[str] | None = None,
+    ) -> list[str]:
+        """Normalize and merge dependency lists.
+
+        Args:
+            dependencies: Primary dependencies to process.
+            additional: Additional dependencies to merge.
+
+        Returns:
+            Sorted, deduplicated list of normalized dependencies.
+        """
+        if additional is None:
+            additional = []
+        # remove all versions from the dependencies to compare them
+        stripped_dependencies = {
+            cls.remove_version_from_dep(dep) for dep in dependencies
+        }
+        additional = [
+            dep
+            for dep in additional
+            if cls.remove_version_from_dep(dep) not in stripped_dependencies
+        ]
+        dependencies.extend(additional)
+        return sorted(set(dependencies))
+
+    @classmethod
+    def remove_version_from_dep(cls, dep: str) -> str:
+        """Strip version specifier from a dependency string.
+
+        Args:
+            dep: Dependency string like "requests>=2.0".
+
+        Returns:
+            Package name without version (e.g., "requests").
+        """
+        return re.split(r"[^a-zA-Z0-9_.-]", dep)[0]
+
+    @classmethod
+    def get_package_name(cls) -> str:
+        """Get the Python package name (with underscores).
+
+        Returns:
+            The package name derived from the project name.
+        """
+        project_name = cls.get_project_name()
+        return get_pkg_name_from_project_name(project_name)
+
+    @classmethod
+    def get_project_name(cls) -> str:
+        """Get the project name from pyproject.toml.
+
+        Returns:
+            The project name or empty string.
+        """
+        return str(cls.load().get("project", {}).get("name", ""))
+
+    @classmethod
+    def get_all_dependencies(cls) -> list[str]:
+        """Get all dependencies (runtime and dev).
+
+        Returns:
+            Combined list of all dependencies.
+        """
+        all_deps = cls.get_dependencies()
+        all_deps.extend(cls.get_dev_dependencies())
+        return all_deps
+
+    @classmethod
+    def get_standard_dev_dependencies(cls) -> list[str]:
+        """Get pyrig's standard development dependencies.
+
+        Returns:
+            Sorted list of standard dev dependencies.
+        """
+        # sort the dependencies
+        return sorted(STANDARD_DEV_DEPS)
+
+    @classmethod
+    def get_dev_dependencies(cls) -> list[str]:
+        """Get development dependencies from pyproject.toml.
+
+        Returns:
+            List of dev dependencies.
+        """
+        dev_deps: list[str] = cls.load().get("dependency-groups", {}).get("dev", [])
+        return dev_deps
+
+    @classmethod
+    def get_dependencies(cls) -> list[str]:
+        """Get runtime dependencies from pyproject.toml.
+
+        Returns:
+            List of runtime dependencies.
+        """
+        deps: list[str] = cls.load().get("project", {}).get("dependencies", [])
+        return deps
+
+    @classmethod
+    @return_resource_content_on_fetch_error(resource_name="LATEST_PYTHON_VERSION")
+    @cache
+    def fetch_latest_python_version(cls) -> str:
+        """Fetch the latest stable Python version from endoflife.date.
+
+        Returns:
+            The latest stable Python version.
+
+        Raises:
+            requests.HTTPError: If the API request fails.
+        """
+        url = "https://endoflife.date/api/python.json"
+        resp = requests.get(url, timeout=10)
+        resp.raise_for_status()
+        data: list[dict[str, str]] = resp.json()
+        # first element has metadata for latest stable
+        return data[0]["latest"]
+
+    @classmethod
+    def get_latest_python_version(
+        cls, level: Literal["major", "minor", "micro"] = "minor"
+    ) -> Version:
+        """Fetch the latest stable Python version from endoflife.date.
+
+        Returns:
+            The latest stable Python version as a string.
+
+        Raises:
+            requests.HTTPError: If the API request fails.
+        """
+        latest_version = Version(cls.fetch_latest_python_version())
+        return adjust_version_to_level(latest_version, level)
+
+    @classmethod
+    def get_latest_possible_python_version(
+        cls, level: Literal["major", "minor", "micro"] = "micro"
+    ) -> Version:
+        """Get the latest Python version allowed by requires-python.
+
+        Args:
+            level: Version precision (major, minor, or micro).
+
+        Returns:
+            The latest allowed Python version.
+        """
+        constraint = cls.load()["project"]["requires-python"]
+        version_constraint = VersionConstraint(constraint)
+        version = version_constraint.get_upper_inclusive()
+        if version is None:
+            version = cls.get_latest_python_version()
+
+        return adjust_version_to_level(version, level)
+
+    @classmethod
+    def get_first_supported_python_version(cls) -> Version:
+        """Get the minimum supported Python version.
+
+        Returns:
+            The minimum Python version from requires-python.
+
+        Raises:
+            ValueError: If no lower bound is specified.
+        """
+        constraint = cls.get_project_requires_python()
+        version_constraint = VersionConstraint(constraint)
+        lower = version_constraint.get_lower_inclusive()
+        if lower is None:
+            msg = "Need a lower bound for python version"
+            raise ValueError(msg)
+        return lower
+
+    @classmethod
+    def get_supported_python_versions(cls) -> list[Version]:
+        """Get all supported Python minor versions.
+
+        Returns:
+            List of supported Python versions (e.g., [3.10, 3.11, 3.12]).
+        """
+        constraint = cls.get_project_requires_python()
+        version_constraint = VersionConstraint(constraint)
+        return version_constraint.get_version_range(
+            level="minor", upper_default=cls.get_latest_python_version()
+        )
+
+    @classmethod
+    def update_dependencies(cls, *, check: bool = True) -> CompletedProcess[bytes]:
+        """Update dependencies to their latest versions.
+
+        Args:
+            check: Whether to raise on non-zero exit code.
+
+        Returns:
+            The completed process result.
+        """
+        from pyrig.src.project.mgt import PROJECT_MGT  # noqa: PLC0415
+
+        upgrade_deps = run_subprocess([PROJECT_MGT, "lock", "--upgrade"], check=check)
+        _ = cls.install_dependencies(check=check)
+        return upgrade_deps
+
+    @classmethod
+    def install_dependencies(cls, *, check: bool = True) -> CompletedProcess[bytes]:
+        """Install project dependencies using uv sync.
+
+        Args:
+            check: Whether to raise on non-zero exit code.
+
+        Returns:
+            The completed process result.
+        """
+        from pyrig.src.project.mgt import PROJECT_MGT  # noqa: PLC0415
+
+        return run_subprocess([PROJECT_MGT, "sync"], check=check)

pyrig/dev/configs/python/__init__.py

@@ -0,0 +1,5 @@
+"""Python source file configuration management.
+
+This package provides ConfigFile subclasses for creating and managing
+Python source files like __init__.py, main.py, and subcommands.py.
+"""

pyrig/dev/configs/python/builders_init.py

@@ -0,0 +1,27 @@
+"""Configuration for the builders package __init__.py.
+
+This module provides the BuildersInitConfigFile class for creating
+the dev/artifacts/builders directory structure with an __init__.py file.
+"""
+
+from types import ModuleType
+
+from pyrig.dev import builders
+from pyrig.dev.configs.base.base import InitConfigFile
+
+
+class BuildersInitConfigFile(InitConfigFile):
+    """Configuration file manager for builders/__init__.py.
+
+    Creates the dev/artifacts/builders directory with an __init__.py
+    file that mirrors pyrig's builders package structure.
+    """
+
+    @classmethod
+    def get_src_module(cls) -> ModuleType:
+        """Get the source module to mirror.
+
+        Returns:
+            The pyrig.dev.builders module.
+        """
+        return builders

pyrig/dev/configs/python/configs_init.py

@@ -0,0 +1,28 @@
+"""Configuration for the configs package __init__.py.
+
+This module provides the ConfigsInitConfigFile class for creating
+the dev/configs directory structure with an __init__.py file.
+All ConfigFile subclasses in this package are automatically discovered.
+"""
+
+from types import ModuleType
+
+from pyrig.dev import configs
+from pyrig.dev.configs.base.base import InitConfigFile
+
+
+class ConfigsInitConfigFile(InitConfigFile):
+    """Configuration file manager for configs/__init__.py.
+
+    Creates the dev/configs directory with an __init__.py file
+    that mirrors pyrig's configs package structure.
+    """
+
+    @classmethod
+    def get_src_module(cls) -> ModuleType:
+        """Get the source module to mirror.
+
+        Returns:
+            The pyrig.dev.configs module.
+        """
+        return configs

pyrig/dev/configs/python/dot_experiment.py

@@ -0,0 +1,46 @@
+"""Configuration for the .experiment.py scratch file.
+
+This module provides the DotExperimentConfigFile class for creating
+a .experiment.py file at the project root for local experimentation.
+This file is automatically added to .gitignore.
+"""
+
+from pathlib import Path
+
+from pyrig.dev.configs.base.base import PythonConfigFile
+
+
+class DotExperimentConfigFile(PythonConfigFile):
+    """Configuration file manager for .experiment.py.
+
+    Creates a scratch Python file at the project root for local
+    experimentation. This file is excluded from version control.
+    """
+
+    @classmethod
+    def get_filename(cls) -> str:
+        """Get the experiment filename.
+
+        Returns:
+            The string ".experiment".
+        """
+        return ".experiment"
+
+    @classmethod
+    def get_parent_path(cls) -> Path:
+        """Get the project root directory.
+
+        Returns:
+            Path to the project root.
+        """
+        return Path()
+
+    @classmethod
+    def get_content_str(cls) -> str:
+        """Get the experiment file content.
+
+        Returns:
+            A minimal Python file with a docstring.
+        """
+        return '''"""This file is for experimentation and is ignored by git."""
+'''

pyrig/dev/configs/python/main.py

@@ -0,0 +1,59 @@
+"""Configuration for the main.py entry point.
+
+This module provides the MainConfigFile class for creating the
+main.py file in the package's src directory. This file serves
+as the CLI entry point.
+"""
+
+from pathlib import Path
+from types import ModuleType
+
+from pyrig import main
+from pyrig.dev.configs.base.base import CopyModuleConfigFile
+
+
+class MainConfigFile(CopyModuleConfigFile):
+    """Configuration file manager for main.py.
+
+    Creates a main.py in pkg_name/src that serves as the CLI entry point.
+    Also cleans up any root-level main.py files.
+    """
+
+    def __init__(self) -> None:
+        """Initialize and clean up any root-level main.py."""
+        super().__init__()
+        self.__class__.delete_root_main()
+
+    @classmethod
+    def get_src_module(cls) -> ModuleType:
+        """Get the source module to copy.
+
+        Returns:
+            The pyrig.main module.
+        """
+        return main
+
+    @classmethod
+    def is_correct(cls) -> bool:
+        """Check if the main.py file is valid.
+
+        Allows modifications as long as the file contains a main function
+        and the standard __name__ == '__main__' guard.
+
+        Returns:
+            True if the file has required structure.
+        """
+        return super().is_correct() or (
+            "def main" in cls.get_file_content()
+            and 'if __name__ == "__main__":' in cls.get_file_content()
+        )
+
+    @classmethod
+    def delete_root_main(cls) -> None:
+        """Delete any root-level main.py file.
+
+        Cleans up legacy main.py files that should be in src/.
+        """
+        root_main_path = Path("main.py")
+        if root_main_path.exists():
+            root_main_path.unlink()

pyrig/dev/configs/python/resources_init.py

@@ -0,0 +1,27 @@
+"""Configuration for the resources package __init__.py.
+
+This module provides the ResourcesInitConfigFile class for creating
+the dev/artifacts/resources directory structure with an __init__.py file.
+"""
+
+from types import ModuleType
+
+from pyrig import resources
+from pyrig.dev.configs.base.base import InitConfigFile
+
+
+class ResourcesInitConfigFile(InitConfigFile):
+    """Configuration file manager for resources/__init__.py.
+
+    Creates the dev/artifacts/resources directory with an __init__.py
+    file that mirrors pyrig's resources package structure.
+    """
+
+    @classmethod
+    def get_src_module(cls) -> ModuleType:
+        """Get the source module to mirror.
+
+        Returns:
+            The pyrig.dev.artifacts.resources module.
+        """
+        return resources

pyrig/dev/configs/python/shared_subcommands.py

@@ -0,0 +1,29 @@
+"""Shared subcommands ConfigFile.
+
+This module provides the SharedSubcommandsConfigFile class for creating
+a shared_subcommands.py file where users can define custom CLI subcommands
+that are available in all pyrig projects.
+"""
+
+from types import ModuleType
+
+from pyrig.dev.cli import shared_subcommands
+from pyrig.dev.configs.base.base import CopyModuleOnlyDocstringConfigFile
+
+
+class SharedSubcommandsConfigFile(CopyModuleOnlyDocstringConfigFile):
+    """Configuration file manager for shared_subcommands.py.
+
+    Creates a shared_subcommands.py file with only the docstring from pyrig's
+    shared_subcommands module, allowing users to add custom CLI subcommands
+    that are available in all pyrig projects.
+    """
+
+    @classmethod
+    def get_src_module(cls) -> ModuleType:
+        """Get the source module to copy docstring from.
+
+        Returns:
+            The pyrig.dev.cli.shared_subcommands module.
+        """
+        return shared_subcommands

pyrig/dev/configs/python/src_init.py

@@ -0,0 +1,27 @@
+"""Configuration for the src package __init__.py.
+
+This module provides the SrcInitConfigFile class for creating
+the src directory structure with an __init__.py file.
+"""
+
+from types import ModuleType
+
+from pyrig import src
+from pyrig.dev.configs.base.base import InitConfigFile
+
+
+class SrcInitConfigFile(InitConfigFile):
+    """Configuration file manager for src/__init__.py.
+
+    Creates the src directory with an __init__.py file that
+    mirrors pyrig's src package structure.
+    """
+
+    @classmethod
+    def get_src_module(cls) -> ModuleType:
+        """Get the source module to mirror.
+
+        Returns:
+            The pyrig.src module.
+        """
+        return src