zest.releaser is collection of command-line programs to help you automate the task of releasing a Python project.
It does away with all the boring bits. This is what zest.releaser automates for you:
It updates the version number. The version number can either be in
setup.py or version.txt or in a __version__ attribute in a
Python file or in setup.cfg. For example, it switches you from
0.3.dev0 (current development version) to 0.3 (release) to
0.4.dev0 (new development version).
It updates the history/changes file. It logs the release date on release and adds a new heading for the upcoming changes (new development version).
It tags the release. It creates a tag in your version control system named after the released version number.
It optionally uploads a source release to PyPI. It will only do this if the package is already registered there (else it will ask, defaulting to 'no'); zest releaser is careful not to publish your private projects!
First the three most important links:
The full documentation is at zestreleaser.readthedocs.io <https://zestreleaser.readthedocs.io>_.
We're on PyPI <https://pypi.org/project/zest.releaser>_, so we're only
an pip install zest.releaser away from installation on your computer.
The code is at github.com/zestsoftware/zest.releaser <https://github.com/zestsoftware/zest.releaser>_.
.. image:: https://img.shields.io/pypi/pyversions/zest.releaser? :alt: PyPI - Python Version .. image:: https://img.shields.io/pypi/implementation/zest.releaser? :alt: PyPI - Implementation
zest.releaser works on Python 3.8+, including PyPy3.
Tested until Python 3.11, but see tox.ini for the canonical place for that.
To be sure: the packages that you release with zest.releaser may
very well work on other Python versions: that totally depends on your
package.
We depend on:
setuptools for the entrypoint hooks that we offer.
colorama for colorized output (some errors printed in red).
twine for secure uploading via https to pypi. Plain setuptools doesn't
support this.
Since version 4.0 there is a recommended extra that you can get by
installing zest.releaser[recommended] instead of zest.releaser. It
contains a few trusted add-ons that we feel are useful for the great majority
of zest.releaser users:
wheel_ for creating a Python wheel that we upload to PyPI next to
the standard source distribution. Wheels are the official binary
distribution format for Python.
Since version 8.0.0a2 we always create wheels, except when you
explicitly switch this off in the config:
create-wheel = false.
If you are sure you want "universal" wheels, follow the directions from the
wheel documentation <https://wheel.readthedocs.io/en/stable/user_guide.html>_.
check-manifest_ checks your MANIFEST.in file for completeness,
or tells you that you need such a file. It basically checks if all
version controlled files are ending up the the distribution that we
will upload. This may avoid 'brown bag' releases that are missing
files.
pyroma_ checks if the package follows best practices of Python
packaging. Mostly it performs checks on the setup.py file, like
checking for Python version classifiers.
readme_renderer_ to check your long description in the same way as pypi does. No more unformatted restructured text on your pypi page just because there was a small error somewhere. Handy.
.. _wheel: https://pypi.org/project/wheel
.. _check-manifest: https://pypi.org/project/check-manifest
.. _pyroma: https://pypi.org/project/pyroma
.. _readme_renderer: https://pypi.org/project/readme_renderer
Just a simple pip install zest.releaser or easy_install zest.releaser is
enough. If you want the recommended extra utilities, do a pip install zest.releaser[recommended].
Alternatively, buildout users can install zest.releaser as part of a specific project's buildout, by having a buildout configuration such as::
[buildout]
parts =
scripts
[scripts]
recipe = zc.recipe.egg
eggs = zest.releaser[recommended]
Of course you must have a version control system installed. Since version 7, zest.releaser only supports git.
If you use Subversion (svn), Mercurial (hg), Git-svn, or Bazaar (bzr), please use version 6. If you really want, you can probably copy the relevant parts from the old code to a new package, and release this as an add-on package for zest.releaser. I suspect that currently it would only work with a monkey patch. If you are planning something, please open an issue, and we can see about making this part pluggable.
Zest.releaser gives you four commands to help in releasing python packages. They must be run in a version controlled checkout. The commands are:
prerelease: asks you for a version number (defaults to the current version minus a 'dev' or so), updates the setup.py or version.txt and the CHANGES/HISTORY/CHANGELOG file (with either .rst/.txt/.md/.markdown or no extension) with this new version number and offers to commit those changes to subversion (or bzr or hg or git).
release: copies the the trunk or branch of the current checkout and
creates a version control tag of it. Makes a checkout of the tag in a
temporary directory. Offers to register and upload a source dist
of this package to PyPI (Python Package Index). Note: if the package has
not been registered yet, it will not do that for you. You must register the
package manually (python setup.py register) so this remains a conscious
decision. The main reason is that you want to avoid having to say: "Oops, I
uploaded our client code to the internet; and this is the initial version
with the plaintext root passwords."
postrelease: asks you for a version number (gives a sane default), adds a development marker to it, updates the setup.py or version.txt and the CHANGES/HISTORY/CHANGELOG file with this and offers to commit those changes to version control. Note that with git and hg, you'd also be asked to push your changes (since 3.27). Otherwise the release and tag only live in your local hg/git repository and not on the server.
fullrelease: all of the above in order.
Note: markdown files should use the "underline" style of headings, not the
"atx" style where you prefix the headers with # signs.
There are some additional tools:
longtest: small tool that renders the long description and opens it in a web browser. Handy for debugging formatting issues locally before uploading it to pypi.
lasttagdiff: small tool that shows the diff of the current branch with the last released tag. Handy for checking whether all the changes are adequately described in the changes file.
lasttaglog: small tool that shows the log of the current branch since the last released tag. Handy for checking whether all the changes are adequately described in the changes file.
addchangelogentry: pass this a text on the command line and it will add this as an entry in the changelog. This is probably mostly useful when you are making the same change in a batch of packages. The same text is used as commit message. In the changelog, the text is indented and the first line is started with a dash. The command detects it if you use for example a star as first character of an entry.
bumpversion: do not release, only bump the version. A
development marker is kept when it is there. With --feature we
update the minor version. With option --breaking we update the
major version.
Reinout van Rees <http://reinout.vanrees.org>_ (Nelen & Schuurmans) is the
original author. He's still maintaining it, together with Maurits.
Maurits van Rees <http://maurits.vanrees.org>_ (Zest Software) added
a heapload of improvements and is the maintainer, together with Reinout.
Kevin Teague <http://bud.ca>_ (Canada's Michael Smith Genome Sciences
Center) added support for multiple version control systems, most notable
Mercurial.
Wouter vanden Hove <http://ugent.be>_ (University of Gent) added
support for uploading to multiple servers, using collective.dist.
Godefroid Chapelle <http://bubblenet.be>_ (BubbleNet) added /tag besides
/tags for subversion.
Richard Mitchell <https://github.com/mitchellrj>_
(Isotoma <https://www.isotoma.com/>_) added Python 3 support.
Mateusz Legięcki <https://github.com/Behoston>_ added a dockerfile for
much easier testing.
Eli Sallé <https://github.com/elisallenens>_ added pyproject.toml support
for zest.releaser's own options. We're modern now!
Fixed version handling documentation to use importlib instead of
pkg_resources.
[reinout]
Build distributions in an isolated environment.
Otherwise build cannot install packages needed for the build system, for example hatchling.
Fixes issue 448 <https://github.com/zestsoftware/zest.releaser/issues/448>_.
[maurits]
tox.ini uses extras = instead of deps = to
install the test extras.
[mtelka]upload-pypi option to false (default is
true).
[leplatrem]~/.pypirc config, read setup.cfg as well, as it might
override some of these values, like [distutils] index-servers.
Fixes issue #436. [maurits]Using newer 'build' (>=1.0.0) including a slight API change, fixes
#433. [reinout]
Typo fix in the readme: we look at __version__ instead of
the previously-documented __versions__... [reinout]
git seem to print everything to stderr,
leading us to think there are errors, but the exit code is zero, so it should be fine.
We do not want to ask too many questions, but we do not want to silently swallow important errors either.
[maurits]Updated contributors list.
Documenting hook_package_dir setting for entry points (which isn't
needed for most entry points, btw).
Fixes issue 370 <https://github.com/zestsoftware/zest.releaser/issues/370>_.
Allowing for retry for git push, which might fail because of a protected
branch. Also displaying that possible cause when it occurs. Fixes issue 385 <https://github.com/zestsoftware/zest.releaser/issues/385>_.
Ignore error output when calling build.
We only need to look at the exit code to see if it worked.
You can call zest.releaser with --verbose if you want
to see the possible warnings.
Removed encoding config option as nobody is using it anymore (using the
option would result in a crash). Apparently it isn't needed anymore now that
we don't use python 2 anymore. Fixes issue 391 <https://github.com/zestsoftware/zest.releaser/issues/391>_.
The longtest is now simpler. It runs readme_renderer and just displays
the result in the browser, without error handling. twine check should be
used if you want a real hard check (longtest --headless is
deprecated). The advantage is that longtest now also renders markdown
correctly. This adds readme_renderer[md] as dependency.
Fixes issue 363 <https://github.com/zestsoftware/zest.releaser/issues/363>_.
Changed build system to pypa/build instead of explicitly using setuptools.
Zest.releaser's settings can now also be placed in pyproject.toml.
Use native namespace packages for zest.releaser, instead of
deprecated pkg_resources based ones.
Added pre-commit config for neater code (black, flake8, isort).
Dropped support for python 3.7. Together with switching to build and
pyproject.toml, this warrants a major version bump.
Always create wheels, except when you explicitly switch this off in the config:
[zest.releaser] create-wheel = no.
If the wheel package is not available, we still do not create wheels.
Fixes issue 406 <https://github.com/zestsoftware/zest.releaser/issues/406>_.
[maurits]
Do not fail when tag versions cannot be parsed.
This can happen in lasttaglog, lasttagdiff, and bumpversion, with setuptools 66 or higher.
Fixes issue 408 <https://github.com/zestsoftware/zest.releaser/issues/408>_.
[maurits]
Drop support for Python 3.6. [maurits]
Support reading and writing the version in pyproject.toml.
See issue 295 <https://github.com/zestsoftware/zest.releaser/issues/295>,
issue 373 <https://github.com/zestsoftware/zest.releaser/issues/373>,
and PEP-621 <https://peps.python.org/pep-0621/>_,
[maurits]
run-pre-commit = yes / no.
Default: no.
When set to true, pre commit hooks are run.
This may interfere with releasing when they fail.
[maurits]Auto-detect history_format based on history filename.
[ericof]
Add history_format option, to explicitly set changelogs
entries in Markdown.
[ericof]
Add the bumpversion options to the postrelease command.
This means feature, breaking, and final.
[rnc, maurits]
Add --final option to bumpversion command.
This removes alpha / beta / rc markers from the version.
[maurits]
Add support for Python 3.11, remove z3c.testsetup from test dependencies. [maurits]
prefix-message = [TAG] to a [zest.releaser]
section in the setup.cfg of your package, or your global
~/.pypirc. Or add your favorite geeky quotes there.
[LvffY]prerelease, check with pep440 if the version is canonical.
Added pep440 to the recommended extra, not to the core dependencies:
zest.releaser can also be used for non-Python projects.
[maurits]--headless option to longtest.Big cleanup to ease future development:
Removed support for Subversion (svn), Bazaar (bzr), Mercurial (hg).
Removed support for Python 2 and 3.5.
Added support for Python 3.9 and 3.10.
Tested with Python 3.6-3.10 plus PyPy3.
Switched from Travis to GitHub Actions.
Simplified running commands by using subprocess.run.
.. # Note: for older changes see doc/sources/changelog.rst.
FAQs
Software releasing made easy and repeatable
We found that zest.releaser demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
In this segment of the Risky Business podcast, Feross Aboukhadijeh and Patrick Gray discuss the challenges of tracking malware discovered in open source softare.
Research
Security News
A threat actor's playbook for exploiting the npm ecosystem was exposed on the dark web, detailing how to build a blockchain-powered botnet.
Security News
NVD’s backlog surpasses 20,000 CVEs as analysis slows and NIST announces new system updates to address ongoing delays.