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 thepackaging
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, localdist/
andbuild/
subdirectories). - python (str) –
Which Python binary to use when invoking
setup.py
.Defaults to just
python
.If
wheel=True
, then this Python must havewheel
installed in its defaultsite-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
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.
- 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/
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
.
-
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 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 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.)