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_action ¶

codecov_action() -> tuple[str, str, str]

Return action metadata for codecov/codecov-action.

Returns:

Type	Description
`tuple[str, str, str]`	Tuple of action name, pinned commit SHA, and release tag.

Source code in src/pyrig_codecov/rig/configs/version_control/remote/workflows/health_check.py

def codecov_action(self) -> tuple[str, str, str]:
    """Return action metadata for `codecov/codecov-action`.

    Returns:
        Tuple of action name, pinned commit SHA, and release tag.
    """
    return self.action_from_resource(self.codecov_action, resources)

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

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

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@<ref>`.

Note

The upload token always comes from a CODECOV_TOKEN repository secret, so it must be configured for the upload to succeed. Since this workflow also runs for Dependabot pull requests, the secret must be added to both the Actions and Dependabot secret stores.

Source code in src/pyrig_codecov/rig/configs/version_control/remote/workflows/health_check.py

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@<ref>`.

    Note:
        The upload token always comes from a `CODECOV_TOKEN` repository
        secret, so it must be configured for the upload to succeed. Since
        this workflow also runs for Dependabot pull requests, the secret
        must be added to both the Actions and Dependabot secret stores.
    """
    return self.step(
        self.step_upload_coverage_report,
        uses=self.codecov_action(),
        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

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(),
    ]

resources ¶

Static resource files bundled with the project.

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

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

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

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

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

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

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

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

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(),
    )