versionfinder
=============
.. image:: https://img.shields.io/github/forks/jantman/versionfinder.svg
:alt: GitHub Forks
:target: https://github.com/jantman/versionfinder/network
.. image:: https://img.shields.io/github/issues/jantman/versionfinder.svg
:alt: GitHub Open Issues
:target: https://github.com/jantman/versionfinder/issues
.. image:: https://secure.travis-ci.org/jantman/versionfinder.png?branch=master
:target: http://travis-ci.org/jantman/versionfinder
:alt: travis-ci for master branch
.. image:: https://codecov.io/github/jantman/versionfinder/coverage.svg?branch=master
:target: https://codecov.io/github/jantman/versionfinder?branch=master
:alt: coverage report for master branch
.. image:: https://readthedocs.org/projects/versionfinder/badge/?version=latest
:target: https://readthedocs.org/projects/versionfinder/?badge=latest
:alt: sphinx documentation for latest release
.. image:: http://www.repostatus.org/badges/latest/active.svg
:alt: Project Status: Active – The project has reached a stable, usable state and is being actively developed.
:target: http://www.repostatus.org/#active
Python package to find the version of another package/distribution, whether installed via pip, setuptools or git
Overview
--------
versionfinder 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.
Requirements
------------
* Python 3.5+
Usage
-----
Versionfinder 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 a ``pkg_resources`` or ``pip`` distribution 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. In ``mymodule.py``, a module within the "mypackage"
package/distribution:
.. code-block:: python
import logging
from versionfinder import find_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.
for lname in ['versionfinder', 'pip', 'git']:
l = logging.getLogger(lname)
l.setLevel(logging.CRITICAL)
l.propagate = True
class MyClass(object):
def __init__(self):
self._versioninfo = find_version('mypackage')
@property
def versioninfo(self):
return self._versioninfo
The ``_versioninfo`` attribute of the class will be set to the ``VersionInfo``
object returned by ``find_version()``. We can inspect some of that object's
properties, which are documented in the
`API docs <http://versionfinder.readthedocs.io/en/latest/versionfinder.versioninfo.html#versionfinder.versioninfo.VersionInfo>`_.
.. code-block:: pycon
>>> from mypackage.mymodule import MyClass
>>> c = MyClass()
>>> v = c.versioninfo
>>> v
VersionInfo(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_dirty
True
>>> 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 Requests
-------------------------
Bug reports and feature requests are happily accepted via the `GitHub Issue Tracker <https://github.com/jantman/versionfinder/issues>`_. Pull requests are
welcome. Issues that don't have an accompanying pull request will be worked on
as my time and priority allows.
Development
===========
To install for development:
1. Fork the `versionfinder <https://github.com/jantman/versionfinder>`_ repository on GitHub
2. Create a new branch off of master in your fork.
.. code-block:: bash
$ virtualenv versionfinder
$ cd versionfinder && source bin/activate
$ pip install -e git+git@github.com:YOURNAME/versionfinder.git@BRANCHNAME#egg=versionfinder
$ cd src/versionfinder
The git clone you're now in will probably be checked out to a specific commit,
so you may want to ``git checkout BRANCHNAME``.
Guidelines
----------
* pep8 compliant with some exceptions (see pytest.ini)
* 100% test coverage with pytest (with valid tests)
Testing
-------
Testing is done via `pytest <https://docs.pytest.org/en/latest/>`_, driven by `tox <https://tox.readthedocs.org/>`_.
* testing is as simple as:
* ``pip install tox``
* ``tox``
* If 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 -e py27 -- -v``
Acceptance Tests
----------------
Versionfinder has a suite of acceptance tests that create virtualenvs, install a
test package (`versionfinder-test-pkg <https://github.com/jantman/versionfinder-test-pkg>`_) in them,
and then call ``versionfinder.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, see ``versionfinder/tests/test_acceptance.py``.
Currently-tested scenarios are:
* Pip
* Install from local git clone
* Install editable from local git clone
* Install editable from local git clone then change a file (dirty)
* Install editable from local git clone then commit and tag
* Install editable from local git clone checked out to a tag
* Install editable from local git clone checked out to a commit
* Install editable from local git clone with multiple remotes
* Install from sdist
* Install from sdist with pip 1.5.4
* Install from wheel
* Install from git URL
* Install from git fork URL
* Install from git URL with commit
* Install from git URL with tag
* Install from git URL with branch
* Install editable from git URL
* Install editable from git fork URL
* Install editable from git URL with multiple remotes
* Install editable from git URL and then change a file in the clone (dirty)
* Install editable from git URL with commit
* Install editable from git URL with tag
* Install editable from git URL with branch
* Install sdist in a venv that's also a git repo
* Install wheel in a venv that's also a git repo
* setuptools / setup.py
* setup.py develop
* setup.py install
* easy_install
* Install from sdist
* Install from egg
* Install from source directory
* Install from sdist in a venv that's also a git repo
* Install from egg in a venv that's also a git repo
* Install from source directory in a venv that's also a git repo
Release Checklist
-----------------
1. Open an issue for the release; cut a branch off master for that issue.
2. Confirm that there are CHANGES.rst entries for all major changes.
3. Ensure that Travis tests passing in all environments.
4. Ensure that test coverage is no less than the last release (ideally, 100%).
5. Increment the version number in versionfinder/version.py and add version and release date to CHANGES.rst, then push to GitHub.
6. Confirm that README.rst renders correctly on GitHub.
7. Upload package to testpypi:
* Make sure your ~/.pypirc file is correct (a repo called ``test`` for https://testpypi.python.org/pypi)
* ``rm -Rf dist``
* ``python setup.py register -r https://testpypi.python.org/pypi``
* ``python setup.py sdist bdist_wheel``
* ``twine upload -r test dist/*``
* Check that the README renders at https://testpypi.python.org/pypi/versionfinder
8. Create a pull request for the release to be merged into master. Upon successful Travis build, merge it.
9. Tag the release in Git, push tag to GitHub:
* tag the release. for now the message is quite simple: ``git tag -a X.Y.Z -m 'X.Y.Z released YYYY-MM-DD'``
* push the tag to GitHub: ``git push origin X.Y.Z``
11. Upload package to live pypi:
* ``twine upload dist/*``
10. make sure any GH issues fixed in the release were closed.
License and Disclaimer
----------------------
This software is licensed under the `GNU Lesser General Public License (LGPL) 3.0 <https://www.gnu.org/licenses/lgpl-3.0.en.html>`_.
Raw data
{
"_id": null,
"home_page": "https://github.com/jantman/versionfinder",
"name": "versionfinder",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "version git pip pkg_resources setuptools",
"author": "Jason Antman",
"author_email": "jason@jasonantman.com",
"download_url": "https://files.pythonhosted.org/packages/1e/03/6ba20b4f6666e6d76db088c5f8f1ac73a21b00aa35719a2ec3ef77a4354c/versionfinder-1.1.1.tar.gz",
"platform": "",
"description": "versionfinder\n=============\n\n.. image:: https://img.shields.io/github/forks/jantman/versionfinder.svg\n :alt: GitHub Forks\n :target: https://github.com/jantman/versionfinder/network\n\n.. image:: https://img.shields.io/github/issues/jantman/versionfinder.svg\n :alt: GitHub Open Issues\n :target: https://github.com/jantman/versionfinder/issues\n\n.. image:: https://secure.travis-ci.org/jantman/versionfinder.png?branch=master\n :target: http://travis-ci.org/jantman/versionfinder\n :alt: travis-ci for master branch\n\n.. image:: https://codecov.io/github/jantman/versionfinder/coverage.svg?branch=master\n :target: https://codecov.io/github/jantman/versionfinder?branch=master\n :alt: coverage report for master branch\n\n.. image:: https://readthedocs.org/projects/versionfinder/badge/?version=latest\n :target: https://readthedocs.org/projects/versionfinder/?badge=latest\n :alt: sphinx documentation for latest release\n\n.. image:: http://www.repostatus.org/badges/latest/active.svg\n :alt: Project Status: Active \u2013 The project has reached a stable, usable state and is being actively developed.\n :target: http://www.repostatus.org/#active\n\nPython package to find the version of another package/distribution, whether installed via pip, setuptools or git\n\nOverview\n--------\n\nversionfinder is a library intended to identify the version/source details of a\nspecified Python distribution (usually the one calling it), whether it was\ninstalled via pip, setuptools or git. This is intended to allow packages to\ndetermine what version they are, beyond what is simply coded in the package:\n\n* For packages installed via pip, return the exact requirement that was installed,\n even if it was a source control URL (editable or not).\n* For packages installed via setuptools, return the installed version.\n* For packages that are a git clone, return the URL, commit, tag, and whether the\n repository is dirty (modified) or not.\n\nThis is mainly intended for projects that need to display their version information\nto users (i.e. for use in filing bug reports or support requests) and wish to be as\nspecific as possible, including whether the package was installed from a fork, a specific\ntag or commit from a git repo, or has local changes not committed to git.\n\nRequirements\n------------\n\n* Python 3.5+\n\nUsage\n-----\n\nVersionfinder is primarily intended to return information about the package/\ndistribution it is called from. As some operations can be quite a bit more time\nconsuming than simply reading a ``pkg_resources`` or ``pip`` distribution version,\nit's recommended that Versionfinder be run once during the startup or initialization\nof your application/process, and the result stored for later use.\n\nThe simplest example is finding the version information for whatever package/distribution\ncontains the calling module. In ``mymodule.py``, a module within the \"mypackage\"\npackage/distribution:\n\n.. code-block:: python\n\n import logging\n from versionfinder import find_version\n\n # If you are using the python logging module, you'll likely want to\n # suppress logging from versionfinder itself, as well as the DEBUG-level\n # logging from ``pip`` and ``git``, which are called by versionfinder.\n for lname in ['versionfinder', 'pip', 'git']:\n l = logging.getLogger(lname)\n l.setLevel(logging.CRITICAL)\n l.propagate = True\n\n class MyClass(object):\n\n def __init__(self):\n self._versioninfo = find_version('mypackage')\n\n @property\n def versioninfo(self):\n return self._versioninfo\n\nThe ``_versioninfo`` attribute of the class will be set to the ``VersionInfo``\nobject returned by ``find_version()``. We can inspect some of that object's\nproperties, which are documented in the\n`API docs <http://versionfinder.readthedocs.io/en/latest/versionfinder.versioninfo.html#versionfinder.versioninfo.VersionInfo>`_.\n\n.. code-block:: pycon\n\n >>> from mypackage.mymodule import MyClass\n >>> c = MyClass()\n >>> v = c.versioninfo\n >>> v\n VersionInfo(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)\n >>> v.pip_version\n '1.2.3'\n >>> v.pkg_resources_version\n '1.2.3'\n >>> v.version\n '1.2.3'\n >>> v.pip_url\n 'http://foo.com'\n >>> v.pkg_resources_url\n 'http://foo.com'\n >>> v.url\n 'http://foo.com'\n >>> v.pip_requirement\n 'git+https://github.com/someone/foo@v1.2.3#egg=foo'\n >>> v.git_remotes\n {'origin': 'https://github.com/someone/foo.git'}\n >>> v.git_remote\n 'https://github.com/someone/foo.git'\n >>> v.git_commit\n '123456ab'\n >>> v.git_tag\n 'v1.2.3'\n >>> v.git_is_dirty\n True\n >>> v.git_str\n 'git+https://github.com/someone/foo@v1.2.3#egg=foo*'\n >>> v.short_str\n '1.2.3 <http://foo.com>'\n >>> v.long_str\n '1.2.3 <http://foo.com> (git+https://github.com/someone/foo@v1.2.3#egg=foo*)'\n\nBugs and Feature Requests\n-------------------------\n\nBug reports and feature requests are happily accepted via the `GitHub Issue Tracker <https://github.com/jantman/versionfinder/issues>`_. Pull requests are\nwelcome. Issues that don't have an accompanying pull request will be worked on\nas my time and priority allows.\n\nDevelopment\n===========\n\nTo install for development:\n\n1. Fork the `versionfinder <https://github.com/jantman/versionfinder>`_ repository on GitHub\n2. Create a new branch off of master in your fork.\n\n.. code-block:: bash\n\n $ virtualenv versionfinder\n $ cd versionfinder && source bin/activate\n $ pip install -e git+git@github.com:YOURNAME/versionfinder.git@BRANCHNAME#egg=versionfinder\n $ cd src/versionfinder\n\nThe git clone you're now in will probably be checked out to a specific commit,\nso you may want to ``git checkout BRANCHNAME``.\n\nGuidelines\n----------\n\n* pep8 compliant with some exceptions (see pytest.ini)\n* 100% test coverage with pytest (with valid tests)\n\nTesting\n-------\n\nTesting is done via `pytest <https://docs.pytest.org/en/latest/>`_, driven by `tox <https://tox.readthedocs.org/>`_.\n\n* testing is as simple as:\n\n * ``pip install tox``\n * ``tox``\n\n* If 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 -e py27 -- -v``\n\nAcceptance Tests\n----------------\n\nVersionfinder has a suite of acceptance tests that create virtualenvs, install a\ntest package (`versionfinder-test-pkg <https://github.com/jantman/versionfinder-test-pkg>`_) in them,\nand then call ``versionfinder.find_version()`` from multiple locations in the package, printing a JSON-serialized\ndict of the results of each call (and an exception, if one was caught). For further information\non the acceptance tests, see ``versionfinder/tests/test_acceptance.py``.\n\nCurrently-tested scenarios are:\n\n* Pip\n\n * Install from local git clone\n * Install editable from local git clone\n * Install editable from local git clone then change a file (dirty)\n * Install editable from local git clone then commit and tag\n * Install editable from local git clone checked out to a tag\n * Install editable from local git clone checked out to a commit\n * Install editable from local git clone with multiple remotes\n * Install from sdist\n * Install from sdist with pip 1.5.4\n * Install from wheel\n * Install from git URL\n * Install from git fork URL\n * Install from git URL with commit\n * Install from git URL with tag\n * Install from git URL with branch\n * Install editable from git URL\n * Install editable from git fork URL\n * Install editable from git URL with multiple remotes\n * Install editable from git URL and then change a file in the clone (dirty)\n * Install editable from git URL with commit\n * Install editable from git URL with tag\n * Install editable from git URL with branch\n * Install sdist in a venv that's also a git repo\n * Install wheel in a venv that's also a git repo\n\n* setuptools / setup.py\n\n * setup.py develop\n * setup.py install\n\n* easy_install\n\n * Install from sdist\n * Install from egg\n * Install from source directory\n * Install from sdist in a venv that's also a git repo\n * Install from egg in a venv that's also a git repo\n * Install from source directory in a venv that's also a git repo\n\nRelease Checklist\n-----------------\n\n1. Open an issue for the release; cut a branch off master for that issue.\n2. Confirm that there are CHANGES.rst entries for all major changes.\n3. Ensure that Travis tests passing in all environments.\n4. Ensure that test coverage is no less than the last release (ideally, 100%).\n5. Increment the version number in versionfinder/version.py and add version and release date to CHANGES.rst, then push to GitHub.\n6. Confirm that README.rst renders correctly on GitHub.\n7. Upload package to testpypi:\n\n * Make sure your ~/.pypirc file is correct (a repo called ``test`` for https://testpypi.python.org/pypi)\n * ``rm -Rf dist``\n * ``python setup.py register -r https://testpypi.python.org/pypi``\n * ``python setup.py sdist bdist_wheel``\n * ``twine upload -r test dist/*``\n * Check that the README renders at https://testpypi.python.org/pypi/versionfinder\n\n8. Create a pull request for the release to be merged into master. Upon successful Travis build, merge it.\n9. Tag the release in Git, push tag to GitHub:\n\n * tag the release. for now the message is quite simple: ``git tag -a X.Y.Z -m 'X.Y.Z released YYYY-MM-DD'``\n * push the tag to GitHub: ``git push origin X.Y.Z``\n\n11. Upload package to live pypi:\n\n * ``twine upload dist/*``\n\n10. make sure any GH issues fixed in the release were closed.\n\nLicense and Disclaimer\n----------------------\n\nThis software is licensed under the `GNU Lesser General Public License (LGPL) 3.0 <https://www.gnu.org/licenses/lgpl-3.0.en.html>`_.\n\n",
"bugtrack_url": null,
"license": "",
"summary": "Python package to find the version of another package, whether installed via pip, setuptools or git.",
"version": "1.1.1",
"split_keywords": [
"version",
"git",
"pip",
"pkg_resources",
"setuptools"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "d7385bc965bf21a8d12a88b05a7242ff",
"sha256": "b17edbb0bfb79d50dfc68d3618d3244af90d3cb932b9dc7f139583694d725f2d"
},
"downloads": -1,
"filename": "versionfinder-1.1.1-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "d7385bc965bf21a8d12a88b05a7242ff",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 35020,
"upload_time": "2020-09-18T16:32:30",
"upload_time_iso_8601": "2020-09-18T16:32:30.158095Z",
"url": "https://files.pythonhosted.org/packages/85/2a/1611380aaf57f63a930c3dca3818f2a6422ba097ba280402b7351b7ae5c7/versionfinder-1.1.1-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "bcfd13e0a93fb1cdafa3a054ad9126e6",
"sha256": "157ad93efccf8f91ab094442526ea794f11c46d582cc6cd7a76dcfba20c805e6"
},
"downloads": -1,
"filename": "versionfinder-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "bcfd13e0a93fb1cdafa3a054ad9126e6",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 32539,
"upload_time": "2020-09-18T16:32:31",
"upload_time_iso_8601": "2020-09-18T16:32:31.955077Z",
"url": "https://files.pythonhosted.org/packages/1e/03/6ba20b4f6666e6d76db088c5f8f1ac73a21b00aa35719a2ec3ef77a4354c/versionfinder-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2020-09-18 16:32:31",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "jantman",
"github_project": "versionfinder",
"travis_ci": true,
"coveralls": true,
"github_actions": false,
"tox": true,
"lcname": "versionfinder"
}
JSON
