The common.py module

Summary

Enums

RuleStatus

Public status of a quality rule.

Functions

file_exists	Return whether a repository file exists.
file_content	Read a repository file (as UTF-8) without allowing path traversal.
all_workflows_content	Return the merged text of the GitHub Actions workflow files.
readme_path	Return the preferred README path for a repository.
_first_doc_line	Return the first non-empty line of a rule check docstring.
normalize_check_result	Normalize a rule return value into a public status and detail.

Attributes

RuleCheckResult

Constants

PASSED
WARNING
ERROR

Description

Shared helpers for quality check rules.

Module detail

common.file_exists(repository_root: pathlib.Path, relative_path: str) → bool

Return whether a repository file exists.

Parameters:

repository_rootpathlib.Path

Root directory that contains the file.

relative_pathstr

File path relative to repository_root.

Returns:

bool

True when the path resolves to a regular file within the repository, otherwise False.

common.file_content(repository_root: pathlib.Path, relative_path: str) → str | None

Read a repository file (as UTF-8) without allowing path traversal.

Parameters:

repository_rootpathlib.Path

Root directory that contains the file.

relative_pathstr

File path relative to repository_root.

Returns:

str or None

File content, or None when the path is unsafe or the file cannot be read as UTF-8.

common.all_workflows_content(repository_root: pathlib.Path) → str | None

Return the merged text of the GitHub Actions workflow files.

Parameters:

repository_rootpathlib.Path

Root directory that contains .github/workflows.

Returns:

str or None

Contents of every readable .yml and .yaml file under .github/workflows, joined by newlines, or None when no such content exists.

common.readme_path(repository_root: pathlib.Path) → str | None

Return the preferred README path for a repository.

Parameters:

repository_rootpathlib.Path

Repository root directory.

Returns:

str or None

"README.rst" when present, otherwise "README.md" when present. None is returned when neither file exists.

common.normalize_check_result(raw_result: object, rule: _QualityRule) → tuple[RuleStatus, str]

Normalize a rule return value into a public status and detail.

Parameters:

raw_resultobject

Value returned by a rule check.

rule_QualityRule

Rule that produced raw_result.

Returns:

tuple[RuleStatus, str]

Public status and its display detail. Invalid return values are converted to ERROR.

common.PASSED: Final[RuleStatus]

common.WARNING: Final[RuleStatus]

common.ERROR: Final[RuleStatus]

type common.RuleCheckResult = bool | str