Skip to content

API Reference

Pyrig plugin that integrates Codecov coverage reporting into a project.

rig

Codecov overrides of pyrig's scaffolding and maintenance layer.

Mirrors pyrig's own rig namespace so its plugin-discovery mechanism picks up this package's configuration and tooling customizations automatically.

configs

Declarative definitions of the configuration files managed by this plugin.

This package is this plugin's discovery scope for pyrig's config-file management: every file this plugin manages or overrides is defined here.

version_control

Codecov customizations for generated version-control configuration.

remote

Codecov customizations for generated GitHub remote-repository configuration.

workflows

Codecov-specific overrides for GitHub Actions workflow configuration.

health_check

Codecov integration for the health check CI workflow.

HealthCheckWorkflowConfigFile

Bases: HealthCheckWorkflowConfigFile

Health check workflow extended with a Codecov coverage upload step.

Source code in src/pyrig_codecov/rig/configs/version_control/remote/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
class HealthCheckWorkflowConfigFile(BaseHealthCheckWorkflowConfigFile):
    """Health check workflow extended with a Codecov coverage upload step."""

    def steps_matrix_health_checks(self) -> list[dict[str, Any]]:
        """Return the matrix job steps, extended with a Codecov upload step.

        Returns:
            The base class steps plus a final step that uploads the
            coverage report to Codecov.
        """
        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.

        Fails the CI job if the upload fails.

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

        Returns:
            Step using `codecov/codecov-action@main`.

        Note:
            Requires a Codecov account linked to the repository (log in at
            codecov.io with GitHub).
        """
        return self.step(
            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",
                "skip_validation": "true",
            },
            step=step,
        )

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

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

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

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

Return the raw secrets expression for CODECOV_TOKEN.

Returns:

Type Description
str

The "secrets.CODECOV_TOKEN" expression string.
Source code in src/pyrig_codecov/rig/configs/version_control/remote/workflows/health_check.py 
66
67
68
69
70
71
72
def codecov_token_var(self) -> str:
    """Return the raw secrets expression for `CODECOV_TOKEN`.

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

Return 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/version_control/remote/workflows/health_check.py 
58
59
60
61
62
63
64
def insert_codecov_token(self) -> str:
    """Return the `${{ secrets.CODECOV_TOKEN }}` expression.

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

Build a step that uploads the coverage report to Codecov.

Fails the CI job if the upload fails.

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.
Note

Requires a Codecov account linked to the repository (log in at codecov.io with GitHub).

Source code in src/pyrig_codecov/rig/configs/version_control/remote/workflows/health_check.py 
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
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.

    Fails the CI job if the upload fails.

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

    Returns:
        Step using `codecov/codecov-action@main`.

    Note:
        Requires a Codecov account linked to the repository (log in at
        codecov.io with GitHub).
    """
    return self.step(
        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",
            "skip_validation": "true",
        },
        step=step,
    )
steps_matrix_health_checks()

Return the matrix job steps, extended with a Codecov upload step.

Returns:

Type Description
list[dict[str, Any]]

The base class steps plus a final step that uploads the
list[dict[str, Any]]

coverage report to Codecov.
Source code in src/pyrig_codecov/rig/configs/version_control/remote/workflows/health_check.py 
15
16
17
18
19
20
21
22
23
24
25
def steps_matrix_health_checks(self) -> list[dict[str, Any]]:
    """Return the matrix job steps, extended with a Codecov upload step.

    Returns:
        The base class steps plus a final step that uploads the
        coverage report to Codecov.
    """
    return [
        *super().steps_matrix_health_checks(),
        self.step_upload_coverage_report(),
    ]

tools

Tool definitions and overrides contributed by this plugin.

Every Tool subclass that this package defines or overrides is discovered from here, extending pyrig's tool management to cover this plugin's own tooling.

testers

Codecov-specific overrides of pyrig's test-and-coverage tool wrappers.

coverage

Codecov-specific coverage reporting and badge configuration.

CoverageTester

Bases: CoverageTester

Coverage tool configured for Codecov as the reporting backend.

Points the coverage badge at Codecov instead of a static shields.io badge, and raises the required coverage threshold to 100%.

Source code in src/pyrig_codecov/rig/tools/testers/coverage.py 
11
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
class CoverageTester(BaseCoverageTester):
    """Coverage tool configured for Codecov as the reporting backend.

    Points the coverage badge at Codecov instead of a static shields.io
    badge, and raises the required coverage threshold to 100%.
    """

    def image_url(self) -> str:
        """Return the URL of the Codecov coverage badge image for the default branch."""
        remote_url, branch = (
            self.remote_coverage_url(),
            VersionController.I.default_branch(),
        )
        return f"{remote_url}/branch/{branch}/graph/badge.svg"

    def link_url(self) -> str:
        """Return the URL of the Codecov project dashboard."""
        return self.remote_coverage_url()

    def version_control_ignore_paths(self) -> tuple[str, ...]:
        """Return the base ignore paths plus the coverage report file."""
        return (*super().version_control_ignore_paths(), self.report_file().as_posix())

    def additional_test_args(self) -> Args:
        """Return the pytest-cov CLI flags, extended with a report-format flag.

        Returns:
            The base pytest-cov flags plus a `--cov-report` flag matching
            `report_file`'s extension.
        """
        return Args(
            *super().additional_test_args(),
            f"--cov-report={self.report_file().suffix.removeprefix('.')}",
        )

    def threshold(self) -> int:
        """Return `100`."""
        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(),
            PackageManager.I.project_name(),
        )
        return f"https://codecov.io/gh/{owner}/{repo}"

    def access_token_key(self) -> str:
        """Return `'CODECOV_TOKEN'`, the env var name for the Codecov upload token."""
        return "CODECOV_TOKEN"

    def report_file(self) -> Path:
        """Return `Path("coverage.xml")`, the coverage report file path."""
        return Path("coverage.xml")
access_token_key()

Return 'CODECOV_TOKEN', the env var name for the Codecov upload token.

Source code in src/pyrig_codecov/rig/tools/testers/coverage.py 
65
66
67
def access_token_key(self) -> str:
    """Return `'CODECOV_TOKEN'`, the env var name for the Codecov upload token."""
    return "CODECOV_TOKEN"
additional_test_args()

Return the pytest-cov CLI flags, extended with a report-format flag.

Returns:

Type Description
Args

The base pytest-cov flags plus a --cov-report flag matching
Args

report_file's extension.
Source code in src/pyrig_codecov/rig/tools/testers/coverage.py 
34
35
36
37
38
39
40
41
42
43
44
def additional_test_args(self) -> Args:
    """Return the pytest-cov CLI flags, extended with a report-format flag.

    Returns:
        The base pytest-cov flags plus a `--cov-report` flag matching
        `report_file`'s extension.
    """
    return Args(
        *super().additional_test_args(),
        f"--cov-report={self.report_file().suffix.removeprefix('.')}",
    )
image_url()

Return the URL of the Codecov coverage badge image for the default branch.

Source code in src/pyrig_codecov/rig/tools/testers/coverage.py 
18
19
20
21
22
23
24
def image_url(self) -> str:
    """Return the URL of the Codecov coverage badge image for the default branch."""
    remote_url, branch = (
        self.remote_coverage_url(),
        VersionController.I.default_branch(),
    )
    return f"{remote_url}/branch/{branch}/graph/badge.svg"
link_url()

Return the URL of the Codecov project dashboard.

Source code in src/pyrig_codecov/rig/tools/testers/coverage.py 
26
27
28
def link_url(self) -> str:
    """Return the URL of the Codecov project dashboard."""
    return 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/testers/coverage.py 
50
51
52
53
54
55
56
57
58
59
60
61
62
63
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(),
        PackageManager.I.project_name(),
    )
    return f"https://codecov.io/gh/{owner}/{repo}"
report_file()

Return Path("coverage.xml"), the coverage report file path.

Source code in src/pyrig_codecov/rig/tools/testers/coverage.py 
69
70
71
def report_file(self) -> Path:
    """Return `Path("coverage.xml")`, the coverage report file path."""
    return Path("coverage.xml")
threshold()

Return 100.

Source code in src/pyrig_codecov/rig/tools/testers/coverage.py 
46
47
48
def threshold(self) -> int:
    """Return `100`."""
    return 100
version_control_ignore_paths()

Return the base ignore paths plus the coverage report file.

Source code in src/pyrig_codecov/rig/tools/testers/coverage.py 
30
31
32
def version_control_ignore_paths(self) -> tuple[str, ...]:
    """Return the base ignore paths plus the coverage report file."""
    return (*super().version_control_ignore_paths(), self.report_file().as_posix())