Package: tag2ver
tag2varEasy release management: file versioning, git commit, git tagging, and  optionally
Black, git remote, and PyPI.The nametag2varis meant to convey that the utility does everything from
git-tagging to file-versioning and all in between and either side. In particulartag2var:IfBlack(https://black.readthedocs.io/en/stable/index.html)
is installed will format all files with:black ..Updatespyandpyifile's__version__attribute with given incremented
semantic-version (https://semver.org).Updatesversionattribute ofsetup.pyas above (ifsetupexists).Git commits all modified files with given description.Git tags git repository with given version and given description.Pushes to remote git (if remote exists).Uploads toPyPIorTest PyPIwith-toption (ifsetup.pyexists).tag2veris careful to check everything before making changes, i.e. it is heavily
biased to finding and reporting an error before attempting any actions.The whole program is in the single file,tag2var.py, (without any dependencies outside
Python3.6+) and therefore this file alone can be copied to install the utility.Alternatively::pip install --upgrade tag2verBefore use with a remote git repository, e.g. GitHub, youmustcache your credentials
because you are not prompted.
Seehttps://stackoverflow.com/questions/5343068/is-there-a-way-to-cache-https-credentials-for-pushing-commitsfor how to cache credentials.
If you forget to cache credentials you will get a 128 error from thegit pushcommand.Help TextUsage fromfolder with git repository to tag and source files to version:python -m tag2ver [options] [<Major>.<Minor>.<Patch> "Release/commit Description."].Options (order of options not important):-hor--help, print short help message (rest of command line ignored).--versionprint version number oftag2ver(rest of command line ignored).-for--force, force the given git (not PyPI) version even if it is not a single
increment.-tor--test_pypi, useTest PyPIinstead ofPyPI(ifsetup.pyexists).
Passes--repository testpypionto twine (https://twine.readthedocs.io/en/latest/).-u <Username>or--username <Username>, forPyPI/Test PyPI(ifsetup.pyexists).
Passed onto twine (https://twine.readthedocs.io/en/latest/).Commonlyrequired with PyPI.-p <Password>or--password <Password>, forPyPI/Test PyPI(ifsetup.pyexists).
Passed onto twine (https://twine.readthedocs.io/en/latest/).Version in form .. (must be the 1st non-option):Must be a semantic version (https://semver.org) with format<Major>.<Minor>.<Patch>,
whereMajor,Minor, andPatchare positive integers or zero.Must be a single increment from previous git tag version, unless-foption given.If PyPI used must be at least one increment from PyPI version
(-fnot considered for PyPI version comparison).Use:<tag2ver dir>.tag2ver.py -f 0.0.0 "Add initial tag and version."(or similar), for 1st tagging in the repository (note 1)Leading zeros are allowed but ignored, e.g.00.00.00is the same as0.0.0.Leading plus not allowed, e.g.+0.0.0is an error.Note 1:Bothpyandpyifiles still need version attr (though it can be an empty string),
e.g.__version__ = ''.Similarlysetup, e.g.version='0.0.0'(must have a valid version though).Sincesetupmust contain a valid version the smallest version that can be in PyPI
is0.0.1(since version insetupmust be increased). In practice this isn't a
problem since much development happens before ready for PyPI and therefore version
already>0.0.0.Description usually in quotes (must be the 2nd non-option):Description of the version: a single, short, ideally < 50 characters, sentence with
an imperative mood (in double quotes to allow spaces).Actionstag2vertakes in order:Reformat all files withBlackifBlackinstalled.Checks git repository exists, if not exit.Checks version number isasingle increment from last git tag (except-foption)
and of form<Major>.<Minor>.<Patch>and description exists, if not exit.Checks if PyPI deployed (setup.pymust exist) (see note 2)Updates the__version__attribute of all thepy, exceptsetup.py(see above),
andpyifile's in the
current directory and subdirectories with given version
(__version__attributes must already exist in all files).Commits all modified files, includingpyandpyifilestag2verhas modified,
with given description.Tags the repository with given version and given description.Ifremoterepository exists, pushesorigintomaster.Ifsetup.pyexists, uploads toPyPI(orTest PyPIwith-toption) with given
version.
Username,-uor--username, and password,-por--password,
may optionally be specified.
(Upload uses twine (https://twine.readthedocs.io/en/latest/),
see link for other options for specifying username and password.)Note 2:Checks version number is at least one increment from last PyPI deployment
(regardless of-foption - PyPI versioning cannot be overridden).Updatessetup.py'sversionattribute with given version
(versionkwarg must already exist).EG:python -m tag2ver -hprints help.python -m tag2ver -f 0.0.0 "Add initial tag and version."for 1st release (note-fand note0.0.0cannot be pushed to PyPI).python -m tag2ver 0.0.1 "Fix bugs, tag, and version.".python -m tag2ver 0.1.0 "Add features, tag, and version.".python -m tag2ver 1.0.0 "Make incompatible changes, tag, and version.".python -m tag2ver -u <PyPI user name> 1.0.1 "Push to PyPI.".
Might need password as well, depending on twine
(https://twine.readthedocs.io/en/latest/) setup, and requiressetup.py.