pyrig 2.2.6__py3-none-any.whl

pyrig/dev/configs/workflows/build.py

@@ -0,0 +1,106 @@
+"""GitHub Actions workflow for building artifacts.
+
+This module provides the BuildWorkflow class for creating
+a workflow that builds artifacts across OS matrix after
+successful health checks on main branch.
+"""
+
+from typing import Any
+
+from pyrig.dev.configs.workflows.base.base import Workflow
+from pyrig.dev.configs.workflows.health_check import HealthCheckWorkflow
+
+
+class BuildWorkflow(Workflow):
+    """Workflow for building project artifacts.
+
+    Triggers after health check workflow completes on main branch.
+    Builds artifacts across OS matrix and uploads them for the
+    release workflow to use.
+    """
+
+    @classmethod
+    def get_workflow_triggers(cls) -> dict[str, Any]:
+        """Get the workflow triggers.
+
+        Returns:
+            Trigger for health check completion on main.
+        """
+        triggers = super().get_workflow_triggers()
+        triggers.update(
+            cls.on_workflow_run(
+                workflows=[HealthCheckWorkflow.get_workflow_name()],
+                branches=["main"],
+            )
+        )
+        return triggers
+
+    @classmethod
+    def get_jobs(cls) -> dict[str, Any]:
+        """Get the workflow jobs.
+
+        Returns:
+            Dict with build job.
+        """
+        jobs: dict[str, Any] = {}
+        jobs.update(cls.job_build_artifacts())
+        jobs.update(cls.job_build_container_image())
+        return jobs
+
+    @classmethod
+    def job_build_artifacts(cls) -> dict[str, Any]:
+        """Get the build job that runs across OS matrix.
+
+        Returns:
+            Job configuration for building artifacts.
+        """
+        return cls.get_job(
+            job_func=cls.job_build_artifacts,
+            if_condition=cls.if_workflow_run_is_success(),
+            strategy=cls.strategy_matrix_os(),
+            runs_on=cls.insert_matrix_os(),
+            steps=cls.steps_build_artifacts(),
+        )
+
+    @classmethod
+    def job_build_container_image(cls) -> dict[str, Any]:
+        """Get the build job that builds the container image.
+
+        Returns:
+            Job configuration for building container image.
+        """
+        return cls.get_job(
+            job_func=cls.job_build_container_image,
+            if_condition=cls.if_workflow_run_is_success(),
+            runs_on=cls.UBUNTU_LATEST,
+            steps=cls.steps_build_container_image(),
+        )
+
+    @classmethod
+    def steps_build_artifacts(cls) -> list[dict[str, Any]]:
+        """Get the steps for building artifacts.
+
+        Returns:
+            List of build steps, or placeholder if no builders defined.
+        """
+        return [
+            *cls.steps_core_matrix_setup(),
+            cls.step_build_artifacts(),
+            cls.step_upload_artifacts(),
+        ]
+
+    @classmethod
+    def steps_build_container_image(cls) -> list[dict[str, Any]]:
+        """Get the steps for building the container image.
+
+        Returns:
+            List of build steps.
+        """
+        return [
+            cls.step_checkout_repository(),
+            cls.step_install_container_engine(),
+            cls.step_build_container_image(),
+            cls.step_make_dist_folder(),
+            cls.step_save_container_image(),
+            cls.step_upload_artifacts(name="container-image"),
+        ]

pyrig/dev/configs/workflows/health_check.py

@@ -0,0 +1,133 @@
+"""GitHub Actions workflow for health checks and CI.
+
+This module provides the HealthCheckWorkflow class for creating
+a workflow that runs on pull requests, pushes, and scheduled intervals
+to verify code quality and run tests.
+"""
+
+from datetime import UTC, datetime, timedelta
+from typing import Any
+
+import pyrig
+from pyrig.dev.configs.workflows.base.base import Workflow
+from pyrig.dev.utils.packages import get_src_package
+from pyrig.src.modules.package import DependencyGraph
+
+
+class HealthCheckWorkflow(Workflow):
+    """Workflow for continuous integration health checks.
+
+    Triggers on pull requests, pushes to main, and scheduled intervals.
+    Runs linting, type checking, security scanning, and tests across
+    a matrix of OS and Python versions.
+    """
+
+    BASE_CRON_HOUR = 0
+
+    @classmethod
+    def get_workflow_triggers(cls) -> dict[str, Any]:
+        """Get the workflow triggers.
+
+        Returns:
+            Triggers for pull requests, pushes, and scheduled runs.
+        """
+        triggers = super().get_workflow_triggers()
+        triggers.update(cls.on_pull_request())
+        triggers.update(cls.on_push())
+        triggers.update(cls.on_schedule(cron=cls.get_staggered_cron()))
+        return triggers
+
+    @classmethod
+    def get_staggered_cron(cls) -> str:
+        """Get a staggered cron schedule based on dependency depth.
+
+        Packages with more dependencies run later to avoid conflicts
+        when dependencies release right before dependent packages.
+
+        Returns:
+            Cron expression with hour offset based on dependency depth.
+        """
+        offset = cls.get_dependency_offset()
+        base_time = datetime.now(tz=UTC).replace(
+            hour=cls.BASE_CRON_HOUR, minute=0, second=0, microsecond=0
+        )
+        scheduled_time = base_time + timedelta(hours=offset)
+        return f"0 {scheduled_time.hour} * * *"
+
+    @classmethod
+    def get_dependency_offset(cls) -> int:
+        """Calculate hour offset based on dependency depth to pyrig.
+
+        Returns:
+            Number of hours to offset from base cron hour.
+        """
+        graph = DependencyGraph()
+        src_pkg = get_src_package()
+        return graph.shortest_path_length(src_pkg.__name__, pyrig.__name__)
+
+    @classmethod
+    def get_jobs(cls) -> dict[str, Any]:
+        """Get the workflow jobs.
+
+        Returns:
+            Dict with matrix and aggregation jobs.
+        """
+        jobs: dict[str, Any] = {}
+        jobs.update(cls.job_health_check_matrix())
+        jobs.update(cls.job_health_check())
+        return jobs
+
+    @classmethod
+    def job_health_check_matrix(cls) -> dict[str, Any]:
+        """Get the matrix job that runs across OS and Python versions.
+
+        Returns:
+            Job configuration for matrix testing.
+        """
+        return cls.get_job(
+            job_func=cls.job_health_check_matrix,
+            strategy=cls.strategy_matrix_os_and_python_version(),
+            runs_on=cls.insert_matrix_os(),
+            steps=cls.steps_health_check_matrix(),
+        )
+
+    @classmethod
+    def job_health_check(cls) -> dict[str, Any]:
+        """Get the aggregation job that depends on matrix completion.
+
+        Returns:
+            Job configuration for result aggregation.
+        """
+        return cls.get_job(
+            job_func=cls.job_health_check,
+            needs=[cls.make_id_from_func(cls.job_health_check_matrix)],
+            steps=cls.steps_aggregate_matrix_results(),
+        )
+
+    @classmethod
+    def steps_health_check_matrix(cls) -> list[dict[str, Any]]:
+        """Get the steps for the matrix health check job.
+
+        Returns:
+            List of steps for setup, linting, and testing.
+        """
+        return [
+            *cls.steps_core_matrix_setup(
+                python_version=cls.insert_matrix_python_version(),
+            ),
+            cls.step_protect_repository(),
+            cls.step_run_pre_commit_hooks(),
+            cls.step_run_tests(),
+            cls.step_upload_coverage_report(),
+        ]
+
+    @classmethod
+    def steps_aggregate_matrix_results(cls) -> list[dict[str, Any]]:
+        """Get the steps for aggregating matrix results.
+
+        Returns:
+            List with the aggregation step.
+        """
+        return [
+            cls.step_aggregate_matrix_results(),
+        ]

pyrig/dev/configs/workflows/publish.py

@@ -0,0 +1,68 @@
+"""GitHub Actions workflow for publishing to PyPI.
+
+This module provides the PublishWorkflow class for creating
+a workflow that publishes the package to PyPI after a successful release.
+"""
+
+from typing import Any
+
+from pyrig.dev.configs.workflows.base.base import Workflow
+from pyrig.dev.configs.workflows.release import ReleaseWorkflow
+
+
+class PublishWorkflow(Workflow):
+    """Workflow for publishing packages to PyPI.
+
+    Triggers after the release workflow completes successfully.
+    Builds a wheel and publishes it to PyPI.
+    """
+
+    @classmethod
+    def get_workflow_triggers(cls) -> dict[str, Any]:
+        """Get the workflow triggers.
+
+        Returns:
+            Trigger for release workflow completion.
+        """
+        triggers = super().get_workflow_triggers()
+        triggers.update(
+            cls.on_workflow_run(workflows=[ReleaseWorkflow.get_workflow_name()])
+        )
+        return triggers
+
+    @classmethod
+    def get_jobs(cls) -> dict[str, Any]:
+        """Get the workflow jobs.
+
+        Returns:
+            Dict with the publish job.
+        """
+        jobs: dict[str, Any] = {}
+        jobs.update(cls.job_publish())
+        return jobs
+
+    @classmethod
+    def job_publish(cls) -> dict[str, Any]:
+        """Get the publish job configuration.
+
+        Returns:
+            Job that builds and publishes to PyPI.
+        """
+        return cls.get_job(
+            job_func=cls.job_publish,
+            steps=cls.steps_publish(),
+            if_condition=cls.if_workflow_run_is_success(),
+        )
+
+    @classmethod
+    def steps_publish(cls) -> list[dict[str, Any]]:
+        """Get the steps for publishing.
+
+        Returns:
+            List of steps for setup, build, and publish.
+        """
+        return [
+            *cls.steps_core_setup(),
+            cls.step_build_wheel(),
+            cls.step_publish_to_pypi(),
+        ]

pyrig/dev/configs/workflows/release.py

@@ -0,0 +1,90 @@
+"""GitHub Actions workflow for creating releases.
+
+This module provides the ReleaseWorkflow class for creating
+a workflow that creates tags and publishes GitHub releases
+after successful build workflow completion.
+"""
+
+from typing import Any
+
+from pyrig.dev.configs.workflows.base.base import Workflow
+from pyrig.dev.configs.workflows.build import BuildWorkflow
+
+
+class ReleaseWorkflow(Workflow):
+    """Workflow for creating GitHub releases.
+
+    Triggers after build workflow completes successfully.
+    Downloads artifacts from the build workflow, creates version tags,
+    generates changelogs, and publishes GitHub releases.
+    """
+
+    @classmethod
+    def get_workflow_triggers(cls) -> dict[str, Any]:
+        """Get the workflow triggers.
+
+        Returns:
+            Trigger for build workflow completion.
+        """
+        triggers = super().get_workflow_triggers()
+        triggers.update(
+            cls.on_workflow_run(
+                workflows=[BuildWorkflow.get_workflow_name()],
+            )
+        )
+        return triggers
+
+    @classmethod
+    def get_permissions(cls) -> dict[str, Any]:
+        """Get the workflow permissions.
+
+        Returns:
+            Permissions with write access for creating releases.
+        """
+        permissions = super().get_permissions()
+        permissions["contents"] = "write"
+        permissions["actions"] = "read"
+        return permissions
+
+    @classmethod
+    def get_jobs(cls) -> dict[str, Any]:
+        """Get the workflow jobs.
+
+        Returns:
+            Dict with release job.
+        """
+        jobs: dict[str, Any] = {}
+        jobs.update(cls.job_release())
+        return jobs
+
+    @classmethod
+    def job_release(cls) -> dict[str, Any]:
+        """Get the release job that creates the GitHub release.
+
+        Returns:
+            Job configuration for creating releases.
+        """
+        return cls.get_job(
+            job_func=cls.job_release,
+            if_condition=cls.if_workflow_run_is_success(),
+            steps=cls.steps_release(),
+        )
+
+    @classmethod
+    def steps_release(cls) -> list[dict[str, Any]]:
+        """Get the steps for creating the release.
+
+        Returns:
+            List of steps for tagging, changelog, and release creation.
+        """
+        return [
+            *cls.steps_core_installed_setup(repo_token=True),
+            cls.step_run_pre_commit_hooks(),
+            cls.step_commit_added_changes(),
+            cls.step_push_commits(),
+            cls.step_create_and_push_tag(),
+            cls.step_extract_version(),
+            cls.step_download_artifacts_from_workflow_run(),
+            cls.step_build_changelog(),
+            cls.step_create_release(),
+        ]

pyrig/dev/tests/__init__.py

@@ -0,0 +1,5 @@
+"""Test infrastructure for pyrig-based projects.
+
+This package provides pytest fixtures, utilities, and configuration
+for automated testing of pyrig projects.
+"""

pyrig/dev/tests/conftest.py

@@ -0,0 +1,40 @@
+"""Pytest configuration for pyrig tests.
+
+This module automatically discovers and registers pytest plugins from all
+packages that depend on pyrig. It finds fixtures modules across the dependency
+graph and adds them to pytest_plugins for automatic fixture availability.
+
+The discovery process:
+    1. Finds all packages depending on pyrig
+    2. Locates their fixtures modules
+    3. Collects all Python files within those modules
+    4. Registers them as pytest plugins
+"""
+
+from pathlib import Path
+
+import pyrig
+from pyrig.dev.tests import fixtures
+from pyrig.src.modules.module import (
+    get_same_modules_from_deps_depen_on_dep,
+    to_module_name,
+    to_path,
+)
+
+# find the fixtures module in all packages that depend on pyrig
+# and add all paths to pytest_plugins
+fixtures_pkgs = get_same_modules_from_deps_depen_on_dep(fixtures, pyrig)
+
+
+pytest_plugin_paths: list[Path] = []
+for pkg in fixtures_pkgs:
+    absolute_path = Path(pkg.__path__[0])
+    relative_path = to_path(pkg.__name__, is_package=True)
+
+    pkg_root = Path(absolute_path.as_posix().removesuffix(relative_path.as_posix()))
+
+    for path in absolute_path.rglob("*.py"):
+        rel_plugin_path = path.relative_to(pkg_root)
+        pytest_plugin_paths.append(rel_plugin_path)
+
+pytest_plugins = [to_module_name(path) for path in pytest_plugin_paths]

pyrig/dev/tests/fixtures/__init__.py

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

pyrig/dev/tests/fixtures/assertions.py

@@ -0,0 +1,147 @@
+"""Fixtures that assert some state or condition."""
+
+import logging
+import runpy
+import sys
+from collections.abc import Callable
+from importlib import import_module
+from types import ModuleType
+from typing import Any
+
+import pytest
+from pytest_mock import MockerFixture
+
+from pyrig import main
+from pyrig.dev.cli.commands.create_tests import make_test_skeletons
+from pyrig.dev.configs.pyproject import PyprojectConfigFile
+from pyrig.dev.configs.python.main import MainConfigFile
+from pyrig.dev.utils.testing import session_fixture
+from pyrig.src.modules.module import (
+    get_module_content_as_str,
+    get_module_name_replacing_start_module,
+    get_objs_from_obj,
+    make_obj_importpath,
+)
+from pyrig.src.os.os import run_subprocess
+from pyrig.src.project.mgt import PROJECT_MGT_RUN_ARGS
+from pyrig.src.testing.assertions import assert_with_msg
+from pyrig.src.testing.convention import (
+    get_obj_from_test_obj,
+    make_summary_error_msg,
+    make_test_obj_importpath_from_obj,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@session_fixture
+def assert_no_untested_objs() -> Callable[
+    [ModuleType | type | Callable[..., Any]], None
+]:
+    """Fixture that asserts that all objects of an object have corresponding tests.
+
+    This fixture provides a function that can be called to assert that all objects
+    (functions, classes, or methods) in a given module, class, or function have
+    corresponding test objects in the test module, class, or function.
+
+    """
+
+    def _assert_no_untested_objs(
+        test_obj: ModuleType | type | Callable[..., Any],
+    ) -> None:
+        """Assert that all objects in the source have corresponding test objects.
+
+        This function verifies that every object (function, class, or method) in the
+        source module or class has a corresponding test object
+        in the test module or class.
+
+        Args:
+            test_obj: The test object (module, class, or function) to check
+
+        Raises:
+            AssertionError: If any object lacks a corresponding test object,
+                with a detailed error message listing the untested objects
+
+        """
+        test_objs = get_objs_from_obj(test_obj)
+        test_objs_paths = {make_obj_importpath(obj) for obj in test_objs}
+
+        try:
+            obj = get_obj_from_test_obj(test_obj)
+        except ImportError:
+            if isinstance(test_obj, ModuleType):
+                # we skip if module not found bc that means it has custom tests
+                # and is not part of the mirrored structure
+                logger.warning("No source module found for %s, skipping", test_obj)
+                return
+            raise
+        objs = get_objs_from_obj(obj)
+        test_obj_path_to_obj = {
+            make_test_obj_importpath_from_obj(obj): obj for obj in objs
+        }
+
+        missing_test_obj_path_to_obj = {
+            test_path: obj
+            for test_path, obj in test_obj_path_to_obj.items()
+            if test_path not in test_objs_paths
+        }
+
+        # get the modules of these obj
+        if missing_test_obj_path_to_obj:
+            make_test_skeletons()
+
+        msg = f"""Found missing tests. Tests skeletons were automatically created for:
+        {make_summary_error_msg(missing_test_obj_path_to_obj.keys())}
+    """
+
+        assert_with_msg(
+            not missing_test_obj_path_to_obj,
+            msg,
+        )
+
+    return _assert_no_untested_objs
+
+
+@pytest.fixture
+def main_test_fixture(mocker: MockerFixture) -> None:
+    """Fixture for testing main."""
+    project_name = PyprojectConfigFile.get_project_name()
+    src_package_name = PyprojectConfigFile.get_package_name()
+
+    cmds = [
+        [*PROJECT_MGT_RUN_ARGS, project_name, "--help"],
+        [*PROJECT_MGT_RUN_ARGS, project_name, main.main.__name__, "--help"],
+    ]
+    success = False
+    for cmd in cmds:
+        completed_process = run_subprocess(cmd, check=False)
+        if completed_process.returncode == 0:
+            success = True
+            break
+    else:
+        cmd_strs = [" ".join(cmd) for cmd in cmds]
+        assert_with_msg(
+            success,
+            f"Expected {main.main.__name__} to be callable by one of {cmd_strs}",
+        )
+
+    main_module_name = get_module_name_replacing_start_module(main, src_package_name)
+    main_module = import_module(main_module_name)
+    main_mock = mocker.patch.object(main_module, main.main.__name__)
+    main_module.main()
+    assert_with_msg(
+        main_mock.call_count == 1,
+        f"Expected main to be called, got {main_mock.call_count}",
+    )
+
+    # must run main module directly as __main__
+    # so that pytest-cov sees that it calls main
+    # remove module if already imported, so run_module reloads it
+    del sys.modules[main_module_name]
+    # run module as __main__, pytest-cov will see it
+    # run only if file content is the same as pyrig.main
+    main_module_content = get_module_content_as_str(main_module)
+    config_main_module_content = MainConfigFile.get_content_str()
+
+    if main_module_content == config_main_module_content:
+        runpy.run_module(main_module_name, run_name="__main__")

pyrig/dev/tests/fixtures/autouse/__init__.py

@@ -0,0 +1,5 @@
+"""Scope-specific pytest fixtures.
+
+This package organizes fixtures by their pytest scope (function, class,
+module, package, session) for automatic discovery and registration.
+"""

pyrig/dev/tests/fixtures/autouse/class_.py

@@ -0,0 +1,42 @@
+"""Class-level test fixtures and utilities.
+
+These fixtures in this module are automatically applied to all test classes
+through pytest's autouse mechanism. Pyrig automatically adds this module to
+pytest_plugins in conftest.py. However you still have decorate the fixture
+with @autouse_class_fixture from pyrig.src.testing.fixtures or with pytest's
+autouse mechanism @pytest.fixture(scope="class", autouse=True).
+"""
+
+from collections.abc import Callable
+from types import ModuleType
+from typing import Any
+
+import pytest
+
+from pyrig.dev.utils.testing import autouse_class_fixture
+
+
+@autouse_class_fixture
+def assert_all_methods_tested(
+    request: pytest.FixtureRequest,
+    assert_no_untested_objs: Callable[[ModuleType | type | Callable[..., Any]], None],
+) -> None:
+    """Verify that all methods in a class have corresponding tests.
+
+    This fixture runs automatically for each test class and checks that every
+    method defined in the corresponding source class has a test method defined
+    in the test class.
+
+    Args:
+        request: The pytest fixture request object containing the current class
+        assert_no_untested_objs: The assert_no_untested_objs fixture asserts
+            that all objects have corresponding tests
+
+    Raises:
+        AssertionError: If any method in the source class lacks a test
+
+    """
+    class_ = request.node.cls
+    if class_ is None:
+        return
+    assert_no_untested_objs(class_)

pyrig/dev/tests/fixtures/autouse/module.py

@@ -0,0 +1,40 @@
+"""Module-level test fixtures and utilities.
+
+These fixtures in this module are automatically applied to all test modules
+through pytest's autouse mechanism. Pyrig automatically adds this module to
+pytest_plugins in conftest.py. However you still have decorate the fixture
+with @autouse_module_fixture from pyrig.src.testing.fixtures or with pytest's
+autouse mechanism @pytest.fixture(scope="module", autouse=True).
+"""
+
+from collections.abc import Callable
+from types import ModuleType
+from typing import Any
+
+import pytest
+
+from pyrig.dev.utils.testing import autouse_module_fixture
+
+
+@autouse_module_fixture
+def assert_all_funcs_and_classes_tested(
+    request: pytest.FixtureRequest,
+    assert_no_untested_objs: Callable[[ModuleType | type | Callable[..., Any]], None],
+) -> None:
+    """Verify that all functions and classes in a module have corresponding tests.
+
+    This fixture runs automatically for each test module and checks that every
+    function and class defined in the corresponding source module has a test
+    function or class defined in the test module.
+
+    Args:
+        request: The pytest fixture request object containing the current module
+        assert_no_untested_objs: The assert_no_untested_objs fixture asserts
+            that all objects have corresponding tests
+
+    Raises:
+        AssertionError: If any function or class in the source module lacks a test
+
+    """
+    module: ModuleType = request.module
+    assert_no_untested_objs(module)