Package: jarn.mkrelease
mkreleaseis a no-frills Python package releaser. It is designed to take
the cumber out of building and distributing Python packages.
The releaser supports source distributions, eggs, and wheels.MotivationAfter preparing a package for release (update version strings, dates) we
typically have to:Commit modified files.Tag the release.Build a source distribution and wheel.Distribute the results via scp or upload them to an index server.If we are doing this a lot, the need for automation becomes obvious.ContentsInstallationUsageOptionsArgumentsConfigurationUpload with SCPUpload to Index ServersUsing GnuPGRequirementsFootnotesRelatedChangelogInstallationmkrelease works with Python 2.7 - 3.11 and all released versions of
setuptools.Usepip install jarn.mkreleaseto install themkreleasescript.Since version 4.4 mkrelease requirestwinefor register and upload
operations. Twine may be installed as a global utility on the system PATH or
into the same environment as jarn.mkrelease.[1]Usepip install jarn.mkrelease[twine]to install mkrelease + twine.Since version 5.0 file-finder extensions are no longer installed by default.
If you still want to use file-finders specify thefilefinderextra.Usepip install jarn.mkrelease[filefinder]to install mkrelease + file-finder
extensions.Usepip uninstallsetuptools-subversionsetuptools-hgsetuptools-gitto
uninstall file-finder extensions.Usagemkrelease [options][scm-sandbox|scm-url[rev]]Options-C,--no-commitDo not commit modified files from the sandbox.-T,--no-tagDo not tag the release in SCM.-P,--no-pushDo not push commits and tags upstream.-R,--no-registerDo not register the release with dist-location.-S,--no-uploadDo not upload the release to dist-location.-n,--dry-runDry-run; equivalent to-CTPRS. This flag turns mkrelease into a
simple package builder.--svn,--hg,--gitSelect the SCM type. Only required if the SCM type
cannot be guessed from the argument.-ddist-location,--dist-location=dist-locationAn scp destination specification, an index
server configured in~/.pypirc, or an alias name for
either. This option may be specified more than once.-s,--signSign the release with GnuPG.-iidentity,--identity=identityThe GnuPG identity to sign with. Implies-s.-z,--zipRelease a zip archive.-g,--gztarRelease a tar.gz archive (default).-b,--eggRelease a binary egg.-w,--wheelRelease a wheel file (default).-m,--manifest-onlyIgnore setuptools file-finder extensions and collect files viaMANIFEST.inonly.-e,--developAllow setuptools build tags. Implies-T.-q,--quietSuppress output of setuptools commands.-ttwine,--twine=twineOverride the twine executable used.-cconfig-file,--config-file=config-fileUse config-file instead of the default~/.mkrelease.-l,--list-locationsList known dist-locations and exit.-h,--helpPrint the help message and exit.-v,--versionPrint the version string and exit.--no-colorDisable output colors.--non-interactiveDo not prompt for username and password if the
required credentials are missing.Argumentsscm-sandboxA local SCM sandbox. Defaults to the current working
directory.scm-url[rev]The URL of a remote SCM repository. The optionalrevargument specifies a branch or tag to check out.Configurationmkrelease reads available index servers from thedistutilsconfiguration
file~/.pypirc. This file should contain your PyPI account information:[2][distutils]index-servers=pypi[pypi]repository=https://upload.pypi.org/legacy/username=fredpassword=secretNext, mkrelease reads its own configuration file~/.mkrelease.
It may be used to change defaults and to define location
aliases:[mkrelease]# Release stepscommit=yestag=yespush=yesregister=noupload=yes# One or more of: zip gztar egg wheelformats=gztar wheel# Setuptools optionsmanifest-only=yesdevelop=noquiet=no# Sign with GnuPGsign=noidentity=# Default dist-locationdist-location=[aliases]# Map name to one or more dist-locationscustomerA=jarn.com:/var/dist/customerA/public=jarn.com:/var/dist/public/world=pypipublicUpload with SCPThe simplest distribution location is a server directory reachable by ssh.
Releasing a package means scp-ing it to the appropriate place
on the server:$ mkrelease -d customerA
$ mkrelease -d jarn.com:/var/dist/customerB/
$ mkrelease -d scp://jarn.com/var/dist/customerC/
$ mkrelease -d stefan@jarn.com:eggs -C -e -qTo upload via sftp instead of scp, use thesftpURL scheme:$ mkrelease -d sftp://jarn.com/var/dist/customerD/Note: Unlike scp, the sftp client does not prompt for login credentials.
This means that non-interactive login must be configured on the
destination server or the upload will fail.Upload to Index ServersAnother way of publishing a Python package is by uploading it to a dedicated
index server likePyPI.
Given the~/.pypircfile from above, we can release to PyPI simply by typing:$ mkrelease -d pypiIndex servers are not limited to PyPI though.
There isTestPyPI, and there are alternative index servers likedevpi.
We extend our~/.pypirc:[2][distutils]index-servers=pypitestpypi[pypi]repository=https://upload.pypi.org/legacy/username=fredpassword=secret[testpypi]repository=https://test.pypi.org/legacy/username=fredpassword=secretWe can now release to TestPyPI with:$ mkrelease -d testpypi -C -eUsing GnuPGRelease a package and sign the distributions with GnuPG:$ mkrelease -d pypi -s -i fred@bedrock.comThe-iflag is optional and GnuPG will pick your default
key if not given.RequirementsThe following commands must be available on the system PATH (you only need
what you plan to use):svnhggitscpsftpgpgtwine[1]Footnotes[1](1,2)The twine executable is determined by trying in order:Value of--twinecommand line option, orValue ofTWINEenvironment variable, orValue oftwineconfiguration file setting, orpython-mtwineif twine is importable, ortwine[2](1,2)There are more secure ways to handle login credentials:Generate anAPI tokenon PyPI, and/orMake use of twine’skeyring support.RelatedAlso see our Python documentation viewerjarn.viewdoc.Changelog5.3 - 2023-09-23Update tox.ini for latest tox.
[stefan]Filter deprecated config warning.
[stefan]Fix invalid escape sequences.
[stefan]Therevpart of Git URLs no longer defaults to ‘master’.
[stefan]5.2 - 2023-01-20Support setuptools >= 65.6.0.
[stefan]5.1 - 2022-11-13Support Python 2.7 - 3.11.
[stefan]Do not require setup.py or setup.cfg if pyproject.toml exists.
[stefan]Filter some deprecation warnings.
[stefan]Disable twine progress bars in non-interactive mode.
[stefan]5.0 - 2022-02-26NEW: File finder extensions are no longer installed by default.
[stefan]NEW: push is now on by default
[stefan]NEW: register is now off by default
[stefan]NEW: formats now defaults to gztar + wheel
[stefan]Do not require setup.py if setup.cfg exists.
[stefan]Switch to the nose2 test runner for its fast multiprocessing plugin.
[stefan]4.4 - 2022-02-26Support Python 2.7 - 3.10.
[stefan]Support local distutils in setuptools >= 60.0.0.
[stefan]Add output colors.
[stefan]Requiretwinefor register and upload operations.
[stefan]Move metadata to setup.cfg.
[stefan]Move tests out ofjarn.mkreleasenamespace.
[stefan]Include tests in sdist but not in wheel.
[stefan]4.3 - 2019-01-28Fix issue #10: Can no longer run from a zc.buildout.
[stefan]Supportpython-mjarn.mkrelease.
[stefan]4.2 - 2019-01-25Drop Python 2.6 support, add Python 3.7.
[stefan]Update wheel and keyring dependencies.
[stefan]Add a complete config file example to the README.
[stefan]Acceptdist-locationas alias fordistdefaultin config files.
[stefan]Convert dashes to underscores in config parser optionxform.
[stefan]4.1 - 2017-10-06Add -m option to skip setuptools extensions.
[stefan]Never read existingSOURCES.txtfiles.
[stefan]Allow –egg as alias for –binary.
[stefan]4.0.1 - 2017-07-20Fix conditional include of keyring.
[stefan]4.0 - 2017-07-20Add support for source distributions in gztar format.
[stefan]Add support for wheel files.
[stefan]Allow multiple archive formats per release.
[stefan]Protect against bad or incomplete locale settings.
[stefan]The secondary thread would sometimes not terminate in Python 2.
[stefan]3.10 - 2017-02-01Support setuptools >= 33.1.0.
[stefan]3.9 - 2017-01-31Catch up with late-2016 PyPI API change.
[stefan]Add -R option to skip the register step.
[stefan]Support Python 2.6 - 3.6 without 2to3.
[stefan]Handle return code changes in Mercurial 3.1.1.
[stefan]3.8 - 2013-11-21Support Python 3.x.
[stefan]3.7 - 2012-08-22Fix compilation of Python source files when the -b option is given.
[stefan]Run check command as part of sdist and register commands.
[stefan]Add SFTP support.
[stefan]Allowsftp://andscp://URLs as dist-locations.
[stefan]3.6 - 2012-07-11Handle return code changes in Mercurial 2.1.
[stefan]Add setuptools-subversion dependency.
[stefan]Support Subversion 1.7 with the help of setuptools-subversion.
[stefan]3.5 - 2011-11-25Allow multiple values for thedistdefaultconfig file option.
[stefan]Defer list-locations until after all arguments have been parsed.
[stefan]Make tests run twice as fast by avoiding Subversion checkouts.
[stefan]3.4 - 2011-11-10Warn if -p is given but no upstream location is found.
[stefan]Always push to default in Mercurial.
[stefan]Avoid reading empty lines from terminating subprocesses.
[stefan]Fix bug in handling of distbase.
[stefan]3.3 - 2011-10-31Add setuptools to the PYTHONPATH for subprocesses.
[stefan]Unset any PYTHONPATH while executing SCM commands.
[stefan]Support Git’s short-formssh://URLs.
[stefan]Add -c option to specify a config file other than ~/.mkrelease.
[stefan]3.2 - 2011-10-21Fix the environment passed to subprocesses; Mercurial did not appreciate
the mangled PYTHONPATH.
[stefan]Allow to specify the branch or tag to check out from Git and Mercurial
repositories.
[stefan]Adapt to new status output in Subversion 1.6.
[stefan]Always includedistdefaultin list-locations.
[stefan]Detect Subversion repos fromfile://URLs.
[stefan]Detect bare Git repos fromfile://URLs.
[stefan]3.1 - 2011-07-19Pass the PYTHONPATH to subprocesses so mkrelease works in zc.buildout
environments.
[stefan]Improve SCM detection in situations where one or more SCMs are nested.
[stefan]Add support for relativefile:URLs.
[stefan]Depend onlazyinstead of carrying a local implementation.
[stefan]3.0.10 - 2011-07-07Add -l option to list known dist-locations (i.e. servers and aliases).
[stefan]Drop support for server URLs as dist-locations. Server URLs are
not unique.
[stefan]Update the Mercurial test repository so tagging tests don’t fail
under Mercurial 1.8.
[stefan]3.0.9 - 2010-12-31Rename[defaults]configuration file section to[mkrelease].
[stefan]Various internal code cleanups.
[stefan]3.0.8 - 2010-08-13Avoid underscores in dependency names.
[stefan]Handle return code changes in Mercurial 1.6.
[stefan]3.0.7 - 2010-07-07Improve documentation and error messages.
[stefan]3.0.5 - 2010-03-23Allow per-server configuration of -s and -i defaults.
[stefan]Support the codespeak.net Subversion repository layout.
[stefan]3.0.4 - 2010-03-16Status checks didn’t use the same path restrictions as commits
(Mercurial and Git.)
[stefan]3.0.3 - 2010-03-16Change how we check for existing tags in Subversion repositories.
[stefan]Make sandbox-status checks more robust in all three SCMs.
[stefan]3.0.2 - 2010-03-12Add support for Git 1.7.
[stefan]3.0.1 - 2010-02-07Stop when -d pypi is given but no configuration can be found.
[stefan]Usegnu_getoptto parse the command line.
[stefan]3.0 - 2010-01-15Switch to -n for dry-run to be consistent with other tools.
[stefan]Rename –skip-* long options to –no-* for the same reason.
[stefan]Fix a bug in Mercurial and Git sandbox detection.
[stefan]Prepare for standalone distutils.
[stefan]2.0.4 - 2010-01-10Improve Git support to handle remotes other than origin.
[stefan]Fix SCM detection inssh://URLs.
[stefan]2.0.3 - 2010-01-03Add -b option for releasing binary eggs.
[stefan]Don’t choke on dirty sandboxes when dry-running.
[stefan]2.0.2 - 2009-08-29Filter meta files (.svn*,.hg*,.git*) and never include
them in releases.
[stefan]Make sure to clean up all temporary files.
[stefan]2.0.1 - 2009-07-24Fixed bug which could cause mkrelease to issue eggs with faulty manifest
files (Symptom: data files not installed).
[stefan]The -e flag now implies -T. We never want to tag a development release.
[stefan]2.0 - 2009-07-16Allow command line options to appear after the argument. As in:mkrelease src/mypackage-q-dpypi.
[stefan]2.0b2 - 2009-07-09Improve user feedback in the SCM-detection part.
[stefan]Document the -e flag.
[stefan]Drop global configuration file for YAGNI.
[stefan]Allow to set default values for -s and -i in ~/.mkrelease.
[stefan]2.0b1 - 2009-07-03By default, ignore all version number extensions (dev-r12345)
that may be configured in setup.cfg. Passing the -e flag
disables this safeguard.
[witsch, stefan]Delete any existing signature file before signing anew. This keeps
GnuPG from complaining about existing (but left-over) files.
[stefan]2.0a2 - 2009-06-27Drop configurable Python and use sys.executable. This also means we
now require Python 2.6.
[stefan]Force setuptools to only use file-finders for the selected SCM type.
This is required to support multi-SCM sandboxes (think git-svn).
[stefan]Treat Subversion sandboxes just like the others and avoid the
temporary checkout step.
[stefan]Remove the -u flag for being pointless.
[stefan]2.0a1 - 2009-06-14Added support for Mercurial and Git.
[stefan]Added 250+ unit tests.
[stefan]1.0.2 - 2009-06-13Documented long options.
[stefan]Print a “Tagging …” line before tagging.
[stefan]1.0 - 2009-05-14Print help and version to stdout, not stderr.
[stefan]1.0b4 - 2009-04-30Since distutils commands may return 0, successful or not, we must
check their output for signs of failure.
[stefan]Allow to pass argument list tomain().
[stefan]1.0b3 - 2009-03-23No longer depend on grep.
[stefan]Use subprocess.Popen instead of os.system and os.popen.
[stefan]Protect against infinite alias recursion.
[stefan]Drop -z option and always create zip files from now on.
[stefan]1.0b2 - 2009-03-19Checkin everything that’s been modified, not just “relevant” files.
[stefan]Expand aliases recursively.
[stefan]1.0b1 - 2009-03-18The distbase and distdefault config file options no longer have
default values.
[stefan]Read index servers from ~/.pypirc and allow them to be used with -d.
[stefan]The -d option may be specified more than once.
[stefan]Dropped -p option. Use -d pypi instead.
[stefan]Dropped -c option. If your have non-standard SVN repositories you must
tag by hand.
[stefan]0.19 - 2009-02-23Absolute-ize the temp directory path.
[stefan]0.18 - 2009-01-26Include README.txt and CHANGES.txt in long_description.
[stefan]Rid unused imports and locals.
[stefan]0.17 - 2009-01-23Add -c option to enable codespeak support. The codespeak.net repository
usesbranchandtaginstead ofbranchesandtags.
[gotcha, stefan]0.16 - 2009-01-13Fold regex construction into find and make find a method.
[stefan]Update README.txt.
[stefan]0.15 - 2009-01-13Support for reading default options from a config file.
[fschulze, stefan]0.14 - 2009-01-08Add -s and -i options for signing PyPI uploads with GnuPG.
[stefan]Stop execution after any failing step.
[stefan]0.13 - 2009-01-05Stop execution when the checkin step fails.
[stefan]0.12 - 2009-01-02setup.cfg may not exist.
[stefan]0.11 - 2008-12-02Add setup.cfg to list of files we check in.
[stefan]0.10 - 2008-10-21Don’t capitalize GetOptError messages.
[stefan]0.9 - 2008-10-16Add -v option to print the script version.
[stefan]0.8 - 2008-10-16Lift restriction where only svn trunk could be released.
[stefan]0.7 - 2008-10-09Fix PyPI upload which must happen on the same command line as sdist.
[stefan]0.6 - 2008-10-08Update README.txt.
[stefan]0.5 - 2008-10-08Also locate and checkin HISTORY.txt to support ZopeSkel’ed eggs.
[stefan]0.4 - 2008-10-08Use svn checkout instead of svn export because it makes a difference
to setuptools.
[stefan]Add -p option for uploading to PyPI instead of dist-location.
[stefan]0.3 - 2008-10-06Also locate and checkin version.txt.
[stefan]0.2 - 2008-10-01Add -z option to create zip archives instead of the default tar.gz.
[stefan]0.1 - 2008-10-01Initial release
[stefan]