Package: versionfinder
versionfinderPython package to find the version of another package/distribution, whether installed via pip, setuptools or gitOverviewversionfinder is a library intended to identify the version/source details of a
specified Python distribution (usually the one calling it), whether it was
installed via pip, setuptools or git. This is intended to allow packages to
determine what version they are, beyond what is simply coded in the package:For packages installed via pip, return the exact requirement that was installed,
even if it was a source control URL (editable or not).For packages installed via setuptools, return the installed version.For packages that are a git clone, return the URL, commit, tag, and whether the
repository is dirty (modified) or not.This is mainly intended for projects that need to display their version information
to users (i.e. for use in filing bug reports or support requests) and wish to be as
specific as possible, including whether the package was installed from a fork, a specific
tag or commit from a git repo, or has local changes not committed to git.RequirementsPython 3.5+UsageVersionfinder is primarily intended to return information about the package/
distribution it is called from. As some operations can be quite a bit more time
consuming than simply reading apkg_resourcesorpipdistribution version,
it’s recommended that Versionfinder be run once during the startup or initialization
of your application/process, and the result stored for later use.The simplest example is finding the version information for whatever package/distribution
contains the calling module. Inmymodule.py, a module within the “mypackage”
package/distribution:importloggingfromversionfinderimportfind_version# If you are using the python logging module, you'll likely want to# suppress logging from versionfinder itself, as well as the DEBUG-level# logging from ``pip`` and ``git``, which are called by versionfinder.forlnamein['versionfinder','pip','git']:l=logging.getLogger(lname)l.setLevel(logging.CRITICAL)l.propagate=TrueclassMyClass(object):def__init__(self):self._versioninfo=find_version('mypackage')@propertydefversioninfo(self):returnself._versioninfoThe_versioninfoattribute of the class will be set to theVersionInfoobject returned byfind_version(). We can inspect some of that object’s
properties, which are documented in theAPI docs.>>>frommypackage.mymoduleimportMyClass>>>c=MyClass()>>>v=c.versioninfo>>>vVersionInfo(git_commit=123456ab, git_is_dirty=True, git_remotes={'origin': 'https://github.com/someone/foo.git'}, git_tag=v1.2.3, pip_requirement=git+https://github.com/someone/foo@v1.2.3#egg=foo, pip_url=http://foo.com, pip_version=1.2.3, pkg_resources_url=http://foo.com, pkg_resources_version=1.2.3)>>>v.pip_version'1.2.3'>>>v.pkg_resources_version'1.2.3'>>>v.version'1.2.3'>>>v.pip_url'http://foo.com'>>>v.pkg_resources_url'http://foo.com'>>>v.url'http://foo.com'>>>v.pip_requirement'git+https://github.com/someone/foo@v1.2.3#egg=foo'>>>v.git_remotes{'origin': 'https://github.com/someone/foo.git'}>>>v.git_remote'https://github.com/someone/foo.git'>>>v.git_commit'123456ab'>>>v.git_tag'v1.2.3'>>>v.git_is_dirtyTrue>>>v.git_str'git+https://github.com/someone/foo@v1.2.3#egg=foo*'>>>v.short_str'1.2.3 <http://foo.com>'>>>v.long_str'1.2.3 <http://foo.com> (git+https://github.com/someone/foo@v1.2.3#egg=foo*)'Bugs and Feature RequestsBug reports and feature requests are happily accepted via theGitHub Issue Tracker. Pull requests are
welcome. Issues that don’t have an accompanying pull request will be worked on
as my time and priority allows.DevelopmentTo install for development:Fork theversionfinderrepository on GitHubCreate a new branch off of master in your fork.$virtualenvversionfinder$cdversionfinder&&sourcebin/activate$pipinstall-egit+git@github.com:YOURNAME/versionfinder.git@BRANCHNAME#egg=versionfinder$cdsrc/versionfinderThe git clone you’re now in will probably be checked out to a specific commit,
so you may want togit checkout BRANCHNAME.Guidelinespep8 compliant with some exceptions (see pytest.ini)100% test coverage with pytest (with valid tests)TestingTesting is done viapytest, driven bytox.testing is as simple as:pip install toxtoxIf you want to pass additional arguments to pytest, add them to the tox command line after “–”. i.e., for verbose pytext output on py27 tests:tox-epy27---vAcceptance TestsVersionfinder has a suite of acceptance tests that create virtualenvs, install a
test package (versionfinder-test-pkg) in them,
and then callversionfinder.find_version()from multiple locations in the package, printing a JSON-serialized
dict of the results of each call (and an exception, if one was caught). For further information
on the acceptance tests, seeversionfinder/tests/test_acceptance.py.Currently-tested scenarios are:PipInstall from local git cloneInstall editable from local git cloneInstall editable from local git clone then change a file (dirty)Install editable from local git clone then commit and tagInstall editable from local git clone checked out to a tagInstall editable from local git clone checked out to a commitInstall editable from local git clone with multiple remotesInstall from sdistInstall from sdist with pip 1.5.4Install from wheelInstall from git URLInstall from git fork URLInstall from git URL with commitInstall from git URL with tagInstall from git URL with branchInstall editable from git URLInstall editable from git fork URLInstall editable from git URL with multiple remotesInstall editable from git URL and then change a file in the clone (dirty)Install editable from git URL with commitInstall editable from git URL with tagInstall editable from git URL with branchInstall sdist in a venv that’s also a git repoInstall wheel in a venv that’s also a git reposetuptools / setup.pysetup.py developsetup.py installeasy_installInstall from sdistInstall from eggInstall from source directoryInstall from sdist in a venv that’s also a git repoInstall from egg in a venv that’s also a git repoInstall from source directory in a venv that’s also a git repoRelease ChecklistOpen an issue for the release; cut a branch off master for that issue.Confirm that there are CHANGES.rst entries for all major changes.Ensure that Travis tests passing in all environments.Ensure that test coverage is no less than the last release (ideally, 100%).Increment the version number in versionfinder/version.py and add version and release date to CHANGES.rst, then push to GitHub.Confirm that README.rst renders correctly on GitHub.Upload package to testpypi:Make sure your ~/.pypirc file is correct (a repo calledtestforhttps://testpypi.python.org/pypi)rm-Rfdistpython setup.py register-rhttps://testpypi.python.org/pypipython setup.py sdist bdist_wheeltwine upload-rtest dist/*Check that the README renders athttps://testpypi.python.org/pypi/versionfinderCreate a pull request for the release to be merged into master. Upon successful Travis build, merge it.Tag the release in Git, push tag to GitHub:tag the release. for now the message is quite simple:git tag-aX.Y.Z-m'X.Y.Z releasedYYYY-MM-DD'push the tag to GitHub:git push origin X.Y.ZUpload package to live pypi:twine upload dist/*make sure any GH issues fixed in the release were closed.License and DisclaimerThis software is licensed under theGNU Lesser General Public License (LGPL) 3.0.