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
¶ An enumeration.
-
class
invocations.packaging.release.
Release
¶ An enumeration.
-
class
invocations.packaging.release.
Tag
¶ An enumeration.
-
class
invocations.packaging.release.
VersionFile
¶ 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.- sdist (bool) – Whether to build sdists/tgzs. Default:
-
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, dual_wheels=False, alt_python=None, check_desc=False)¶ 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.
- 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
(orpython2
, if you’re on Python 3 already) binary in your$PATH
. Also requires that this other python have thewheel
package installed in itssite-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 bepython3
orpython2
, depending on the currently active interpreter. - check_desc (bool) – Whether to run
setup.py check -r -s
(usesreadme_renderer
) before trying to publish - catches long_description bugs. Default:False
.
- sdist (bool) – Whether to upload sdists/tgzs. Default:
-
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)¶ Test installation of previously built artifacts found in
directory
.Uses the
venv
module to build temporary virtualenvs.
-
invocations.packaging.release.
tidelift
(c, dry_run=False)¶ Add current latest version to Tidelift & set changelog link.
-
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.
- index (str) –
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.)