|repostatus| |ci-status| |coverage| |pyversions| |conda| |license|
.. |repostatus| image:: https://www.repostatus.org/badges/latest/active.svg
:target: https://www.repostatus.org/#active
:alt: Project Status: Active — The project has reached a stable, usable
state and is being actively developed.
.. |ci-status| image:: https://github.com/jwodder/versioningit/actions/workflows/test.yml/badge.svg
:target: https://github.com/jwodder/versioningit/actions/workflows/test.yml
:alt: CI Status
.. |coverage| image:: https://codecov.io/gh/jwodder/versioningit/branch/master/graph/badge.svg
:target: https://codecov.io/gh/jwodder/versioningit
.. |pyversions| image:: https://img.shields.io/pypi/pyversions/versioningit.svg
:target: https://pypi.org/project/versioningit/
.. |conda| image:: https://img.shields.io/conda/vn/conda-forge/versioningit.svg
:target: https://anaconda.org/conda-forge/versioningit
:alt: Conda Version
.. |license| image:: https://img.shields.io/github/license/jwodder/versioningit.svg
:target: https://opensource.org/licenses/MIT
:alt: MIT License
`GitHub <https://github.com/jwodder/versioningit>`_
| `PyPI <https://pypi.org/project/versioningit/>`_
| `Documentation <https://versioningit.readthedocs.io>`_
| `Issues <https://github.com/jwodder/versioningit/issues>`_
| `Changelog <https://github.com/jwodder/versioningit/blob/master/CHANGELOG.md>`_
``versioningit`` — *Versioning It with your Version In Git*
``versioningit`` is yet another Python packaging plugin for automatically
determining your package's version based on your version control repository's
tags. Unlike others, it allows easy customization of the version format and
even lets you easily override the separate functions used for version
extraction & calculation.
**Features:**
- Works with both setuptools and Hatch_
.. _hatch: https://hatch.pypa.io
- Installed & configured through :pep:`518`'s ``pyproject.toml``
- Supports Git, modern Git archives, and Mercurial
- Formatting of the final version uses format template strings, with fields for
basic VCS information and separate template strings for distanced vs. dirty
vs. distanced-and-dirty repository states
- Can optionally write the final version and other details to a file for
loading at runtime
- Provides custom hooks for inserting the final version and other details into
a source file at build time
- The individual methods for VCS querying, tag-to-version calculation, version
bumping, version formatting, and writing the version to a file can all be
customized using either functions defined alongside one's project code or via
publicly-distributed entry points
- Can alternatively be used as a library for use in ``setup.py`` or the like,
in case you don't want to or can't configure it via ``pyproject.toml``
- The only thing it does is calculate your version and optionally write it to a
file; there's no overriding of your sdist contents based on what's in your
Git repository, especially not without a way to turn it off, because that
would just be rude.
Installation & Setup
====================
``versioningit`` requires Python 3.8 or higher. Just use `pip
<https://pip.pypa.io>`_ for Python 3 (You have pip, right?) to install
``versioningit`` and its dependencies::
python3 -m pip install versioningit
However, usually you won't need to install ``versioningit`` in your environment
directly. Instead, you specify it in your project's ``pyproject.toml`` file in
the ``build-system.requires`` key, like so:
.. code:: toml
# If using Setuptools:
[build-system]
requires = [
"setuptools",
"versioningit",
]
build-backend = "setuptools.build_meta"
# If using Hatch:
[build-system]
requires = [
"hatchling",
"versioningit",
]
build-backend = "hatchling.build"
# This setting is also required if you're using Hatch:
[tool.hatch.version]
source = "versioningit"
Then, you configure ``versioningit`` by adding a ``[tool.versioningit]`` table
to your ``pyproject.toml``. See `the documentation`__ for details, but you
can get up & running with just the minimal configuration, an empty table:
__ https://versioningit.readthedocs.io/en/stable/configuration.html
.. code:: toml
[tool.versioningit]
``versioningit`` eliminates the need to list an explicit version in
``setup.py``, ``setup.cfg``, or ``pyproject.toml`` (and any explicit version
you do list will be ignored when using ``versioningit``), so you should remove
any such settings in order to reduce confusion.
**Note:** If you're specifying your project metadata via a ``[project]`` table
in ``pyproject.toml``, you need to set ``project.dynamic = ["version"]`` in
order for ``versioningit`` to work.
Once you have a ``[tool.versioningit]`` table in your ``pyproject.toml`` — and
once your repository has at least one tag — building your project with build_
or similar will result in your project's version automatically being set based
on the latest tag in your Git repository. You can test your configuration and
see what the resulting version will be using the ``versioningit`` command (`see
the documentation`__).
.. _build: https://github.com/pypa/build
__ https://versioningit.readthedocs.io/en/stable/command.html
Example Configurations
======================
One of ``versioningit``'s biggest strengths is its ability to configure the
version format using placeholder strings. The default format configuration
looks like this:
.. code:: toml
[tool.versioningit.format]
# Format used when there have been commits since the most recent tag:
distance = "{base_version}.post{distance}+{vcs}{rev}"
# Example formatted version: 1.2.3.post42+ge174a1f
# Format used when there are uncommitted changes:
dirty = "{base_version}+d{build_date:%Y%m%d}"
# Example formatted version: 1.2.3+d20230922
# Format used when there are both commits and uncommitted changes:
distance-dirty = "{base_version}.post{distance}+{vcs}{rev}.d{build_date:%Y%m%d}"
# Example formatted version: 1.2.3.post42+ge174a1f.d20230922
Other format configurations of interest include:
- The default format used by setuptools_scm_:
.. code:: toml
[tool.versioningit.next-version]
method = "smallest"
[tool.versioningit.format]
distance = "{next_version}.dev{distance}+{vcs}{rev}"
# Example formatted version: 1.2.4.dev42+ge174a1f
dirty = "{base_version}+d{build_date:%Y%m%d}"
# Example formatted version: 1.2.3+d20230922
distance-dirty = "{next_version}.dev{distance}+{vcs}{rev}.d{build_date:%Y%m%d}"
# Example formatted version: 1.2.4.dev42+ge174a1f.d20230922
- The format used by versioneer_:
.. code:: toml
[tool.versioningit.format]
distance = "{base_version}+{distance}.{vcs}{rev}"
# Example formatted version: 1.2.3+42.ge174a1f
dirty = "{base_version}+{distance}.{vcs}{rev}.dirty"
# Example formatted version: 1.2.3+42.ge174a1f.dirty
distance-dirty = "{base_version}+{distance}.{vcs}{rev}.dirty"
# Example formatted version: 1.2.3+42.ge174a1f.dirty
- The format used by vcversioner_:
.. code:: toml
[tool.versioningit.format]
distance = "{base_version}.post{distance}"
# Example formatted version: 1.2.3.post42
dirty = "{base_version}"
# Example formatted version: 1.2.3
distance-dirty = "{base_version}.post{distance}"
# Example formatted version: 1.2.3.post42
.. _setuptools_scm: https://github.com/pypa/setuptools_scm
.. _versioneer: https://github.com/python-versioneer/python-versioneer
.. _vcversioner: https://github.com/habnabit/vcversioner
Raw data
{
"_id": null,
"home_page": null,
"name": "versioningit",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "Git, Mercurial, VCS, packaging, version",
"author": null,
"author_email": "John Thorvald Wodder II <versioningit@varonathe.org>",
"download_url": "https://files.pythonhosted.org/packages/5c/9b/941647e9e3616b5da7bbc4601ed9920f44a886704100fa8151406c07c149/versioningit-3.1.2.tar.gz",
"platform": null,
"description": "|repostatus| |ci-status| |coverage| |pyversions| |conda| |license|\n\n.. |repostatus| image:: https://www.repostatus.org/badges/latest/active.svg\n :target: https://www.repostatus.org/#active\n :alt: Project Status: Active \u2014 The project has reached a stable, usable\n state and is being actively developed.\n\n.. |ci-status| image:: https://github.com/jwodder/versioningit/actions/workflows/test.yml/badge.svg\n :target: https://github.com/jwodder/versioningit/actions/workflows/test.yml\n :alt: CI Status\n\n.. |coverage| image:: https://codecov.io/gh/jwodder/versioningit/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/jwodder/versioningit\n\n.. |pyversions| image:: https://img.shields.io/pypi/pyversions/versioningit.svg\n :target: https://pypi.org/project/versioningit/\n\n.. |conda| image:: https://img.shields.io/conda/vn/conda-forge/versioningit.svg\n :target: https://anaconda.org/conda-forge/versioningit\n :alt: Conda Version\n\n.. |license| image:: https://img.shields.io/github/license/jwodder/versioningit.svg\n :target: https://opensource.org/licenses/MIT\n :alt: MIT License\n\n`GitHub <https://github.com/jwodder/versioningit>`_\n| `PyPI <https://pypi.org/project/versioningit/>`_\n| `Documentation <https://versioningit.readthedocs.io>`_\n| `Issues <https://github.com/jwodder/versioningit/issues>`_\n| `Changelog <https://github.com/jwodder/versioningit/blob/master/CHANGELOG.md>`_\n\n``versioningit`` \u2014 *Versioning It with your Version In Git*\n\n``versioningit`` is yet another Python packaging plugin for automatically\ndetermining your package's version based on your version control repository's\ntags. Unlike others, it allows easy customization of the version format and\neven lets you easily override the separate functions used for version\nextraction & calculation.\n\n**Features:**\n\n- Works with both setuptools and Hatch_\n\n .. _hatch: https://hatch.pypa.io\n\n- Installed & configured through :pep:`518`'s ``pyproject.toml``\n\n- Supports Git, modern Git archives, and Mercurial\n\n- Formatting of the final version uses format template strings, with fields for\n basic VCS information and separate template strings for distanced vs. dirty\n vs. distanced-and-dirty repository states\n\n- Can optionally write the final version and other details to a file for\n loading at runtime\n\n- Provides custom hooks for inserting the final version and other details into\n a source file at build time\n\n- The individual methods for VCS querying, tag-to-version calculation, version\n bumping, version formatting, and writing the version to a file can all be\n customized using either functions defined alongside one's project code or via\n publicly-distributed entry points\n\n- Can alternatively be used as a library for use in ``setup.py`` or the like,\n in case you don't want to or can't configure it via ``pyproject.toml``\n\n- The only thing it does is calculate your version and optionally write it to a\n file; there's no overriding of your sdist contents based on what's in your\n Git repository, especially not without a way to turn it off, because that\n would just be rude.\n\n\nInstallation & Setup\n====================\n``versioningit`` requires Python 3.8 or higher. Just use `pip\n<https://pip.pypa.io>`_ for Python 3 (You have pip, right?) to install\n``versioningit`` and its dependencies::\n\n python3 -m pip install versioningit\n\nHowever, usually you won't need to install ``versioningit`` in your environment\ndirectly. Instead, you specify it in your project's ``pyproject.toml`` file in\nthe ``build-system.requires`` key, like so:\n\n.. code:: toml\n\n # If using Setuptools:\n [build-system]\n requires = [\n \"setuptools\",\n \"versioningit\",\n ]\n build-backend = \"setuptools.build_meta\"\n\n # If using Hatch:\n [build-system]\n requires = [\n \"hatchling\",\n \"versioningit\",\n ]\n build-backend = \"hatchling.build\"\n\n # This setting is also required if you're using Hatch:\n [tool.hatch.version]\n source = \"versioningit\"\n\nThen, you configure ``versioningit`` by adding a ``[tool.versioningit]`` table\nto your ``pyproject.toml``. See `the documentation`__ for details, but you\ncan get up & running with just the minimal configuration, an empty table:\n\n__ https://versioningit.readthedocs.io/en/stable/configuration.html\n\n.. code:: toml\n\n [tool.versioningit]\n\n``versioningit`` eliminates the need to list an explicit version in\n``setup.py``, ``setup.cfg``, or ``pyproject.toml`` (and any explicit version\nyou do list will be ignored when using ``versioningit``), so you should remove\nany such settings in order to reduce confusion.\n\n**Note:** If you're specifying your project metadata via a ``[project]`` table\nin ``pyproject.toml``, you need to set ``project.dynamic = [\"version\"]`` in\norder for ``versioningit`` to work.\n\nOnce you have a ``[tool.versioningit]`` table in your ``pyproject.toml`` \u2014 and\nonce your repository has at least one tag \u2014 building your project with build_\nor similar will result in your project's version automatically being set based\non the latest tag in your Git repository. You can test your configuration and\nsee what the resulting version will be using the ``versioningit`` command (`see\nthe documentation`__).\n\n.. _build: https://github.com/pypa/build\n\n__ https://versioningit.readthedocs.io/en/stable/command.html\n\n\nExample Configurations\n======================\n\nOne of ``versioningit``'s biggest strengths is its ability to configure the\nversion format using placeholder strings. The default format configuration\nlooks like this:\n\n.. code:: toml\n\n [tool.versioningit.format]\n # Format used when there have been commits since the most recent tag:\n distance = \"{base_version}.post{distance}+{vcs}{rev}\"\n # Example formatted version: 1.2.3.post42+ge174a1f\n\n # Format used when there are uncommitted changes:\n dirty = \"{base_version}+d{build_date:%Y%m%d}\"\n # Example formatted version: 1.2.3+d20230922\n\n # Format used when there are both commits and uncommitted changes:\n distance-dirty = \"{base_version}.post{distance}+{vcs}{rev}.d{build_date:%Y%m%d}\"\n # Example formatted version: 1.2.3.post42+ge174a1f.d20230922\n\nOther format configurations of interest include:\n\n- The default format used by setuptools_scm_:\n\n .. code:: toml\n\n [tool.versioningit.next-version]\n method = \"smallest\"\n\n [tool.versioningit.format]\n distance = \"{next_version}.dev{distance}+{vcs}{rev}\"\n # Example formatted version: 1.2.4.dev42+ge174a1f\n\n dirty = \"{base_version}+d{build_date:%Y%m%d}\"\n # Example formatted version: 1.2.3+d20230922\n\n distance-dirty = \"{next_version}.dev{distance}+{vcs}{rev}.d{build_date:%Y%m%d}\"\n # Example formatted version: 1.2.4.dev42+ge174a1f.d20230922\n\n- The format used by versioneer_:\n\n .. code:: toml\n\n [tool.versioningit.format]\n distance = \"{base_version}+{distance}.{vcs}{rev}\"\n # Example formatted version: 1.2.3+42.ge174a1f\n\n dirty = \"{base_version}+{distance}.{vcs}{rev}.dirty\"\n # Example formatted version: 1.2.3+42.ge174a1f.dirty\n\n distance-dirty = \"{base_version}+{distance}.{vcs}{rev}.dirty\"\n # Example formatted version: 1.2.3+42.ge174a1f.dirty\n\n- The format used by vcversioner_:\n\n .. code:: toml\n\n [tool.versioningit.format]\n distance = \"{base_version}.post{distance}\"\n # Example formatted version: 1.2.3.post42\n\n dirty = \"{base_version}\"\n # Example formatted version: 1.2.3\n\n distance-dirty = \"{base_version}.post{distance}\"\n # Example formatted version: 1.2.3.post42\n\n.. _setuptools_scm: https://github.com/pypa/setuptools_scm\n.. _versioneer: https://github.com/python-versioneer/python-versioneer\n.. _vcversioner: https://github.com/habnabit/vcversioner\n",
"bugtrack_url": null,
"license": null,
"summary": "Versioning It with your Version In Git",
"version": "3.1.2",
"project_urls": {
"Bug Tracker": "https://github.com/jwodder/versioningit/issues",
"Documentation": "https://versioningit.readthedocs.io",
"Source Code": "https://github.com/jwodder/versioningit"
},
"split_keywords": [
"git",
" mercurial",
" vcs",
" packaging",
" version"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "7f5650784a34941e6a77cb068289c851d35c8b9af6a4d266fdb85d4d4828fe21",
"md5": "ff966cf1b400fd108b1f176d2e38c3a6",
"sha256": "33c0905aeac7877b562171387c2c98af87b391aa9195f095455f21ddc47d4636"
},
"downloads": -1,
"filename": "versioningit-3.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ff966cf1b400fd108b1f176d2e38c3a6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 37950,
"upload_time": "2024-07-20T12:41:06",
"upload_time_iso_8601": "2024-07-20T12:41:06.227751Z",
"url": "https://files.pythonhosted.org/packages/7f/56/50784a34941e6a77cb068289c851d35c8b9af6a4d266fdb85d4d4828fe21/versioningit-3.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5c9b941647e9e3616b5da7bbc4601ed9920f44a886704100fa8151406c07c149",
"md5": "7e25b7db2b9d6c82d910d691b52b211c",
"sha256": "4db83ed99f56b07d83940bee3445ca46ca120d13b6b304cdb5fb44e5aa4edec0"
},
"downloads": -1,
"filename": "versioningit-3.1.2.tar.gz",
"has_sig": false,
"md5_digest": "7e25b7db2b9d6c82d910d691b52b211c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 213047,
"upload_time": "2024-07-20T12:41:07",
"upload_time_iso_8601": "2024-07-20T12:41:07.927030Z",
"url": "https://files.pythonhosted.org/packages/5c/9b/941647e9e3616b5da7bbc4601ed9920f44a886704100fa8151406c07c149/versioningit-3.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-20 12:41:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jwodder",
"github_project": "versioningit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "versioningit"
}
JSON
