Skip to content

API Reference

The top-level package for the project.

rig

Package initialization.

configs

Package initialization.

remote_version_control

Package initialization.

workflows

Package initialization.

health_check

GitHub Actions workflow generator for the health check CI stage.

HealthCheckWorkflowConfigFile

Bases: HealthCheckWorkflowConfigFile

Overrides the base class methods to customize the health check workflow.

Source code in src/pyrig_codecov/rig/configs/remote_version_control/workflows/health_check.py 
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
class HealthCheckWorkflowConfigFile(BaseHealthCheckWorkflowConfigFile):
    """Overrides the base class methods to customize the health check workflow."""

    def steps_matrix_health_checks(self) -> list[dict[str, Any]]:
        """Return the steps for the matrix health checks job.

        Extends the base class steps with an additional step to upload the
        coverage report to Codecov.

        Returns:
            List of step configuration dicts for the matrix health checks job,
            including the Codecov upload step.
        """
        return [
            *super().steps_matrix_health_checks(),
            self.step_upload_coverage_report(),
        ]

    def step_upload_coverage_report(
        self,
        *,
        step: dict[str, Any] | None = None,
    ) -> dict[str, Any]:
        """Build a step that uploads the coverage report to Codecov.

        Requires a Codecov account linked to the repository (log in at
        codecov.io with GitHub).
        Fails the CI job if the upload fails, ensuring that coverage reports are
        always uploaded when the health check workflow runs.

        Args:
            step: Additional keys to merge into the step configuration.

        Returns:
            Step using ``codecov/codecov-action@main``.
        """
        return self.step(
            step_func=self.step_upload_coverage_report,
            uses="codecov/codecov-action@main",
            with_={
                "files": CoverageTester.I.report_file().as_posix(),
                "token": self.insert_codecov_token(),
                "fail_ci_if_error": "true",
            },
            step=step,
        )

    def insert_codecov_token(self) -> str:
        """Get the ``${{ secrets.CODECOV_TOKEN }}`` expression.

        Returns:
            GitHub Actions expression for the ``CODECOV_TOKEN`` secret.
        """
        return self.insert_var(self.codecov_token_var())

    def codecov_token_var(self) -> str:
        """Get the raw secrets expression for ``CODECOV_TOKEN``.

        Returns:
            ``"secrets.CODECOV_TOKEN"``
        """
        return self.secrets_var(CoverageTester.I.access_token_key())
codecov_token_var()

Get the raw secrets expression for CODECOV_TOKEN.

Returns:

Type Description
str

"secrets.CODECOV_TOKEN"
Source code in src/pyrig_codecov/rig/configs/remote_version_control/workflows/health_check.py 
67
68
69
70
71
72
73
def codecov_token_var(self) -> str:
    """Get the raw secrets expression for ``CODECOV_TOKEN``.

    Returns:
        ``"secrets.CODECOV_TOKEN"``
    """
    return self.secrets_var(CoverageTester.I.access_token_key())
insert_codecov_token()

Get the ${{ secrets.CODECOV_TOKEN }} expression.

Returns:

Type Description
str

GitHub Actions expression for the CODECOV_TOKEN secret.
Source code in src/pyrig_codecov/rig/configs/remote_version_control/workflows/health_check.py 
59
60
61
62
63
64
65
def insert_codecov_token(self) -> str:
    """Get the ``${{ secrets.CODECOV_TOKEN }}`` expression.

    Returns:
        GitHub Actions expression for the ``CODECOV_TOKEN`` secret.
    """
    return self.insert_var(self.codecov_token_var())
step_upload_coverage_report(*, step=None)

Build a step that uploads the coverage report to Codecov.

Requires a Codecov account linked to the repository (log in at codecov.io with GitHub). Fails the CI job if the upload fails, ensuring that coverage reports are always uploaded when the health check workflow runs.

Parameters:

Name Type Description Default
step dict[str, Any] | None

Additional keys to merge into the step configuration.

 None

Returns:

Type Description
dict[str, Any]

Step using codecov/codecov-action@main.
Source code in src/pyrig_codecov/rig/configs/remote_version_control/workflows/health_check.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
def step_upload_coverage_report(
    self,
    *,
    step: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """Build a step that uploads the coverage report to Codecov.

    Requires a Codecov account linked to the repository (log in at
    codecov.io with GitHub).
    Fails the CI job if the upload fails, ensuring that coverage reports are
    always uploaded when the health check workflow runs.

    Args:
        step: Additional keys to merge into the step configuration.

    Returns:
        Step using ``codecov/codecov-action@main``.
    """
    return self.step(
        step_func=self.step_upload_coverage_report,
        uses="codecov/codecov-action@main",
        with_={
            "files": CoverageTester.I.report_file().as_posix(),
            "token": self.insert_codecov_token(),
            "fail_ci_if_error": "true",
        },
        step=step,
    )
steps_matrix_health_checks()

Return the steps for the matrix health checks job.

Extends the base class steps with an additional step to upload the coverage report to Codecov.

Returns:

Type Description
list[dict[str, Any]]

List of step configuration dicts for the matrix health checks job,
list[dict[str, Any]]

including the Codecov upload step.
Source code in src/pyrig_codecov/rig/configs/remote_version_control/workflows/health_check.py 
15
16
17
18
19
20
21
22
23
24
25
26
27
28
def steps_matrix_health_checks(self) -> list[dict[str, Any]]:
    """Return the steps for the matrix health checks job.

    Extends the base class steps with an additional step to upload the
    coverage report to Codecov.

    Returns:
        List of step configuration dicts for the matrix health checks job,
        including the Codecov upload step.
    """
    return [
        *super().steps_matrix_health_checks(),
        self.step_upload_coverage_report(),
    ]

tools

Package initialization.

coverage_tester

Coverage testing wrapper for the code coverage tool.

Wraps CoverageTester commands and information.

CoverageTester

Bases: CoverageTester

Overrides the base CoverageTester from pyrig.

Source code in src/pyrig_codecov/rig/tools/coverage_tester.py 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
class CoverageTester(BaseCoverageTester):
    """Overrides the base CoverageTester from pyrig."""

    def badge_urls(self) -> tuple[str, str]:
        """Get the Codecov badge image URL and dashboard URL.

        The badge image URL points to an SVG coverage badge on Codecov's CDN
        scoped to the default branch. The dashboard URL is the Codecov project
        page for the current repository.

        Returns:
            Tuple of (badge_image_url, dashboard_url), where badge_image_url
            is the SVG badge URL including the default branch, and dashboard_url
            is the Codecov project dashboard URL.
        """
        return (
            f"{self.remote_coverage_url()}/branch/{VersionController.I.default_branch()}/graph/badge.svg",
            self.remote_coverage_url(),
        )

    def version_control_ignore_paths(self) -> tuple[str, ...]:
        """Get the paths to ignore for version control."""
        return (*super().version_control_ignore_paths(), self.report_file().as_posix())

    def additional_test_args(self) -> Args:
        """Get additional pytest-cov arguments for CI test runs.

        Added on top of ``additional_test_args()`` during CI execution to produce an
        XML coverage report, which is required for uploading results to Codecov.

        Returns:
            Tuple containing ``--cov-report=xml``.
        """
        return Args(
            (
                *super().additional_test_args(),
                f"--cov-report={self.report_file().suffix.removeprefix('.')}",
            )
        )

    def threshold(self) -> int:
        """Enforcing 100% coverage for packages with this plugin."""
        return 100

    def remote_coverage_url(self) -> str:
        """Construct the Codecov project dashboard URL for the current repository.

        Resolves the repository owner from the git remote and
        the repository name from the project name.

        Returns:
            URL in the format ``https://codecov.io/gh/{owner}/{repo}``.
        """
        owner, repo = (
            VersionController.I.repo_owner(check_repo_url=False),
            PackageManager.I.project_name(),
        )
        return f"https://codecov.io/gh/{owner}/{repo}"

    def access_token_key(self) -> str:
        """Get the environment variable name for the Codecov upload token.

        This key is referenced in CI workflow definitions to inject the
        Codecov authentication token when uploading coverage reports.

        Returns:
            'CODECOV_TOKEN'
        """
        return "CODECOV_TOKEN"

    def report_file(self) -> Path:
        """Get the Path object for the coverage report file.

        Returns:
            Path object pointing to the coverage report file
        """
        return Path("coverage.xml")
access_token_key()

Get the environment variable name for the Codecov upload token.

This key is referenced in CI workflow definitions to inject the Codecov authentication token when uploading coverage reports.

Returns:

Type Description
str

'CODECOV_TOKEN'
Source code in src/pyrig_codecov/rig/tools/coverage_tester.py 
73
74
75
76
77
78
79
80
81
82
def access_token_key(self) -> str:
    """Get the environment variable name for the Codecov upload token.

    This key is referenced in CI workflow definitions to inject the
    Codecov authentication token when uploading coverage reports.

    Returns:
        'CODECOV_TOKEN'
    """
    return "CODECOV_TOKEN"
additional_test_args()

Get additional pytest-cov arguments for CI test runs.

Added on top of additional_test_args() during CI execution to produce an XML coverage report, which is required for uploading results to Codecov.

Returns:

Type Description
Args

Tuple containing --cov-report=xml.
Source code in src/pyrig_codecov/rig/tools/coverage_tester.py 
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
def additional_test_args(self) -> Args:
    """Get additional pytest-cov arguments for CI test runs.

    Added on top of ``additional_test_args()`` during CI execution to produce an
    XML coverage report, which is required for uploading results to Codecov.

    Returns:
        Tuple containing ``--cov-report=xml``.
    """
    return Args(
        (
            *super().additional_test_args(),
            f"--cov-report={self.report_file().suffix.removeprefix('.')}",
        )
    )
badge_urls()

Get the Codecov badge image URL and dashboard URL.

The badge image URL points to an SVG coverage badge on Codecov's CDN scoped to the default branch. The dashboard URL is the Codecov project page for the current repository.

Returns:

Type Description
str

Tuple of (badge_image_url, dashboard_url), where badge_image_url
str

is the SVG badge URL including the default branch, and dashboard_url
tuple[str, str]

is the Codecov project dashboard URL.
Source code in src/pyrig_codecov/rig/tools/coverage_tester.py 
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
def badge_urls(self) -> tuple[str, str]:
    """Get the Codecov badge image URL and dashboard URL.

    The badge image URL points to an SVG coverage badge on Codecov's CDN
    scoped to the default branch. The dashboard URL is the Codecov project
    page for the current repository.

    Returns:
        Tuple of (badge_image_url, dashboard_url), where badge_image_url
        is the SVG badge URL including the default branch, and dashboard_url
        is the Codecov project dashboard URL.
    """
    return (
        f"{self.remote_coverage_url()}/branch/{VersionController.I.default_branch()}/graph/badge.svg",
        self.remote_coverage_url(),
    )
remote_coverage_url()

Construct the Codecov project dashboard URL for the current repository.

Resolves the repository owner from the git remote and the repository name from the project name.

Returns:

Type Description
str

URL in the format https://codecov.io/gh/{owner}/{repo}.
Source code in src/pyrig_codecov/rig/tools/coverage_tester.py 
58
59
60
61
62
63
64
65
66
67
68
69
70
71
def remote_coverage_url(self) -> str:
    """Construct the Codecov project dashboard URL for the current repository.

    Resolves the repository owner from the git remote and
    the repository name from the project name.

    Returns:
        URL in the format ``https://codecov.io/gh/{owner}/{repo}``.
    """
    owner, repo = (
        VersionController.I.repo_owner(check_repo_url=False),
        PackageManager.I.project_name(),
    )
    return f"https://codecov.io/gh/{owner}/{repo}"
report_file()

Get the Path object for the coverage report file.

Returns:

Type Description
Path

Path object pointing to the coverage report file
Source code in src/pyrig_codecov/rig/tools/coverage_tester.py 
84
85
86
87
88
89
90
def report_file(self) -> Path:
    """Get the Path object for the coverage report file.

    Returns:
        Path object pointing to the coverage report file
    """
    return Path("coverage.xml")
threshold()

Enforcing 100% coverage for packages with this plugin.

Source code in src/pyrig_codecov/rig/tools/coverage_tester.py 
54
55
56
def threshold(self) -> int:
    """Enforcing 100% coverage for packages with this plugin."""
    return 100
version_control_ignore_paths()

Get the paths to ignore for version control.

Source code in src/pyrig_codecov/rig/tools/coverage_tester.py 
34
35
36
def version_control_ignore_paths(self) -> tuple[str, ...]:
    """Get the paths to ignore for version control."""
    return (*super().version_control_ignore_paths(), self.report_file().as_posix())