packaging

packaging.release

Python package release tasks.

This module assumes:

  • you’re using semantic versioning for your releases
  • you maintain a file called $package/_version.py containing normal version conventions (__version_info__ tuple and __version__ string).
invocations.packaging.release.all_(c)

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

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

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

All parameters save 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 build sdists/tgzs.
  • wheel (bool) – Whether to build wheels (requires the wheel package from PyPI).
  • directory (str) –

    Allows specifying a specific directory in which to perform builds and dist creation. Useful when running as a subroutine from publish which sets up a temporary directory.

    Two subdirectories will be created within this directory: one for builds, and one for the dist archives.

    When None or another false-y value, the current working directory is used (and thus, local dist/ and build/ subdirectories).

  • python (str) –

    Which Python binary to use when invoking setup.py.

    Defaults to just python.

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

  • clean (bool) – Whether to clean out the local build/ folder before building.
invocations.packaging.release.prepare(c)

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

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

Publish code to PyPI or index of choice.

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.
  • wheel (bool) – Whether to upload wheels (requires the wheel package from PyPI).
  • 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 actual publication step if True.

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

  • directory (str) –

    Base directory within which will live the dist/ and build/ directories.

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

  • dual_wheels (bool) –

    When True, builds individual wheels for Python 2 and Python 3.

    Useful for situations where you can’t build universal wheels, but still want to distribute for both interpreter versions.

    Requires that you have a useful python3 (or python2, if you’re on Python 3 already) binary in your $PATH. Also requires that this other python have the wheel package installed in its site-packages; usually this will mean the global site-packages for that interpreter.

    See also the alt_python argument.

  • alt_python (str) –

    Path to the ‘alternate’ Python interpreter to use when dual_wheels=True.

    When None (the default) will be python3 or python2, depending on the currently active interpreter.

  • check_desc (bool) – Whether to run setup.py check -r -s (uses readme_renderer) before trying to publish - catches long_description bugs. Default: False.
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.upload(c, directory, index=None, sign=False, dry_run=False)

Upload (potentially also signing) all artifacts in directory.

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