repomatic.lint_repo.context module

What the repository checks read, resolved once per run.

LintContext is the one context that lint-repo and setup-guide both read, so the two commands cannot disagree on a gate. It holds what the command alone knows (the repository it names, which secrets exist), the facts pyproject.toml states, and the [tool.repomatic] configuration.

Every remote read is a cached property: a check that never asks for one makes no call, and two checks asking for the same one share a single call.

repomatic.lint_repo.context.DOCS_URL_KEYS = ('documentation', 'docs')

Keys in [project.urls] naming the published documentation site.

Checked in priority order, and looked up in a lowercased index of the project’s own keys: PEP 621 leaves the spelling to the project, so Documentation, documentation and Docs all occur in the wild. Mirrors the same convention _SOURCE_URL_KEYS in repomatic.pypi applies to the PyPI copy of the same mapping.

repomatic.lint_repo.context.WRANGLER_TOML = PosixPath('wrangler.toml')

The root-level Wrangler configuration a Cloudflare Pages project may commit.

repomatic.lint_repo.context.documentation_url(project_urls)

The documentation site a project declares in [project.urls].

Parameters:

project_urls (Mapping[str, str] | None) – The [project.urls] mapping, keys untouched.

Return type:

str | None

Returns:

The first URL found per DOCS_URL_KEYS, or None when the project declares none.

class repomatic.lint_repo.context.LintContext(config=<factory>, repo=None, repo_name=None, package_name=None, is_package=False, is_sphinx=False, has_changelog=False, project_description=None, docs_url=None, keywords=None, tool_table=<factory>, nuitka_active=False, has_pat=False, has_virustotal_key=False, has_cloudflare_api_token=False, has_cloudflare_r2_keys=False, has_notifications_pat=False)

Bases: object

Everything the repository checks and the setup guide read.

Build it with from_project(), which reads the checkout the way the CLI does, or directly for a hand-assembled probe. The fields hold what is known before any check runs. The cached properties hold what a check reads on demand: a GitHub API call, a walk of the working tree, or a parse of the workflows.

config: Config

The resolved [tool.repomatic] configuration.

repo: str | None = None

Repository in owner/repo format.

None turns off every check that reads the GitHub API.

repo_name: str | None = None

The repository name, from --repo-name or the name part of repo.

package_name: str | None = None

The [project] name of pyproject.toml.

is_package: bool = False

Whether the project builds a distributable package.

Per repomatic.pyproject.is_python_package(). Gates the checks that only make sense for something actually published to PyPI.

is_sphinx: bool = False

Whether the project uses Sphinx documentation.

has_changelog: bool = False

Whether the configured changelog exists.

The release workflow publishes a GitHub release for each release commit, and only prepare-release writes one, from the changelog. So this is also whether the repository publishes GitHub releases, which is what the immutable releases setting protects.

project_description: str | None = None

Description from pyproject.toml.

docs_url: str | None = None

Documentation site declared in [project.urls], per DOCS_URL_KEYS.

keywords: list[str] | None = None

Keywords list from pyproject.toml.

tool_table: Mapping[str, Any]

The [tool] table of pyproject.toml, parsed.

nuitka_active: bool = False

Whether this project compiles binaries with Nuitka.

has_pat: bool = False

Whether REPOMATIC_PAT is configured.

has_virustotal_key: bool = False

Whether VIRUSTOTAL_API_KEY is configured.

has_cloudflare_api_token: bool = False

Whether CLOUDFLARE_API_TOKEN is configured.

has_cloudflare_r2_keys: bool = False

Whether CLOUDFLARE_R2_ACCESS_KEY_ID and CLOUDFLARE_R2_SECRET_ACCESS_KEY are both configured.

has_notifications_pat: bool = False

Whether REPOMATIC_NOTIFICATIONS_PAT is configured.

property slug: str

repo, for a check that runs only when it is set.

Raises:

ValueError – When no repository is named. A check reading the GitHub API declares that it needs one, so reaching this error means the check ran without its gate.

property owner: str

The owner part of slug.

property is_awesome: bool

Whether the repository is an awesome-* curated list.

property md: Metadata

CI and project context, for the repository identity the guide renders.

deploys_to(target)

Whether this repository publishes its site to target.

Routes through repomatic.config.deploys_to(): one host’s prerequisite is the other’s noise, and exactly one of them applies.

Return type:

bool

property repo_object: dict[str, Any] | None

The repository object of the GitHub REST API, read once.

One GET /repos/{repo} answers the description, the website field, the topics, the fork flag and the owner type, which four checks and the setup guide read. None when no repository is named or the read failed, which each reader reports as skipped rather than failed.

property rulesets: list[dict[str, Any]] | None

The repository’s rulesets, the ones inherited from a parent included.

One endpoint serves the two ruleset checks, which filter the same payload on different target values. A failed read is kept too: both checks then report the same unreadable API instead of asking twice.

Returns:

The ruleset list, or None when the API could not be read.

property declared_labels: frozenset[str] | None

Every label name the configured sources declare, per sync-labels.

Read here rather than inside the check so the check reads its expectation from the same place the sync writes it. Reading it fetches the labels.extra-files definitions. None when a label definition could not be fetched or read: the set is unknown rather than short, and the check reports skipped.

property pat_permissions: PatPermissionResults | None

The results of the PAT permission probes, or None without a PAT.

Both lint-repo and the setup guide read them, so they run once.

property pat_scope: CheckResult | None

The result of the PAT repository-scope probe, or None without a PAT.

property files: FileInventory

What the repository holds on disk, .gitignore applied.

The inventory of the Metadata singleton, so the checks share one walk of the tree with every other reader of the run.

property redirects_files: list[Path]

Committed Cloudflare Pages _redirects files, .gitignore honoured.

The gitignore filter is what keeps a generated site tree (an output/ or docs/_build/ copy of the same file) out of the audit: the engine replica must read the source of truth, not a build artifact of it.

property oversized_files: list[Path]

Tracked files over the Cloudflare Pages limit, .gitignore honoured.

Built trees stay out, like the _redirects inventory above: the deploy step reads those, and it names each file it moves or drops. The size rule is the one the deploy applies, from oversized_files().

property has_wrangler_toml: bool

Whether the repository commits a root-level wrangler.toml.

property workflow_texts: dict[Path, str]

Every workflow file’s raw text, read once for the whole run.

Some checks match the files as written, others parse them. Reading once here spares each check its own walk of .github/workflows/.

property workflows: dict[Path, dict[str, Any]]

The parsed workflows, from workflow_texts.

classmethod from_project(config, *, repo=None, repo_name=None, has_pat=False, has_virustotal_key=False, has_cloudflare_api_token=False, has_cloudflare_r2_keys=False, has_notifications_pat=False)

Resolve the project facts from the current checkout.

Everything pyproject.toml, the Metadata singleton and the configuration can answer is read here, so a command hands over only what it alone knows: which repository it names, and which secrets exist.

Parameters:

• config (Config) – The resolved [tool.repomatic] configuration.

• repo (str | None) – Repository in owner/repo format, or None.

• repo_name (str | None) – Repository name; derived from repo when omitted.

• has_pat (bool) – Whether REPOMATIC_PAT is configured.

• has_virustotal_key (bool) – Whether VIRUSTOTAL_API_KEY is configured.

• has_cloudflare_api_token (bool) – Whether CLOUDFLARE_API_TOKEN is configured.

• has_cloudflare_r2_keys (bool) – Whether both R2 upload secrets are configured.

• has_notifications_pat (bool) – Whether REPOMATIC_NOTIFICATIONS_PAT is configured.

Return type:

LintContext