API¶

Public-repository extensions for pyrig.

rig ¶

Public-repository overrides for pyrig's rig subsystem.

configs ¶

Configuration overrides for public repositories.

community ¶

Community policy overrides for public repositories.

security ¶

Configuration management for SECURITY.md files.

Manages SECURITY.md, the project's vulnerability-reporting policy.

SecurityConfigFile ¶

Bases: SecurityConfigFile

Override the default security policy for public repositories.

reporting_method ¶

reporting_method() -> str

Return a Markdown link to the repository's private reporting form.

Returns:

Type	Description
`str`	Link to GitHub's private vulnerability reporting form.

Source code in src/pyrig_public/rig/configs/community/security.py

def reporting_method(self) -> str:
    """Return a Markdown link to the repository's private reporting form.

    Returns:
        Link to GitHub's private vulnerability reporting form.
    """
    url = RemoteVersionController().security_advisory_url()
    return f"[GitHub's private vulnerability reporting]({url})"

docs ¶

Configuration management for the project's documentation site.

api ¶

Configuration manager for the API reference documentation page.

APIDocsConfigFile ¶

Bases: MarkdownConfigFile

Configuration manager for the API reference page (docs/api.md).

Generates a Markdown file that uses the mkdocstrings ::: directive to render full API documentation from the project's Python docstrings. The page contains an # API heading and a single ::: directive targeting the project's package, which mkdocstrings expands recursively into all public members, their signatures, docstrings, and source code.

content ¶

content() -> str

Return the Markdown content for the API reference page.

Source code in src/pyrig_public/rig/configs/docs/api.py

    def content(self) -> str:
        """Return the Markdown content for the API reference page."""
        return f"""# API

::: {PackageManager.I.package_name()}
"""

parent_path ¶

parent_path() -> Path

Return the DocsBuilder's documentation source directory.

Source code in src/pyrig_public/rig/configs/docs/api.py

def parent_path(self) -> Path:
    """Return the `DocsBuilder`'s documentation source directory."""
    return DocsBuilder.I.docs_dir()

stem ¶

stem() -> str

Return the filename stem "api".

Source code in src/pyrig_public/rig/configs/docs/api.py

def stem(self) -> str:
    """Return the filename stem `"api"`."""
    return "api"

version_control ¶

Version-control configuration overrides for public repositories.

remote ¶

GitHub repository configuration overrides.

configure ¶

Shell script that applies repository configuration via the GitHub CLI.

ConfigureRepositoryConfigFile ¶

Bases: ConfigureRepositoryConfigFile

Add public-repository settings to the GitHub setup script.

The additional script functions require maintainer approval for external contributors' pull request workflows and enable private vulnerability reporting.

fork_pr_contributor_approval_function ¶

fork_pr_contributor_approval_function() -> str

Return RepositorySettingsConfigFile.I.fork_pr_contributor_approval_key().

Named identically to the settings file key it reads, so both stay in sync automatically.

Source code in src/pyrig_public/rig/configs/version_control/remote/configure.py

def fork_pr_contributor_approval_function(self) -> str:
    """Return `RepositorySettingsConfigFile.I.fork_pr_contributor_approval_key()`.

    Named identically to the settings file key it reads, so both stay
    in sync automatically.
    """
    return RepositorySettingsConfigFile.I.fork_pr_contributor_approval_key()

fork_pr_contributor_approval_script ¶

fork_pr_contributor_approval_script() -> str

Return the fork_pr_contributor_approval shell function.

Returns:

Type	Description
`str`	Function definition that pipes the
`str`	`fork_pr_contributor_approval` key of the settings file into
`str`	`gh api` as a `PUT` request.

Source code in src/pyrig_public/rig/configs/version_control/remote/configure.py

    def fork_pr_contributor_approval_script(self) -> str:
        """Return the `fork_pr_contributor_approval` shell function.

        Returns:
            Function definition that pipes the
            `fork_pr_contributor_approval` key of the settings file into
            `gh api` as a `PUT` request.
        """
        settings_path = RepositorySettingsConfigFile.I.path().as_posix()
        key = RepositorySettingsConfigFile.I.fork_pr_contributor_approval_key()
        endpoint = (
            f'"repos/${{{self.repo_variable()}}}'
            '/actions/permissions/fork-pr-contributor-approval"'
        )
        api_call = RemoteVersionController.I.api_method_input_args(
            endpoint=endpoint,
            method="PUT",
            input_="-",
        )
        return f"""{self.fork_pr_contributor_approval_function()}() {{
  jq '.{key}' {settings_path} | {api_call}
}}"""

scripts ¶

scripts() -> tuple[str, ...]

Return base scripts and the public-repository policy scripts.

Returns:

Type	Description
`str`	The inherited scripts followed by fork-approval and
`...`	vulnerability-reporting functions.

Source code in src/pyrig_public/rig/configs/version_control/remote/configure.py

def scripts(self) -> tuple[str, ...]:
    """Return base scripts and the public-repository policy scripts.

    Returns:
        The inherited scripts followed by fork-approval and
        vulnerability-reporting functions.
    """
    return (
        *super().scripts(),
        self.fork_pr_contributor_approval_script(),
        self.vulnerability_reporting_script(),
    )

vulnerability_reporting_function ¶

vulnerability_reporting_function() -> str

Return "vulnerability_reporting", the function name.

Source code in src/pyrig_public/rig/configs/version_control/remote/configure.py

def vulnerability_reporting_function(self) -> str:
    """Return `"vulnerability_reporting"`, the function name."""
    return "vulnerability_reporting"

vulnerability_reporting_script ¶

vulnerability_reporting_script() -> str

Return the vulnerability_reporting shell function.

Returns:

Type	Description
`str`	Function definition that `PUT`s the GitHub API endpoint that
`str`	enables private vulnerability reporting for the repository.

Source code in src/pyrig_public/rig/configs/version_control/remote/configure.py

    def vulnerability_reporting_script(self) -> str:
        """Return the `vulnerability_reporting` shell function.

        Returns:
            Function definition that `PUT`s the GitHub API endpoint that
            enables private vulnerability reporting for the repository.
        """
        endpoint = (
            f'"repos/${{{self.repo_variable()}}}/private-vulnerability-reporting"'
        )
        api_call = RemoteVersionController.I.api_method_args(
            endpoint=endpoint,
            method="PUT",
        )
        return f"""{self.vulnerability_reporting_function()}() {{
  {api_call}
}}"""

settings ¶

Repository-level settings and protection ruleset configuration for GitHub.

RepositorySettingsConfigFile ¶

Bases: RepositorySettingsConfigFile

Override repository settings for public GitHub repositories.

fork_pr_contributor_approval_key ¶

fork_pr_contributor_approval_key() -> str

Return "fork_pr_contributor_approval".

The top-level key for the fork pull request contributor approval policy, i.e. which external contributors must be approved by a maintainer before their fork PR's workflows run.

Source code in src/pyrig_public/rig/configs/version_control/remote/settings.py

def fork_pr_contributor_approval_key(self) -> str:
    """Return `"fork_pr_contributor_approval"`.

    The top-level key for the fork pull request contributor approval
    policy, i.e. which external contributors must be approved by a
    maintainer before their fork PR's workflows run.
    """
    return "fork_pr_contributor_approval"

fork_pr_contributor_approval_policy ¶

fork_pr_contributor_approval_policy() -> str

Return the approval policy for fork pull request contributors.

Source code in src/pyrig_public/rig/configs/version_control/remote/settings.py

def fork_pr_contributor_approval_policy(self) -> str:
    """Return the approval policy for fork pull request contributors."""
    return "all_external_contributors"

settings ¶

settings() -> dict[str, Any]

Add public visibility and fork-PR approval to the base settings.

Returns:

Type	Description
`dict[str, Any]`	The inherited settings with public visibility and approval
`dict[str, Any]`	required for external contributors' fork pull request workflows.

Source code in src/pyrig_public/rig/configs/version_control/remote/settings.py

def settings(self) -> dict[str, Any]:
    """Add public visibility and fork-PR approval to the base settings.

    Returns:
        The inherited settings with public visibility and approval
        required for external contributors' fork pull request workflows.
    """
    configs = super().settings()
    configs[self.repository_key()]["visibility"] = self.visibility()
    configs[self.fork_pr_contributor_approval_key()] = {
        "approval_policy": self.fork_pr_contributor_approval_policy(),
    }
    return configs

visibility ¶

visibility() -> str

Return the visibility value applied to the repository.

Returns:

Type	Description
`str`	`public`, the visibility required by this public-repository plugin.

Source code in src/pyrig_public/rig/configs/version_control/remote/settings.py

def visibility(self) -> str:
    """Return the visibility value applied to the repository.

    Returns:
        `public`, the visibility required by this public-repository plugin.
    """
    return "public"

tools ¶

Tool overrides for public repositories.

version_control ¶

Version-control tool overrides for public repositories.

remote ¶

GitHub-specific remote version-control tools.

controller ¶

Identity, URL, and environment metadata for a repository's remote hosting service.

RemoteVersionController ¶

Bases: RemoteVersionController

Override the base remote version controller for public repositories.

security_advisory_url ¶

security_advisory_url() -> str

Construct the URL for filing a new private security advisory.

Returns:

Type	Description
`str`	URL in the format
`str`	`https://github.com/{owner}/{repo}/security/advisories/new`.

Source code in src/pyrig_public/rig/tools/version_control/remote/controller.py

def security_advisory_url(self) -> str:
    """Construct the URL for filing a new private security advisory.

    Returns:
        URL in the format
        `https://github.com/{owner}/{repo}/security/advisories/new`.
    """
    return f"{self.repo_url()}/security/advisories/new"