Skip to content

API

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 automatically picks up this package's overrides and additions.

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 coverage-upload step for the health check CI workflow.

HealthCheckWorkflowConfigFile

Bases: HealthCheckWorkflowConfigFile

Health check workflow extended with a Codecov coverage upload step.

codecov_token_var 
codecov_token_var() -> str

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 
58
59
60
61
62
63
64
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(ProjectTester.I.access_token_key())
insert_codecov_token 
insert_codecov_token() -> str

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 
50
51
52
53
54
55
56
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_upload_coverage_report() -> dict[str, Any]

Build a step that uploads the coverage report to Codecov.

Fails the CI job if the upload fails.

Returns:

Type Description
dict[str, Any]

Step using codecov/codecov-action@main.
Note

The upload token always comes from a CODECOV_TOKEN repository secret, so it must be configured for the upload to succeed.

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
def step_upload_coverage_report(self) -> dict[str, Any]:
    """Build a step that uploads the coverage report to Codecov.

    Fails the CI job if the upload fails.

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

    Note:
        The upload token always comes from a `CODECOV_TOKEN` repository
        secret, so it must be configured for the upload to succeed.
    """
    return self.step(
        self.step_upload_coverage_report,
        uses="codecov/codecov-action@main",
        with_={
            "files": ProjectTester.I.report_file().as_posix(),
            "token": self.insert_codecov_token(),
            "fail_ci_if_error": "true",
            "skip_validation": "true",
        },
    )
steps_matrix_health_checks 
steps_matrix_health_checks() -> list[dict[str, Any]]

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.

This package is this plugin's discovery scope for pyrig's tool management: every tool this plugin defines or overrides is declared here.

testing

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

project

Codecov-specific coverage reporting and badge configuration.

ProjectTester

Bases: ProjectTester

Coverage tool configured for Codecov as the reporting backend.

Points the coverage badge at Codecov instead of a static shields.io badge, raises the required coverage threshold to 100%, and exposes the report file, format, and upload token needed to publish results to Codecov from CI.

access_token_key 
access_token_key() -> str

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

Source code in src/pyrig_codecov/rig/tools/testing/project.py 
59
60
61
def access_token_key(self) -> str:
    """Return `'CODECOV_TOKEN'`, the env var name for the Codecov upload token."""
    return "CODECOV_TOKEN"
additional_args 
additional_args() -> Args

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

Returns:

Type Description
Args

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

flag set to report_format()'s value.
Source code in src/pyrig_codecov/rig/tools/testing/project.py 
20
21
22
23
24
25
26
27
28
29
30
def additional_args(self) -> Args:
    """Return the base pytest flags, extended with a report-format flag.

    Returns:
        The base pytest flags plus a `--cov-report`
        flag set to `report_format()`'s value.
    """
    return Args(
        *super().additional_args(),
        f"--cov-report={self.report_format()}",
    )
image_url 
image_url() -> str

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

Source code in src/pyrig_codecov/rig/tools/testing/project.py 
32
33
34
35
36
37
38
def image_url(self) -> str:
    """Return the URL of the Codecov coverage badge image for the default branch."""
    remote_url, branch = (
        self.link_url(),
        VersionController.I.default_branch(),
    )
    return f"{remote_url}/branch/{branch}/graph/badge.svg"
link_url 
link_url() -> str

Return the URL of the Codecov project dashboard.

Source code in src/pyrig_codecov/rig/tools/testing/project.py 
40
41
42
43
44
45
46
def link_url(self) -> str:
    """Return the URL of the Codecov project dashboard."""
    owner, repo = (
        VersionController.I.repo_owner(),
        PackageManager.I.project_name(),
    )
    return f"https://codecov.io/gh/{owner}/{repo}"
report_file 
report_file() -> Path

Return the coverage report file path.

Returns:

Type Description
Path

coverage.<ext>, where <ext> is report_format()'s value.
Source code in src/pyrig_codecov/rig/tools/testing/project.py 
63
64
65
66
67
68
69
def report_file(self) -> Path:
    """Return the coverage report file path.

    Returns:
        `coverage.<ext>`, where `<ext>` is `report_format()`'s value.
    """
    return Path(f"coverage.{self.report_format()}")
report_format 
report_format() -> str

Return 'xml', the coverage report format.

Source code in src/pyrig_codecov/rig/tools/testing/project.py 
71
72
73
def report_format(self) -> str:
    """Return `'xml'`, the coverage report format."""
    return "xml"
threshold 
threshold() -> int

Return 100.

Source code in src/pyrig_codecov/rig/tools/testing/project.py 
48
49
50
def threshold(self) -> int:
    """Return `100`."""
    return 100
version_control_ignore_patterns 
version_control_ignore_patterns() -> tuple[str, ...]

Return the base ignore paths plus the coverage report file.

Source code in src/pyrig_codecov/rig/tools/testing/project.py 
52
53
54
55
56
57
def version_control_ignore_patterns(self) -> tuple[str, ...]:
    """Return the base ignore paths plus the coverage report file."""
    return (
        *super().version_control_ignore_patterns(),
        self.report_file().as_posix(),
    )