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).
- class invocations.packaging.release.Changelog(value)¶
An enumeration.
- class invocations.packaging.release.Release(value)¶
An enumeration.
- class invocations.packaging.release.Tag(value)¶
An enumeration.
- class invocations.packaging.release.VersionFile(value)¶
An enumeration.
- 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
andpush
as well asprepare
.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.
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 builds and dist creation. Useful when running as a subroutine from
publish
which sets up a temporary directory.Up to two subdirectories may be created within this directory: one for builds (if building wheels), and one for the dist archives.
When
None
or another false-y value (which is the default), the current working directory is used (and thus, localdist/
andbuild/
subdirectories).python (str) –
Which Python binary to use when invoking
setup.py
.Defaults to
"python"
.If
wheel=True
, then this Python must havewheel
installed in its defaultsite-packages
(or similar) location.clean – Whether to clean out the build and dist directories before building.
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.
- 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
andpublish
.This uses the
twine
command under the hood, both its pre-uploadcheck
subcommand (which verifies the archives to be uploaded, including checking your PyPI readme) and theupload
one.All parameters save
dry_run
anddirectory
honor config settings of the same name, under thepackaging
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) –
Base directory within which will live the
dist/
andbuild/
directories.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
.Directory should either be a
dist
directory itself, or the parent of one.Uses the
venv
module to build temporary virtualenvs.
- 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 yourpypirc
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/SHAversion
.Specify the vendor folder (e.g.
<mypackage>/vendor
) asvendor_dir
.For Crate/PyPI releases,
package
should be the name of the software entry on those sites, andversion
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 andversion
should be a Git identifier (branch, tag, SHA etc.)git_url
must also be given, something suitable forgit 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.)