Skip to content

API

Pyrig plugin that integrates PyPI publishing into a pyrig project.

rig

Mirrored namespace extending pyrig's project scaffolding for PyPI publishing.

configs

Configuration files this plugin adds or overrides for PyPI publishing.

Mirrors pyrig's config-file discovery namespace, so configurations defined here extend or override the base project's managed configuration.

pyproject

PyPI-specific extensions to the project's pyproject.toml configuration.

PyprojectConfigFile

Bases: PyprojectConfigFile

Pyproject config that adds PyPI trove classifiers and keywords.

classifiers_configs 
classifiers_configs() -> list[str]

Build the PyPI trove classifiers for the project.

Includes a Programming Language :: Python :: X.Y classifier for every Python minor version the project supports, alongside fixed classifiers declaring the project as Python 3 only, OS independent, and typed.

Returns:

Type Description
list[str]

Trove classifier strings for the project.classifiers field.
Source code in src/pyrig_pypi/rig/configs/pyproject.py 
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
def classifiers_configs(self) -> list[str]:
    """Build the PyPI trove classifiers for the project.

    Includes a `Programming Language :: Python :: X.Y` classifier for every
    Python minor version the project supports, alongside fixed classifiers
    declaring the project as Python 3 only, OS independent, and typed.

    Returns:
        Trove classifier strings for the `project.classifiers` field.
    """
    return [
        "Operating System :: OS Independent",
        "Programming Language :: Python :: 3 :: Only",
        *(
            f"Programming Language :: Python :: {v.major}.{v.minor}"
            for v in self.supported_python_versions()
        ),
        "Typing :: Typed",
    ]
keywords_configs 
keywords_configs() -> list[str]

Build the PyPI keywords for the project.

Returns:

Type Description
list[str]

A single-element list containing the pyrig executable name, to
list[str]

aid discoverability of the pyrig ecosystem in PyPI search.
Source code in src/pyrig_pypi/rig/configs/pyproject.py 
60
61
62
63
64
65
66
67
def keywords_configs(self) -> list[str]:
    """Build the PyPI keywords for the project.

    Returns:
        A single-element list containing the pyrig executable name, to
        aid discoverability of the pyrig ecosystem in PyPI search.
    """
    return [Pyrigger.I.name()]

version_control

PyPI-specific overrides of version control configuration.

remote

PyPI-specific overrides for the project's GitHub-hosted remote configuration.

configure

PyPI-specific extension of .github/configure.sh.

ConfigureRepositoryConfigFile

Bases: ConfigureRepositoryConfigFile

Configure script extended to sync the repository's GitHub topics.

apply_topics_function 
apply_topics_function() -> str

Return "topics", the function name.

Source code in src/pyrig_pypi/rig/configs/version_control/remote/configure.py 
43
44
45
def apply_topics_function(self) -> str:
    """Return `"topics"`, the function name."""
    return "topics"
apply_topics_script 
apply_topics_script() -> str

Return the topics shell function as a multi-line string.

Returns:

Type Description
str

Function definition that wraps the topics key of the settings
str

file into the body the GitHub topics endpoint expects, then
str

PUTs it to replace the repository's topics.
Source code in src/pyrig_pypi/rig/configs/version_control/remote/configure.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
    def apply_topics_script(self) -> str:
        """Return the `topics` shell function as a multi-line string.

        Returns:
            Function definition that wraps the `topics` key of the settings
            file into the body the GitHub topics endpoint expects, then
            `PUT`s it to replace the repository's topics.
        """
        settings_path = RepositorySettingsConfigFile.I.path().as_posix()
        topics_key = RepositorySettingsConfigFile.I.topics_key()
        endpoint = f"repos/${{{self.repo_variable()}}}/topics"
        extract = f"jq '{{names: .{topics_key}}}' {settings_path}"
        api_call = f'gh api "{endpoint}" --method=PUT --input=-'
        return f"""{self.apply_topics_function()}() {{
  {extract} | {api_call}
}}"""
scripts 
scripts() -> tuple[str, ...]

Add the topics function to the scripts this file defines.

Returns:

Type Description
tuple[str, ...]

The base scripts, plus apply_topics_script().
Source code in src/pyrig_pypi/rig/configs/version_control/remote/configure.py 
15
16
17
18
19
20
21
22
23
24
def scripts(self) -> tuple[str, ...]:
    """Add the `topics` function to the scripts this file defines.

    Returns:
        The base scripts, plus `apply_topics_script()`.
    """
    return (
        *super().scripts(),
        self.apply_topics_script(),
    )
settings

PyPI-specific extension of GitHub repository settings.

RepositorySettingsConfigFile

Bases: RepositorySettingsConfigFile

Repository settings config that mirrors PyPI keywords as GitHub topics.

topics_configs 
topics_configs() -> list[str]

Return the GitHub topics for the repository.

Returns:

Type Description
list[str]

The project's PyPI keywords, unmodified.
Source code in src/pyrig_pypi/rig/configs/version_control/remote/settings.py 
27
28
29
30
31
32
33
def topics_configs(self) -> list[str]:
    """Return the GitHub topics for the repository.

    Returns:
        The project's PyPI keywords, unmodified.
    """
    return PyprojectConfigFile.I.keywords_configs()
topics_key 
topics_key() -> str

Return "topics", the top-level key for the repository's GitHub topics.

Source code in src/pyrig_pypi/rig/configs/version_control/remote/settings.py 
35
36
37
def topics_key(self) -> str:
    """Return `"topics"`, the top-level key for the repository's GitHub topics."""
    return "topics"
workflows

PyPI-specific overrides of the project's GitHub Actions workflow configuration.

deploy

Deploy workflow extended to build the package and publish it to PyPI.

DeployWorkflowConfigFile

Bases: DeployWorkflowConfigFile

Deploy workflow that also builds the package and publishes it to PyPI.

job_package 
job_package() -> dict[str, Any]

Build the job that builds the package and publishes it to PyPI.

Returns:

Type Description
dict[str, Any]

Dict mapping the derived job ID to its configuration.
Source code in src/pyrig_pypi/rig/configs/version_control/remote/workflows/deploy.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
def job_package(self) -> dict[str, Any]:
    """Build the job that builds the package and publishes it to PyPI.

    Returns:
        Dict mapping the derived job ID to its configuration.
    """
    return self.job(
        self.job_package,
        permissions={
            **self.permission_contents(),
            **self.permission_id_token(write=True),
        },
        steps=self.steps_package(),
    )
jobs 
jobs() -> dict[str, Any]

Build the workflow's jobs, adding the package build-and-publish job.

Returns:

Type Description
dict[str, Any]

Dict mapping each job ID to its configuration.
Source code in src/pyrig_pypi/rig/configs/version_control/remote/workflows/deploy.py 
15
16
17
18
19
20
21
22
23
24
def jobs(self) -> dict[str, Any]:
    """Build the workflow's jobs, adding the package build-and-publish job.

    Returns:
        Dict mapping each job ID to its configuration.
    """
    return {
        **super().jobs(),
        **self.job_package(),
    }
step_build_package 
step_build_package() -> dict[str, Any]

Build a step that packages the project into distributable artifacts.

Runs uv build to produce wheel and source distributions in the dist/ directory.

Returns:

Type Description
dict[str, Any]

Step that runs uv build.
Source code in src/pyrig_pypi/rig/configs/version_control/remote/workflows/deploy.py 
54
55
56
57
58
59
60
61
62
63
64
65
66
def step_build_package(self) -> dict[str, Any]:
    """Build a step that packages the project into distributable artifacts.

    Runs `uv build` to produce wheel and source distributions in the
    `dist/` directory.

    Returns:
        Step that runs `uv build`.
    """
    return self.step(
        self.step_build_package,
        run=str(PackageManager.I.build_args()),
    )
step_publish_package 
step_publish_package() -> dict[str, Any]

Build a step that publishes the built distributions to PyPI.

Runs uv publish using GitHub Actions OIDC trusted publishing.

Returns:

Type Description
dict[str, Any]

Step that publishes to PyPI using trusted publishing.
Source code in src/pyrig_pypi/rig/configs/version_control/remote/workflows/deploy.py 
68
69
70
71
72
73
74
75
76
77
78
79
def step_publish_package(self) -> dict[str, Any]:
    """Build a step that publishes the built distributions to PyPI.

    Runs `uv publish` using GitHub Actions OIDC trusted publishing.

    Returns:
        Step that publishes to PyPI using trusted publishing.
    """
    return self.step(
        self.step_publish_package,
        run=str(PackageManager.I.published_trusted_args()),
    )
steps_package 
steps_package() -> list[dict[str, Any]]

Build the ordered steps for the package job.

Returns:

Type Description
list[dict[str, Any]]

Ordered list of step dicts: core setup, build the distributions,
list[dict[str, Any]]

then publish them to PyPI.
Source code in src/pyrig_pypi/rig/configs/version_control/remote/workflows/deploy.py 
41
42
43
44
45
46
47
48
49
50
51
52
def steps_package(self) -> list[dict[str, Any]]:
    """Build the ordered steps for the package job.

    Returns:
        Ordered list of step dicts: core setup, build the distributions,
        then publish them to PyPI.
    """
    return [
        *self.steps_core_setup(),
        self.step_build_package(),
        self.step_publish_package(),
    ]

tools

Tool wrappers this plugin adds or overrides for PyPI publishing.

packages

Tool wrappers this plugin adds or overrides for the project's PyPI package.

index

PyPI index integration for the project's badges and links.

PackageIndex

Bases: Tool

PyPI badge and metadata for the project's package index listing.

Badges the project with its current PyPI version and links to the project's PyPI page.

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

Return an empty tuple; pypi is not an installable dev dependency.

Source code in src/pyrig_pypi/rig/tools/packages/index.py 
14
15
16
def dev_dependencies(self) -> tuple[str, ...]:
    """Return an empty tuple; `pypi` is not an installable dev dependency."""
    return ()
group 
group() -> str

Return Group.PROJECT_INFO.

Source code in src/pyrig_pypi/rig/tools/packages/index.py 
18
19
20
def group(self) -> str:
    """Return `Group.PROJECT_INFO`."""
    return Group.PROJECT_INFO
image_url 
image_url() -> str

Return the shields.io badge URL for the project's current PyPI version.

Source code in src/pyrig_pypi/rig/tools/packages/index.py 
22
23
24
25
def image_url(self) -> str:
    """Return the shields.io badge URL for the project's current PyPI version."""
    repo = PackageManager.I.project_name()
    return f"https://img.shields.io/pypi/v/{repo}?logo=pypi&logoColor=white"
link_url 
link_url() -> str

Return the URL of the project's PyPI page.

Source code in src/pyrig_pypi/rig/tools/packages/index.py 
27
28
29
30
def link_url(self) -> str:
    """Return the URL of the project's PyPI page."""
    repo = PackageManager.I.project_name()
    return f"https://pypi.org/project/{repo}"
name 
name() -> str

Return "pypi".

Source code in src/pyrig_pypi/rig/tools/packages/index.py 
32
33
34
def name(self) -> str:
    """Return `"pypi"`."""
    return "pypi"
manager

Package manager tool wrapper customized for PyPI publishing.

Extends the base package manager tool with the arguments needed to publish a package to the PyPI index.

PackageManager

Bases: PackageManager

Package manager that adds PyPI publishing arguments to uv commands.

publish_args 
publish_args(*args: str) -> Args

Construct Args for publishing the package to PyPI.

Parameters:

Name Type Description Default
*args str

Additional arguments for the publish command.

 ()

Returns:

Type Description
Args

Args for uv publish <args...>.
Source code in src/pyrig_pypi/rig/tools/packages/manager.py 
14
15
16
17
18
19
20
21
22
23
def publish_args(self, *args: str) -> Args:
    """Construct `Args` for publishing the package to PyPI.

    Args:
        *args: Additional arguments for the publish command.

    Returns:
        Args for `uv publish <args...>`.
    """
    return self.args("publish", *args)
published_trusted_args 
published_trusted_args(*args: str) -> Args

Construct Args for PyPI trusted publishing with uv.

Parameters:

Name Type Description Default
*args str

Additional arguments for the publish command.

 ()

Returns:

Type Description
Args

Args for uv publish --trusted-publishing=always <args...>.
Source code in src/pyrig_pypi/rig/tools/packages/manager.py 
25
26
27
28
29
30
31
32
33
34
def published_trusted_args(self, *args: str) -> Args:
    """Construct `Args` for PyPI trusted publishing with uv.

    Args:
        *args: Additional arguments for the publish command.

    Returns:
        Args for `uv publish --trusted-publishing=always <args...>`.
    """
    return self.publish_args("--trusted-publishing=always", *args)

programming_language

PyPI-specific override of the project's Python language badge.

ProgrammingLanguage

Bases: ProgrammingLanguage

Programming language tool that badges the project with PyPI pyversions.

image_url 
image_url() -> str

Return the badge URL for the project's supported Python versions.

Source code in src/pyrig_pypi/rig/tools/programming_language.py 
12
13
14
15
16
def image_url(self) -> str:
    """Return the badge URL for the project's supported Python versions."""
    return (
        f"https://img.shields.io/pypi/pyversions/{PackageManager.I.project_name()}"
    )