.. role:: bash(code)
:language: bash
.. role:: python(code)
:language: python
=============
version-query
=============
Zero-overhead package versioning for Python.
.. image:: https://img.shields.io/pypi/v/version-query.svg
:target: https://pypi.org/project/version-query
:alt: package version from PyPI
.. image:: https://github.com/mbdevpl/version-query/actions/workflows/python.yml/badge.svg?branch=main
:target: https://github.com/mbdevpl/version-query/actions
:alt: build status from GitHub
.. image:: https://codecov.io/gh/mbdevpl/version-query/branch/main/graph/badge.svg
:target: https://codecov.io/gh/mbdevpl/version-query
:alt: test coverage from Codecov
.. image:: https://api.codacy.com/project/badge/Grade/437ab82bd6324530847fe8ed833f8d78
:target: https://app.codacy.com/gh/mbdevpl/version-query
:alt: grade from Codacy
.. image:: https://img.shields.io/github/license/mbdevpl/version-query.svg
:target: https://github.com/mbdevpl/version-query/blob/v1.5.4/NOTICE
:alt: license
Package versioning toolkit for Python which relies on git tags, git history traversal
and status of git repository to generate a very fine-grained version number.
Aren't you tired hardcoding the version numbers when maintaining a Python package?!
And wouldn't you like have fine-grained versioning scheme with version changing with each commit,
for easier development, testing and pre-release deployment?!
Search no more!
As long as you mark your releases using git tags, instead of hardcoding:
.. code:: python
__version__ = '1.5.0.dev2'
You can do:
.. code:: python
from version_query import predict_version_str
__version__ = predict_version_str()
It's 21st century, stop hardcoding version numbers!
This will set the version to release version when you really release a new version,
and it will automatically generate a suitable development version at development/pre-release phase.
.. contents::
:backlinks: none
Overview
========
At development time, the current version number is automatically generated based on:
* tags
* current commit SHA
* index status
in your git repository. Therefore the package can be built and shipped to PyPI based only on status
of the git repository. When there is no git repository (this might be the case at installation time
or at runtime) then the script relies on metadata generated at packaging time.
That's why, regardless if package is installed from PyPI (from source or wheel distribution)
or cloned from GitHub, the version query will work.
Additionally, version numbers in version-query are mutable objects and they can be conveniently
incremented, compared with each other, as well as converted to/from other popular
versioning formats.
Versioning scheme
=================
Version scheme used by version-query is a relaxed mixture of:
* `Semantic Versioning 2.0.0 <http://semver.org/>`_ and
* `PEP 440 -- Version Identification and Dependency Specification <https://www.python.org/dev/peps/pep-0440/>`_.
These two rulesets are mostly compatible. When they are not, a more relaxed approach of the two
is used. Details follow.
Version has one of the following forms:
* ``<release>``
* ``<release><pre-release>``
* ``<release>+<local>``
* ``<release><pre-release>+<local>``
A release version identifier ``<release>`` has one of the following forms:
* ``<major>``
* ``<major>.<minor>``
* ``<major>.<minor>.<patch>``
And the pre-release version identifier ``<pre-release>`` has one of the following forms:
* ``<pre-type>``
* ``<pre-type><pre-patch>``
* ``<pre-separator><pre-type>``
* ``<pre-separator><pre-patch>``
* ``<pre-separator><pre-type><pre-patch>``
* ... and any of these forms can be repeated arbitrary number of times.
And finally the local version identifier ``<local>`` has one of the forms:
* ``<local-part>``
* ``<local-part><local-separator><local-part>``
* ``<local-part><local-separator><local-part><local-separator><local-part>``
* ... and so on.
Each version component has a meaning and constraints on its contents:
* ``<major>`` - a non-negative integer, increments when backwards-incompatible changes are made
* ``<minor>`` - a non-negative integer, increments when backwards-compatible features are added
* ``<patch>`` - a non-negative integer, increments when backwards-compatible bugfixes are made
* ``<pre-separator>`` - dot or dash, separates release version information from pre-release
* ``<pre-type>`` - a string of lower-case alphabetic characters, type of the pre-release
* ``<pre-patch>`` - a non-negative integer, revision of the pre-release
* ``<local-part>`` - a sequence of alphanumeric characters, stores arbitrary information
* ``<local-separator>`` - a dot or dash, separates parts of local version identifier
How exactly the version number is determined
--------------------------------------------
The version-query package has two modes of operation:
* *query* - only currently available explicit information is used to determine the version number
* *prediction* - this applies only to determining version number from git repository, and means
that in addition to explicit version information, git repository status can be used
to get very fine-grained version number which will be unique for every repository snapshot
Version query from package metadata file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The metadata file (``PKG-INFO`` or ``metadata.json`` or ``METADATA``) is automatically generated
whenever a Python distribution file is built.
Which one, depends on your method of building, but in any case, the file is then packaged into
distributions, and when uploaded to PyPI that metadata file is used to populate
the package page - therefore all Python packages on PyPI should have it.
Additionally, source code folder of any package using setuptools, in which ``setup.py build``
was executed, contains metadata file -- even if distribution file was not built.
The version identifier is contained verbatim in the metadata file, therefore version query
in this case boils down to simply reading the metadata file.
Information about Python metadata files:
* `PEP 345 -- Metadata for Python Software Packages 1.2 <https://www.python.org/dev/peps/pep-0345/>`_,
which replaced `PEP 314 -- Metadata for Python Software Packages v1.1 <https://www.python.org/dev/peps/pep-0314/>`_,
which in turn replaced `PEP 241 -- Metadata for Python Software Packages <https://www.python.org/dev/peps/pep-0241/>`_.
According to PEP 345, version of package should conform to what has been defined in PEP 440.
* `PEP 566 -- Metadata for Python Software Packages 2.1 <https://www.python.org/dev/peps/pep-0566/>`_
which replaced the PEP 345. This new standard doesn't however modify the version handling
in any way other than ensuring that requirements specification conforms with PEP 508,
which is not related to Python package version querying.
Version query from git repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The version number is equal to the version contained in the most recent version tag.
Version tags
````````````
Any git tag that is a valid version (matching the rules above) is considered a version tag.
Version number can be prefixed with ``v`` or ``ver``. Other tags are ignored.
Examples of valid version tags:
* ``v1.0``
* ``v0.16.0``
* ``v1.0.dev3``
* ``ver0.5.1-4.0.0+gita1de3012``
* ``42.0``
* ``3.14-15``
Most recent version tag
```````````````````````
The most recent tag is found based on repository history and version precedence.
Search for version tags starts from current commit, and goes backwards in history (towards initial
commit). Therefore, commits after current one as well as not-merged branches are ignored in the
version tag search.
If there are several version tags on one commit, then highest version number is used.
If there are version tags on several merged branches, then the highest version number is used.
If there are no version tags in the repository, you'll get an error - so version cannot be queried
from git repository without any version tags.
But in such case, version can still be *predicted*, as described below.
Version prediction from git repository
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In version prediction mode, first of all, a most recent version tag is found, as above.
If there are no version tags in the repo, then the initial commit is assumed to have tag
``v0.1.0.dev0``.
Then, the new commits since the most recent version tag are counted.
Then, the repository index status is queried. All the results are combined to form
the predicted version number. Procedure is described below in detail.
Counting new commits
````````````````````
If after the commit with the most recent tag there are any new commits, a suffix ``.dev#``
is appended to the version identifier, where ``#`` is the number of commits between
the current commit and the most recent version tag.
Additionally, the ``<patch>`` version component is incremented by ``1``.
Additionally, a plus (``+``) character, word ``git`` and the first 8 characters of SHA
of the latest commit are appended to version identifier, e.g. ``+gita3014fe0``.
Repository index status
```````````````````````
Additionally, if there are any uncommitted changes in the repository (i.e. the repo is *dirty*),
the suffix ``.dirty`` followed by current date and time in format ``YYYYMMDDhhmmss`` are appended
to the identifier.
Example of how the final version identifier looks like, depending on various conditions
of the repository:
* Most recent version tag is ``v0.4.5``, there were 2 commits since,
latest having SHA starting with ``812f12ea``.
Version identifier will be ``0.4.6.dev2+git812f12ea``.
* Most recent version tag is ``ver6.0``, and there was 1 commit since
having SHA starting with ``e10ac365``.
Version identifier will be ``6.0.1.dev1+gite10ac365``.
* Most recent version tag is ``v9``, there were 40 commit since,
latest having SHA starting with ``1ad22355``, the repository has uncommitted changes and
version was queried at 19:52.20, 8th June 2017.
the result is ``9.0.1.dev40+git1ad22355.dirty20170608195220``.
How exactly version numbers are compared
----------------------------------------
The base specification of the comparison scheme is:
* `PEP 508 -- Dependency specification for Python Software Packages <https://www.python.org/dev/peps/pep-0508/>`_ as well as
* `Semantic Versioning 2.0.0 <http://semver.org/>`_.
With the notable difference to both that all version components are taken into account when
establishing version precedence.
When being compared, ``<major>``, ``<minor>`` and ``<patch>`` are assumed equal to ``0`` if they
are not present. In ``<pre-release>``, the ``<pre-patch>`` is assumed to be ``0`` if not present.
Examples of comparison results:
* ``0.3-4.4-2.9`` < ``0.3-4.4-2.10``
* ``0.3dev`` < ``0.3dev1``
* ``0.3rc2`` < ``0.3``
* ``0.3`` < ``0.3-2``
* ``1.0.0`` < ``1.0.0+blahblah``
* ``1.0.0+aa`` < ``1.0.0+aaa``
* ``1.0.0`` = ``1.0.0``
* ``1`` = ``1.0.0``
* ``1.0`` = ``1.0.0.0``
* ``1.0.0-0.0.DEV42`` = ``1.0.0.0.0.dev42``
How exactly version number is incremented
-----------------------------------------
Some version components have assumed value ``0`` if they are not present, please see section above
for details.
Incrementing any version component clears all existing following components.
Examples of how version is incremented:
* for ``1.5``, incrementing ``<major>`` results in ``2.0``;
* for ``1.5.1-2.4``, ``<minor>``++ results in ``1.6``;
* ``1.5.1-2.4``, ``<patch>``++, ``1.5.2``;
* ``1.5.1``, ``<major>``+=3, ``4.0.0``.
API details
===========
All functionality mentioned below is considered as the public API. Other functionality may change
without notice.
Main API
--------
.. code:: python
import version_query
version_str = version_query.query_version_str()
The version-query package will query the version string while operating in *query* mode.
.. code:: python
version_str = version_query.predict_version_str()
The version-query package will infer the version string while operating in *prediction* mode.
.. code:: python
version = version_query.Version(1, 0, 4)
version = version_query.Version(major=1, patch=4)
version = version_query.Version.from_str('1.0.4')
The Version class is used internally by version-query, but it can be also used explicitly.
.. code:: python
import packaging.version
version = version_query.Version.from_py_version(packaging.version.Version())
version.to_py_version()
import semver
version = version_query.Version.from_sem_version(semver.VersionInfo())
version.to_sem_version()
Also, Version class interoperates with ``packaging`` and ``semver`` packages as well as selected
built-in types.
.. code:: python
assert version_query.Version(1, 0, 4).increment(version_query.VersionComponent.Patch, 2) \
== version_query.Version.from_str('1.0.6')
assert version_query.Version.from_str('1.0.4') < version_query.Version.from_str('2.0.0')
The Version objects are mutable, hashable and comparable.
.. code:: python
version = version_query.query_folder(pathlib.Path('/my/project'), search_parent_directories=False)
version = version_query.predict_git_repo(pathlib.Path('/my/git/versioned/project/subdir'), True)
version = version_query.query_caller(stack_level=1)
version = version_query.predict_caller(2)
Version object can be obtained for any supported path, as well as for any python code
currently being executed -- as long as it is located in a supported location.
Command-line interface
----------------------
.. code:: bash
python3 -m version_query --help
python3 -m version_query /my/project -p
.. code:: python
version_query.__main__.main(args=['--help'])
version_query.__main__.main(args=['/my/project', '-p'])
Version query can be also used as a command-line script, with the entry point also accessible
as ``version_query.__main__.main`` from within Python.
Utility functions
-----------------
.. code:: python
assert version_query.git_query.preprocess_git_version_tag('v1.0.4') == '1.0.4'
assert version_query.git_query.preprocess_git_version_tag('ver1.0.4') == '1.0.4'
assert version_query.git_query.preprocess_git_version_tag('1.0.4') == '1.0.4'
Remove ``v`` and ``ver`` prefix from a given string, and preform very crude checking whether
the tag is probably a version tag.
Limitations
===========
Either git repository or metadata file must be present for the script to work. When, for example,
zipped version of repository is downloaded from GitHub, the resulting archive contains neither
metadata files nor repository data.
It is unclear what happens if the queried repository is bare.
The implementation is not fully compatible with Python versioning. Especially,
in current implementation at most one of:
alpha ``a`` / beta ``b`` / release candidate ``rc`` / development ``dev`` suffixes
can be used in a version identifier.
And the format in which
alpha ``a``, beta ``b`` and release candidate ``rc`` suffixes
are to be used does not match exactly the conditions defined in PEP 440.
Script might feel a bit slow when attempting to find a version tag in a git repository with a very
large history and no version tags. It is designed towards packages with short release cycles
-- in long release cycles the overhead of manual versioning is small anyway.
Despite above limitations, version-query itself (as well as growing number of other packages) are
using version-query without any issues.
Requirements
============
Python version 3.8 or later.
Python libraries as specified in `requirements.txt <https://github.com/mbdevpl/version-query/blob/v1.5.4/requirements.txt>`_.
Building and running tests additionally requires packages listed in `requirements_test.txt <https://github.com/mbdevpl/version-query/blob/v1.5.4/requirements_test.txt>`_.
Tested on Linux, macOS and Windows.
Raw data
{
"_id": null,
"home_page": "https://github.com/mbdevpl/version-query",
"name": "version-query",
"maintainer": "Mateusz Bysiek",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "mateusz.bysiek@gmail.com",
"keywords": "automation,continuous integration,git,releasing,semantic versioning,tagging,versioning",
"author": "Mateusz Bysiek, John Vandenberg",
"author_email": "mateusz.bysiek@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/2b/f0/d2ab955bca50192dacf6d0f83bdf65e09ac945637fa827472b2a7aa7e64e/version-query-1.5.4.tar.gz",
"platform": null,
"description": ".. role:: bash(code)\n :language: bash\n\n.. role:: python(code)\n :language: python\n\n\n=============\nversion-query\n=============\n\nZero-overhead package versioning for Python.\n\n.. image:: https://img.shields.io/pypi/v/version-query.svg\n :target: https://pypi.org/project/version-query\n :alt: package version from PyPI\n\n.. image:: https://github.com/mbdevpl/version-query/actions/workflows/python.yml/badge.svg?branch=main\n :target: https://github.com/mbdevpl/version-query/actions\n :alt: build status from GitHub\n\n.. image:: https://codecov.io/gh/mbdevpl/version-query/branch/main/graph/badge.svg\n :target: https://codecov.io/gh/mbdevpl/version-query\n :alt: test coverage from Codecov\n\n.. image:: https://api.codacy.com/project/badge/Grade/437ab82bd6324530847fe8ed833f8d78\n :target: https://app.codacy.com/gh/mbdevpl/version-query\n :alt: grade from Codacy\n\n.. image:: https://img.shields.io/github/license/mbdevpl/version-query.svg\n :target: https://github.com/mbdevpl/version-query/blob/v1.5.4/NOTICE\n :alt: license\n\nPackage versioning toolkit for Python which relies on git tags, git history traversal\nand status of git repository to generate a very fine-grained version number.\n\nAren't you tired hardcoding the version numbers when maintaining a Python package?!\n\nAnd wouldn't you like have fine-grained versioning scheme with version changing with each commit,\nfor easier development, testing and pre-release deployment?!\n\nSearch no more!\n\nAs long as you mark your releases using git tags, instead of hardcoding:\n\n.. code:: python\n\n __version__ = '1.5.0.dev2'\n\nYou can do:\n\n.. code:: python\n\n from version_query import predict_version_str\n\n __version__ = predict_version_str()\n\nIt's 21st century, stop hardcoding version numbers!\n\nThis will set the version to release version when you really release a new version,\nand it will automatically generate a suitable development version at development/pre-release phase.\n\n\n.. contents::\n :backlinks: none\n\n\nOverview\n========\n\nAt development time, the current version number is automatically generated based on:\n\n* tags\n* current commit SHA\n* index status\n\nin your git repository. Therefore the package can be built and shipped to PyPI based only on status\nof the git repository. When there is no git repository (this might be the case at installation time\nor at runtime) then the script relies on metadata generated at packaging time.\n\nThat's why, regardless if package is installed from PyPI (from source or wheel distribution)\nor cloned from GitHub, the version query will work.\n\nAdditionally, version numbers in version-query are mutable objects and they can be conveniently\nincremented, compared with each other, as well as converted to/from other popular\nversioning formats.\n\nVersioning scheme\n=================\n\nVersion scheme used by version-query is a relaxed mixture of:\n\n* `Semantic Versioning 2.0.0 <http://semver.org/>`_ and\n\n* `PEP 440 -- Version Identification and Dependency Specification <https://www.python.org/dev/peps/pep-0440/>`_.\n\nThese two rulesets are mostly compatible. When they are not, a more relaxed approach of the two\nis used. Details follow.\n\nVersion has one of the following forms:\n\n* ``<release>``\n* ``<release><pre-release>``\n* ``<release>+<local>``\n* ``<release><pre-release>+<local>``\n\nA release version identifier ``<release>`` has one of the following forms:\n\n* ``<major>``\n* ``<major>.<minor>``\n* ``<major>.<minor>.<patch>``\n\nAnd the pre-release version identifier ``<pre-release>`` has one of the following forms:\n\n* ``<pre-type>``\n* ``<pre-type><pre-patch>``\n* ``<pre-separator><pre-type>``\n* ``<pre-separator><pre-patch>``\n* ``<pre-separator><pre-type><pre-patch>``\n* ... and any of these forms can be repeated arbitrary number of times.\n\nAnd finally the local version identifier ``<local>`` has one of the forms:\n\n* ``<local-part>``\n* ``<local-part><local-separator><local-part>``\n* ``<local-part><local-separator><local-part><local-separator><local-part>``\n* ... and so on.\n\nEach version component has a meaning and constraints on its contents:\n\n* ``<major>`` - a non-negative integer, increments when backwards-incompatible changes are made\n* ``<minor>`` - a non-negative integer, increments when backwards-compatible features are added\n* ``<patch>`` - a non-negative integer, increments when backwards-compatible bugfixes are made\n\n* ``<pre-separator>`` - dot or dash, separates release version information from pre-release\n* ``<pre-type>`` - a string of lower-case alphabetic characters, type of the pre-release\n* ``<pre-patch>`` - a non-negative integer, revision of the pre-release\n\n* ``<local-part>`` - a sequence of alphanumeric characters, stores arbitrary information\n* ``<local-separator>`` - a dot or dash, separates parts of local version identifier\n\n\nHow exactly the version number is determined\n--------------------------------------------\n\nThe version-query package has two modes of operation:\n\n* *query* - only currently available explicit information is used to determine the version number\n* *prediction* - this applies only to determining version number from git repository, and means\n that in addition to explicit version information, git repository status can be used\n to get very fine-grained version number which will be unique for every repository snapshot\n\n\nVersion query from package metadata file\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe metadata file (``PKG-INFO`` or ``metadata.json`` or ``METADATA``) is automatically generated\nwhenever a Python distribution file is built.\nWhich one, depends on your method of building, but in any case, the file is then packaged into\ndistributions, and when uploaded to PyPI that metadata file is used to populate\nthe package page - therefore all Python packages on PyPI should have it.\n\nAdditionally, source code folder of any package using setuptools, in which ``setup.py build``\nwas executed, contains metadata file -- even if distribution file was not built.\n\nThe version identifier is contained verbatim in the metadata file, therefore version query\nin this case boils down to simply reading the metadata file.\n\nInformation about Python metadata files:\n\n* `PEP 345 -- Metadata for Python Software Packages 1.2 <https://www.python.org/dev/peps/pep-0345/>`_,\n which replaced `PEP 314 -- Metadata for Python Software Packages v1.1 <https://www.python.org/dev/peps/pep-0314/>`_,\n which in turn replaced `PEP 241 -- Metadata for Python Software Packages <https://www.python.org/dev/peps/pep-0241/>`_.\n According to PEP 345, version of package should conform to what has been defined in PEP 440.\n\n* `PEP 566 -- Metadata for Python Software Packages 2.1 <https://www.python.org/dev/peps/pep-0566/>`_\n which replaced the PEP 345. This new standard doesn't however modify the version handling\n in any way other than ensuring that requirements specification conforms with PEP 508,\n which is not related to Python package version querying.\n\n\nVersion query from git repository\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nThe version number is equal to the version contained in the most recent version tag.\n\nVersion tags\n````````````\n\nAny git tag that is a valid version (matching the rules above) is considered a version tag.\nVersion number can be prefixed with ``v`` or ``ver``. Other tags are ignored.\n\nExamples of valid version tags:\n\n* ``v1.0``\n* ``v0.16.0``\n* ``v1.0.dev3``\n* ``ver0.5.1-4.0.0+gita1de3012``\n* ``42.0``\n* ``3.14-15``\n\n\nMost recent version tag\n```````````````````````\n\nThe most recent tag is found based on repository history and version precedence.\n\nSearch for version tags starts from current commit, and goes backwards in history (towards initial\ncommit). Therefore, commits after current one as well as not-merged branches are ignored in the\nversion tag search.\n\nIf there are several version tags on one commit, then highest version number is used.\n\nIf there are version tags on several merged branches, then the highest version number is used.\n\nIf there are no version tags in the repository, you'll get an error - so version cannot be queried\nfrom git repository without any version tags.\n\nBut in such case, version can still be *predicted*, as described below.\n\n\nVersion prediction from git repository\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\nIn version prediction mode, first of all, a most recent version tag is found, as above.\nIf there are no version tags in the repo, then the initial commit is assumed to have tag\n``v0.1.0.dev0``.\n\nThen, the new commits since the most recent version tag are counted.\nThen, the repository index status is queried. All the results are combined to form\nthe predicted version number. Procedure is described below in detail.\n\n\nCounting new commits\n````````````````````\n\nIf after the commit with the most recent tag there are any new commits, a suffix ``.dev#``\nis appended to the version identifier, where ``#`` is the number of commits between\nthe current commit and the most recent version tag.\n\nAdditionally, the ``<patch>`` version component is incremented by ``1``.\n\nAdditionally, a plus (``+``) character, word ``git`` and the first 8 characters of SHA\nof the latest commit are appended to version identifier, e.g. ``+gita3014fe0``.\n\n\nRepository index status\n```````````````````````\n\nAdditionally, if there are any uncommitted changes in the repository (i.e. the repo is *dirty*),\nthe suffix ``.dirty`` followed by current date and time in format ``YYYYMMDDhhmmss`` are appended\nto the identifier.\n\nExample of how the final version identifier looks like, depending on various conditions\nof the repository:\n\n* Most recent version tag is ``v0.4.5``, there were 2 commits since,\n latest having SHA starting with ``812f12ea``.\n Version identifier will be ``0.4.6.dev2+git812f12ea``.\n\n* Most recent version tag is ``ver6.0``, and there was 1 commit since\n having SHA starting with ``e10ac365``.\n Version identifier will be ``6.0.1.dev1+gite10ac365``.\n\n* Most recent version tag is ``v9``, there were 40 commit since,\n latest having SHA starting with ``1ad22355``, the repository has uncommitted changes and\n version was queried at 19:52.20, 8th June 2017.\n the result is ``9.0.1.dev40+git1ad22355.dirty20170608195220``.\n\n\nHow exactly version numbers are compared\n----------------------------------------\n\nThe base specification of the comparison scheme is:\n\n* `PEP 508 -- Dependency specification for Python Software Packages <https://www.python.org/dev/peps/pep-0508/>`_ as well as\n\n* `Semantic Versioning 2.0.0 <http://semver.org/>`_.\n\nWith the notable difference to both that all version components are taken into account when\nestablishing version precedence.\n\nWhen being compared, ``<major>``, ``<minor>`` and ``<patch>`` are assumed equal to ``0`` if they\nare not present. In ``<pre-release>``, the ``<pre-patch>`` is assumed to be ``0`` if not present.\n\nExamples of comparison results:\n\n* ``0.3-4.4-2.9`` < ``0.3-4.4-2.10``\n* ``0.3dev`` < ``0.3dev1``\n* ``0.3rc2`` < ``0.3``\n* ``0.3`` < ``0.3-2``\n* ``1.0.0`` < ``1.0.0+blahblah``\n* ``1.0.0+aa`` < ``1.0.0+aaa``\n* ``1.0.0`` = ``1.0.0``\n* ``1`` = ``1.0.0``\n* ``1.0`` = ``1.0.0.0``\n* ``1.0.0-0.0.DEV42`` = ``1.0.0.0.0.dev42``\n\n\nHow exactly version number is incremented\n-----------------------------------------\n\nSome version components have assumed value ``0`` if they are not present, please see section above\nfor details.\n\nIncrementing any version component clears all existing following components.\n\nExamples of how version is incremented:\n\n* for ``1.5``, incrementing ``<major>`` results in ``2.0``;\n* for ``1.5.1-2.4``, ``<minor>``++ results in ``1.6``;\n* ``1.5.1-2.4``, ``<patch>``++, ``1.5.2``;\n* ``1.5.1``, ``<major>``+=3, ``4.0.0``.\n\n\nAPI details\n===========\n\nAll functionality mentioned below is considered as the public API. Other functionality may change\nwithout notice.\n\n\nMain API\n--------\n\n.. code:: python\n\n import version_query\n\n version_str = version_query.query_version_str()\n\nThe version-query package will query the version string while operating in *query* mode.\n\n.. code:: python\n\n version_str = version_query.predict_version_str()\n\nThe version-query package will infer the version string while operating in *prediction* mode.\n\n.. code:: python\n\n version = version_query.Version(1, 0, 4)\n version = version_query.Version(major=1, patch=4)\n version = version_query.Version.from_str('1.0.4')\n\nThe Version class is used internally by version-query, but it can be also used explicitly.\n\n.. code:: python\n\n import packaging.version\n version = version_query.Version.from_py_version(packaging.version.Version())\n version.to_py_version()\n\n import semver\n version = version_query.Version.from_sem_version(semver.VersionInfo())\n version.to_sem_version()\n\nAlso, Version class interoperates with ``packaging`` and ``semver`` packages as well as selected\nbuilt-in types.\n\n.. code:: python\n\n assert version_query.Version(1, 0, 4).increment(version_query.VersionComponent.Patch, 2) \\\n == version_query.Version.from_str('1.0.6')\n assert version_query.Version.from_str('1.0.4') < version_query.Version.from_str('2.0.0')\n\nThe Version objects are mutable, hashable and comparable.\n\n.. code:: python\n\n version = version_query.query_folder(pathlib.Path('/my/project'), search_parent_directories=False)\n version = version_query.predict_git_repo(pathlib.Path('/my/git/versioned/project/subdir'), True)\n version = version_query.query_caller(stack_level=1)\n version = version_query.predict_caller(2)\n\nVersion object can be obtained for any supported path, as well as for any python code\ncurrently being executed -- as long as it is located in a supported location.\n\n\nCommand-line interface\n----------------------\n\n.. code:: bash\n\n python3 -m version_query --help\n python3 -m version_query /my/project -p\n\n.. code:: python\n\n version_query.__main__.main(args=['--help'])\n version_query.__main__.main(args=['/my/project', '-p'])\n\nVersion query can be also used as a command-line script, with the entry point also accessible\nas ``version_query.__main__.main`` from within Python.\n\n\nUtility functions\n-----------------\n\n.. code:: python\n\n assert version_query.git_query.preprocess_git_version_tag('v1.0.4') == '1.0.4'\n assert version_query.git_query.preprocess_git_version_tag('ver1.0.4') == '1.0.4'\n assert version_query.git_query.preprocess_git_version_tag('1.0.4') == '1.0.4'\n\nRemove ``v`` and ``ver`` prefix from a given string, and preform very crude checking whether\nthe tag is probably a version tag.\n\n\nLimitations\n===========\n\nEither git repository or metadata file must be present for the script to work. When, for example,\nzipped version of repository is downloaded from GitHub, the resulting archive contains neither\nmetadata files nor repository data.\n\nIt is unclear what happens if the queried repository is bare.\n\nThe implementation is not fully compatible with Python versioning. Especially,\nin current implementation at most one of:\nalpha ``a`` / beta ``b`` / release candidate ``rc`` / development ``dev`` suffixes\ncan be used in a version identifier.\n\nAnd the format in which\nalpha ``a``, beta ``b`` and release candidate ``rc`` suffixes\nare to be used does not match exactly the conditions defined in PEP 440.\n\nScript might feel a bit slow when attempting to find a version tag in a git repository with a very\nlarge history and no version tags. It is designed towards packages with short release cycles\n-- in long release cycles the overhead of manual versioning is small anyway.\n\nDespite above limitations, version-query itself (as well as growing number of other packages) are\nusing version-query without any issues.\n\n\nRequirements\n============\n\nPython version 3.8 or later.\n\nPython libraries as specified in `requirements.txt <https://github.com/mbdevpl/version-query/blob/v1.5.4/requirements.txt>`_.\n\nBuilding and running tests additionally requires packages listed in `requirements_test.txt <https://github.com/mbdevpl/version-query/blob/v1.5.4/requirements_test.txt>`_.\n\nTested on Linux, macOS and Windows.\n",
"bugtrack_url": null,
"license": "Apache License 2.0",
"summary": "Zero-overhead package versioning for Python.",
"version": "1.5.4",
"project_urls": {
"Homepage": "https://github.com/mbdevpl/version-query"
},
"split_keywords": [
"automation",
"continuous integration",
"git",
"releasing",
"semantic versioning",
"tagging",
"versioning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "370c092f982e3b816ec685dcbf21cb6848c1c91e7cba73a76dfa6cd1dc4a337b",
"md5": "c2e6d92931302d65a1ecd34020871826",
"sha256": "5a1a01b24f9c80db67c0f29b87c6ca8e0b35ddaa784e921d43f93b3143ea9993"
},
"downloads": -1,
"filename": "version_query-1.5.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "c2e6d92931302d65a1ecd34020871826",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 23039,
"upload_time": "2023-09-02T16:43:47",
"upload_time_iso_8601": "2023-09-02T16:43:47.860741Z",
"url": "https://files.pythonhosted.org/packages/37/0c/092f982e3b816ec685dcbf21cb6848c1c91e7cba73a76dfa6cd1dc4a337b/version_query-1.5.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2bf0d2ab955bca50192dacf6d0f83bdf65e09ac945637fa827472b2a7aa7e64e",
"md5": "f6baaf75696be03f1c224eea3d2ef7fd",
"sha256": "59e6451a76958f25e6597e0d90113dc49020f6a62e8efa1e9ff77bfc4624dd21"
},
"downloads": -1,
"filename": "version-query-1.5.4.tar.gz",
"has_sig": false,
"md5_digest": "f6baaf75696be03f1c224eea3d2ef7fd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 33482,
"upload_time": "2023-09-02T16:43:49",
"upload_time_iso_8601": "2023-09-02T16:43:49.701295Z",
"url": "https://files.pythonhosted.org/packages/2b/f0/d2ab955bca50192dacf6d0f83bdf65e09ac945637fa827472b2a7aa7e64e/version-query-1.5.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-09-02 16:43:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mbdevpl",
"github_project": "version-query",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "version-query"
}
JSON
