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

Generate a health-check workflow that uploads matrix coverage to Codecov.

HealthCheckWorkflowConfigFile

Bases: HealthCheckWorkflowConfigFile

Store matrix reports and upload them to Codecov in a separate job.

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

Return the name, pinned commit SHA, and release tag for Codecov.

Returns:

Type Description
tuple[str, str, str]

Metadata for codecov/codecov-action.

Source code in src/pyrig_codecov/rig/configs/version_control/remote/workflows/health_check.py
def action_codecov(self) -> tuple[str, str, str]:
    """Return the name, pinned commit SHA, and release tag for Codecov.

    Returns:
        Metadata for `codecov/codecov-action`.
    """
    return self.action_from_resource(self.action_codecov, resources)
coverage_artifact_name
coverage_artifact_name(os: str, python_version: str) -> str

Return a name identifying a matrix OS and Python version.

Source code in src/pyrig_codecov/rig/configs/version_control/remote/workflows/health_check.py
def coverage_artifact_name(self, os: str, python_version: str) -> str:
    """Return a name identifying a matrix OS and Python version."""
    return f"coverage-{os}-{python_version}"
coverage_reports_dir
coverage_reports_dir() -> Path

Return the directory containing downloaded coverage artifacts.

Source code in src/pyrig_codecov/rig/configs/version_control/remote/workflows/health_check.py
def coverage_reports_dir(self) -> Path:
    """Return the directory containing downloaded coverage artifacts."""
    return Path("coverage-reports")
job_upload_coverage
job_upload_coverage() -> dict[str, Any]

Build the OIDC-enabled job that uploads matrix reports to Codecov.

Source code in src/pyrig_codecov/rig/configs/version_control/remote/workflows/health_check.py
def job_upload_coverage(self) -> dict[str, Any]:
    """Build the OIDC-enabled job that uploads matrix reports to Codecov."""
    return self.job(
        self.job_upload_coverage,
        needs=(self.job_matrix_health_checks,),
        permissions=self.permissions_job_upload_coverage(),
        steps=self.steps_upload_coverage(),
        timeout_minutes=30,
    )
jobs_health_check
jobs_health_check() -> (
    tuple[Callable[[], dict[str, Any]], ...]
)

Place the coverage upload immediately after the matrix health checks.

Source code in src/pyrig_codecov/rig/configs/version_control/remote/workflows/health_check.py
@override
def jobs_health_check(self) -> tuple[Callable[[], dict[str, Any]], ...]:
    """Place the coverage upload immediately after the matrix health checks."""
    jobs = list(super().jobs_health_check())
    jobs.insert(
        jobs.index(self.job_matrix_health_checks) + 1,
        self.job_upload_coverage,
    )
    return tuple(jobs)
permissions_job_upload_coverage
permissions_job_upload_coverage() -> dict[str, str]

Return the checkout read and Codecov OIDC token permissions.

Source code in src/pyrig_codecov/rig/configs/version_control/remote/workflows/health_check.py
def permissions_job_upload_coverage(self) -> dict[str, str]:
    """Return the checkout read and Codecov OIDC token permissions."""
    return {
        **self.permission_contents(),
        **self.permission_id_token(write=True),
    }
step_download_coverage_reports
step_download_coverage_reports() -> dict[str, Any]

Download this run's reports into separate artifact directories.

Separate directories prevent identically named reports from overwriting.

Source code in src/pyrig_codecov/rig/configs/version_control/remote/workflows/health_check.py
def step_download_coverage_reports(self) -> dict[str, Any]:
    """Download this run's reports into separate artifact directories.

    Separate directories prevent identically named reports from overwriting.
    """
    return self.step_download_artifact(
        self.step_download_coverage_reports,
        pattern=self.coverage_artifact_name("*", "*"),
        path=self.coverage_reports_dir(),
        merge_multiple=False,
    )
step_upload_coverage
step_upload_coverage() -> dict[str, Any]

Upload reports from the artifact directory using OIDC.

Fail the job if the upload fails.

Source code in src/pyrig_codecov/rig/configs/version_control/remote/workflows/health_check.py
def step_upload_coverage(self) -> dict[str, Any]:
    """Upload reports from the artifact directory using OIDC.

    Fail the job if the upload fails.
    """
    return self.step(
        self.step_upload_coverage,
        uses=self.action_codecov(),
        with_={
            "directory": self.coverage_reports_dir().as_posix(),
            "fail_ci_if_error": "true",
            "use_oidc": "true",
        },
    )
step_upload_coverage_report
step_upload_coverage_report() -> dict[str, Any]

Store this matrix job's coverage XML as an artifact.

Fail if the coverage report file is missing.

Source code in src/pyrig_codecov/rig/configs/version_control/remote/workflows/health_check.py
def step_upload_coverage_report(self) -> dict[str, Any]:
    """Store this matrix job's coverage XML as an artifact.

    Fail if the coverage report file is missing.
    """
    return self.step_upload_artifact(
        self.step_upload_coverage_report,
        name=self.coverage_artifact_name(
            self.insert_matrix_os(),
            self.insert_matrix_python_version(),
        ),
        path=ProjectTester.I.report_file(),
    )
steps_matrix_health_checks
steps_matrix_health_checks() -> list[dict[str, Any]]

Add coverage artifact storage after the matrix test steps.

Source code in src/pyrig_codecov/rig/configs/version_control/remote/workflows/health_check.py
@override
def steps_matrix_health_checks(self) -> list[dict[str, Any]]:
    """Add coverage artifact storage after the matrix test steps."""
    return [
        *super().steps_matrix_health_checks(),
        self.step_upload_coverage_report(),
    ]
steps_upload_coverage
steps_upload_coverage() -> list[dict[str, Any]]

Check out the repository, then download and upload reports.

Without checkout the Codecov uploader cannot map report paths to tracked repository files.

Source code in src/pyrig_codecov/rig/configs/version_control/remote/workflows/health_check.py
def steps_upload_coverage(self) -> list[dict[str, Any]]:
    """Check out the repository, then download and upload reports.

    Without checkout the Codecov uploader cannot map report paths to tracked
    repository files.
    """
    return [
        self.step_checkout_repository(),
        self.step_download_coverage_reports(),
        self.step_upload_coverage(),
    ]

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 and format needed to publish results to Codecov from CI.

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