packaging

packaging.release

Python package release tasks.

This module assumes:

  • you’re using semantic versioning for your releases

  • you’re using a modern pyproject.toml for packaging metadata

invocations.packaging.release.all_(c, dry_run=False)

Catchall version-bump/tag/changelog/PyPI upload task.

Parameters:

dry_run (bool) – Handed to all subtasks which themselves have a dry_run flag.

Changed in version 2.1: Expanded functionality to run publish and push as well as prepare.

Changed in version 2.1: Added the dry_run flag.

invocations.packaging.release.build(c, sdist=True, wheel=True, directory=None, python=None, clean=False)

Build sdist and/or wheel archives, optionally in a temp base directory.

Uses the build tool from PyPA.

All parameters/flags honor config settings of the same name, under the packaging tree. E.g. say .configure({'packaging': {'wheel': False}}) to disable building wheel archives by default.

Parameters:

  • sdist (bool) – Whether to build sdists/tgzs. Default: True.

  • wheel (bool) – Whether to build wheels (requires the wheel package from PyPI). Default: True.

  • directory (str) – Allows specifying a specific directory in which to perform dist creation. Useful when running as a subroutine from publish which sets up a temporary directory. Defaults to the current working directory + dist/ (the same as pypa/build’s default behavior, albeit explicitly derived to support our own functionality).

  • clean – Whether to remove the dist directory before building.

  • python (str) –

    Which Python binary to use when invoking -m build.

    Defaults to "python".

    If wheel=True, then this Python must have wheel installed in its default site-packages (or similar) location.

Changed in version 2.0: clean now defaults to False instead of True, cleans both dist and build dirs when True, and honors configuration.

Changed in version 2.0: wheel now defaults to True instead of False.

Changed in version 4.0: Switched to using pypa/build and made related changes to args (eg, directory now only controls dist output location).

invocations.packaging.release.get_archives(directory: str | Path) → list[Path]

Obtain list of archive filenames, then ensure any wheels come first so their improved metadata is what PyPI sees initially (otherwise, it only honors the sdist’s lesser data).

invocations.packaging.release.prepare(c, dry_run=False)

Edit changelog & version, git commit, and git tag, to set up for release.

Parameters:

dry_run (bool) – Whether to take any actual actions or just say what might occur. Will also non-fatally exit if not on some form of release branch. Default: False.

Returns:

True if short-circuited due to all-ok, None otherwise.

Changed in version 2.1: Added the dry_run parameter.

Changed in version 2.1: Generate annotated git tags instead of lightweight ones.

invocations.packaging.release.publish(c, sdist=True, wheel=True, index=None, sign=False, dry_run=False, directory=None)

Publish code to PyPI or index of choice. Wraps build and upload.

This uses the twine command under the hood, both its pre-upload check subcommand (which verifies the archives to be uploaded, including checking your PyPI readme) and the upload one.

All parameters save dry_run and directory honor config settings of the same name, under the packaging tree. E.g. say .configure({'packaging': {'wheel': True}}) to force building wheel archives by default.

Parameters:

  • sdist (bool) – Whether to upload sdists/tgzs. Default: True.

  • wheel (bool) – Whether to upload wheels (requires the wheel package from PyPI). Default: True.

  • index (str) – Custom upload index/repository name. See upload help for details.

  • sign (bool) – Whether to sign the built archive(s) via GPG.

  • dry_run (bool) –

    Skip upload step if True.

    This also prevents cleanup of the temporary build/dist directories, so you can examine the build artifacts.

    Note that this does not skip the twine check step, just the final upload.

  • directory (str) –

    Used for build(directory=) and thus affects where dists go.

    Defaults to a temporary directory which is cleaned up after the run finishes.

invocations.packaging.release.push(c, dry_run=False)

Push current branch and tags to default Git remote.

invocations.packaging.release.status(c)

Print current release (version, changelog, tag, etc) status.

Doubles as a subroutine, returning the return values from its inner call to _converge (an (actions, state) two-tuple of Lexicons).

invocations.packaging.release.test_install(c, directory, verbose=False, skip_import=False)

Test installation of build artifacts found in $directory.

Uses the venv module to build temporary virtualenvs.

Parameters:

  • verbose (bool) – Whether to print subprocess output.

  • skip_import (bool) – If True, don’t try importing the installed module or checking it for type hints.

invocations.packaging.release.upload(c, directory, index=None, sign=False, dry_run=False)

Upload (potentially also signing) all artifacts in directory/dist.

Parameters:

  • index (str) –

    Custom upload index/repository name.

    By default, uses whatever the invoked pip is configured to use. Modify your pypirc file to add new named repositories.

  • sign (bool) – Whether to sign the built archive(s) via GPG.

  • dry_run (bool) –

    Skip actual publication step (and dry-run actions like signing) if True.

    This also prevents cleanup of the temporary build/dist directories, so you can examine the build artifacts.

packaging.vendorize

Tasks for importing external code into a vendor subdirectory.

invocations.packaging.vendorize.vendorize(c, distribution, version, vendor_dir, package=None, git_url=None, license=None)

Vendorize Python package distribution at version/SHA version.

Specify the vendor folder (e.g. <mypackage>/vendor) as vendor_dir.

For Crate/PyPI releases, package should be the name of the software entry on those sites, and version should be a specific version number. E.g. vendorize('lexicon', '0.1.2').

For Git releases, package should be the name of the package folder within the checkout that needs to be vendorized and version should be a Git identifier (branch, tag, SHA etc.) git_url must also be given, something suitable for git clone <git_url>.

For SVN releases: xxx.

For packages where the distribution name is not the same as the package directory name, give package='name'.

By default, no explicit license seeking is done – we assume the license info is in file headers or otherwise within the Python package vendorized. This is not always true; specify license=/path/to/license/file to trigger copying of a license into the vendored folder from the checkout/download (relative to its root.)