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.

Source code in src/pyrig_pypi/rig/configs/pyproject.py

class PyprojectConfigFile(BasePyprojectConfigFile):
    """Pyproject config that adds PyPI trove classifiers and keywords."""

    def _configs(self) -> dict[str, Any]:
        """Add `classifiers` and `keywords` to the `project` table.

        Returns:
            The configuration dict, with the `project` table augmented.
        """
        configs = super()._configs()
        project = configs["project"]
        keys = list(project.keys())
        index = keys.index("dependencies")

        dict_insert_key(
            project,
            index=index,
            key="classifiers",
            value=sorted(self.classifiers_configs()),
        )
        dict_insert_key(
            project,
            index=index,
            key="keywords",
            value=sorted(self.keywords_configs()),
        )
        return configs

    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",
        ]

    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()]

classifiers_configs()

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

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()

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

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.

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.

Source code in src/pyrig_pypi/rig/configs/version_control/remote/workflows/deploy.py

class DeployWorkflowConfigFile(BaseDeployWorkflowConfigFile):
    """Deploy workflow that also builds the package and publishes it to PyPI."""

    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(),
        }

    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,
            steps=self.steps_package(),
        )

    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(),
        ]

    def step_build_package(
        self,
        *,
        step: dict[str, Any] | None = None,
    ) -> 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.

        Args:
            step: Additional keys to merge into the step configuration.

        Returns:
            Step that runs `uv build`.
        """
        return self.step(
            self.step_build_package,
            run=str(PackageManager.I.build_args()),
            step=step,
        )

    def step_publish_package(
        self,
        *,
        step: dict[str, Any] | None = None,
    ) -> dict[str, Any]:
        """Build a step that publishes the built distributions to PyPI.

        Runs `uv publish` authenticated with the `PYPI_TOKEN` secret, injected
        as the `${{ secrets.PYPI_TOKEN }}` expression.

        Args:
            step: Additional keys to merge into the step configuration.

        Returns:
            Step that publishes to PyPI using `PYPI_TOKEN`.
        """
        return self.step(
            self.step_publish_package,
            run=str(PackageManager.I.publish_args(token=self.insert_pypi_token())),
            step=step,
        )

    def insert_pypi_token(self) -> str:
        """Return the `${{ secrets.PYPI_TOKEN }}` expression.

        Returns:
            GitHub Actions expression for the `PYPI_TOKEN` secret.
        """
        return self.insert_expression(self.pypi_token_var())

    def pypi_token_var(self) -> str:
        """Return the raw secrets expression for `PYPI_TOKEN`.

        Returns:
            The `"secrets.PYPI_TOKEN"` expression string.
        """
        return self.secrets_var(PackageIndex.I.access_token_key())

insert_pypi_token()

Return the ${{ secrets.PYPI_TOKEN }} expression.

Returns:

Type	Description
str	GitHub Actions expression for the PYPI_TOKEN secret.

Source code in src/pyrig_pypi/rig/configs/version_control/remote/workflows/deploy.py

def insert_pypi_token(self) -> str:
    """Return the `${{ secrets.PYPI_TOKEN }}` expression.

    Returns:
        GitHub Actions expression for the `PYPI_TOKEN` secret.
    """
    return self.insert_expression(self.pypi_token_var())

job_package()

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

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,
        steps=self.steps_package(),
    )

jobs()

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

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(),
    }

pypi_token_var()

Return the raw secrets expression for PYPI_TOKEN.

Returns:

Type	Description
str	The "secrets.PYPI_TOKEN" expression string.

Source code in src/pyrig_pypi/rig/configs/version_control/remote/workflows/deploy.py

def pypi_token_var(self) -> str:
    """Return the raw secrets expression for `PYPI_TOKEN`.

    Returns:
        The `"secrets.PYPI_TOKEN"` expression string.
    """
    return self.secrets_var(PackageIndex.I.access_token_key())

step_build_package(*, step=None)

Build a step that packages the project into distributable artifacts.

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

Parameters:

Name	Type	Description	Default
step	dict[str, Any] | None	Additional keys to merge into the step configuration.	None

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

def step_build_package(
    self,
    *,
    step: dict[str, Any] | None = None,
) -> 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.

    Args:
        step: Additional keys to merge into the step configuration.

    Returns:
        Step that runs `uv build`.
    """
    return self.step(
        self.step_build_package,
        run=str(PackageManager.I.build_args()),
        step=step,
    )

step_publish_package(*, step=None)

Build a step that publishes the built distributions to PyPI.

Runs uv publish authenticated with the PYPI_TOKEN secret, injected as the ${{ secrets.PYPI_TOKEN }} expression.

Parameters:

Name	Type	Description	Default
step	dict[str, Any] | None	Additional keys to merge into the step configuration.	None

Returns:

Type	Description
dict[str, Any]	Step that publishes to PyPI using PYPI_TOKEN.

Source code in src/pyrig_pypi/rig/configs/version_control/remote/workflows/deploy.py

def step_publish_package(
    self,
    *,
    step: dict[str, Any] | None = None,
) -> dict[str, Any]:
    """Build a step that publishes the built distributions to PyPI.

    Runs `uv publish` authenticated with the `PYPI_TOKEN` secret, injected
    as the `${{ secrets.PYPI_TOKEN }}` expression.

    Args:
        step: Additional keys to merge into the step configuration.

    Returns:
        Step that publishes to PyPI using `PYPI_TOKEN`.
    """
    return self.step(
        self.step_publish_package,
        run=str(PackageManager.I.publish_args(token=self.insert_pypi_token())),
        step=step,
    )

steps_package()

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

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, links, and publish token name.

PackageIndex

Bases: Tool

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

Badges the project with its current PyPI version, links to the project's PyPI page, and names the environment variable holding the PyPI publish token.

Source code in src/pyrig_pypi/rig/tools/packages/index.py

class PackageIndex(Tool):
    """PyPI badge and metadata for the project's package index listing.

    Badges the project with its current PyPI version, links to the project's
    PyPI page, and names the environment variable holding the PyPI publish
    token.
    """

    def dev_dependencies(self) -> tuple[str, ...]:
        """Return an empty tuple; `pypi` is not an installable dev dependency."""
        return ()

    def group(self) -> str:
        """Return `Group.PROJECT_INFO`."""
        return Group.PROJECT_INFO

    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"

    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}"

    def name(self) -> str:
        """Return `"pypi"`."""
        return "pypi"

    def access_token_key(self) -> str:
        """Return `"PYPI_TOKEN"`, the env var name for the PyPI access token."""
        return "PYPI_TOKEN"

access_token_key()

Return "PYPI_TOKEN", the env var name for the PyPI access token.

Source code in src/pyrig_pypi/rig/tools/packages/index.py

def access_token_key(self) -> str:
    """Return `"PYPI_TOKEN"`, the env var name for the PyPI access token."""
    return "PYPI_TOKEN"

dev_dependencies()

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

Source code in src/pyrig_pypi/rig/tools/packages/index.py

def dev_dependencies(self) -> tuple[str, ...]:
    """Return an empty tuple; `pypi` is not an installable dev dependency."""
    return ()

group()

Return Group.PROJECT_INFO.

Source code in src/pyrig_pypi/rig/tools/packages/index.py

def group(self) -> str:
    """Return `Group.PROJECT_INFO`."""
    return Group.PROJECT_INFO

image_url()

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

Source code in src/pyrig_pypi/rig/tools/packages/index.py

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()

Return the URL of the project's PyPI page.

Source code in src/pyrig_pypi/rig/tools/packages/index.py

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()

Return "pypi".

Source code in src/pyrig_pypi/rig/tools/packages/index.py

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 publish arguments to the uv commands.

Source code in src/pyrig_pypi/rig/tools/packages/manager.py

class PackageManager(BasePackageManager):
    """Package manager that adds PyPI publish arguments to the uv commands."""

    def publish_args(self, *args: str, token: str) -> Args:
        """Construct `Args` for publishing the package to PyPI.

        Args:
            *args: Additional arguments for the publish command.
            token: PyPI authentication token.

        Returns:
            Args for `uv publish --token=<token> <args...>`.
        """
        return self.args("publish", f"--token={token}", *args)

publish_args(*args, token)

Construct Args for publishing the package to PyPI.

Parameters:

Name	Type	Description	Default
*args	str	Additional arguments for the publish command.	()
token	str	PyPI authentication token.	required

Returns:

Type	Description
Args	Args for uv publish --token=<token> <args...>.

Source code in src/pyrig_pypi/rig/tools/packages/manager.py

def publish_args(self, *args: str, token: str) -> Args:
    """Construct `Args` for publishing the package to PyPI.

    Args:
        *args: Additional arguments for the publish command.
        token: PyPI authentication token.

    Returns:
        Args for `uv publish --token=<token> <args...>`.
    """
    return self.args("publish", f"--token={token}", *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.

Source code in src/pyrig_pypi/rig/tools/programming_language.py

class ProgrammingLanguage(BaseProgrammingLanguage):
    """Programming language tool that badges the project with PyPI pyversions."""

    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()}"
        )

image_url()

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

Source code in src/pyrig_pypi/rig/tools/programming_language.py

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()}"
    )