| 1 |
Metadata-Version: 2.1 |
| 2 |
Name: incremental |
| 3 |
Version: 24.7.2 |
| 4 |
Summary: A small library that versions your Python projects. |
| 5 |
Maintainer-email: Amber Brown <[email protected]> |
| 6 |
Project-URL: Homepage, https://github.com/twisted/incremental |
| 7 |
Project-URL: Documentation, https://twisted.org/incremental/docs/ |
| 8 |
Project-URL: Issues, https://github.com/twisted/incremental/issues |
| 9 |
Project-URL: Changelog, https://github.com/twisted/incremental/blob/trunk/NEWS.rst |
| 10 |
Classifier: Intended Audience :: Developers |
| 11 |
Classifier: License :: OSI Approved :: MIT License |
| 12 |
Classifier: Framework :: Hatch |
| 13 |
Classifier: Framework :: Setuptools Plugin |
| 14 |
Classifier: Programming Language :: Python :: 3 |
| 15 |
Classifier: Programming Language :: Python :: 3.8 |
| 16 |
Classifier: Programming Language :: Python :: 3.9 |
| 17 |
Classifier: Programming Language :: Python :: 3.10 |
| 18 |
Classifier: Programming Language :: Python :: 3.11 |
| 19 |
Classifier: Programming Language :: Python :: 3.12 |
| 20 |
Requires-Python: >=3.8 |
| 21 |
Description-Content-Type: text/x-rst |
| 22 |
License-File: LICENSE |
| 23 |
Requires-Dist: setuptools>=61.0 |
| 24 |
Requires-Dist: tomli; python_version < "3.11" |
| 25 |
Provides-Extra: scripts |
| 26 |
Requires-Dist: click>=6.0; extra == "scripts" |
| 27 |
|
| 28 |
Incremental |
| 29 |
=========== |
| 30 |
|
| 31 |
|gha| |
| 32 |
|pypi| |
| 33 |
|coverage| |
| 34 |
|
| 35 |
Incremental is a small library that versions your Python projects. |
| 36 |
|
| 37 |
API documentation can be found `here <https://twisted.org/incremental/docs/>`_. |
| 38 |
|
| 39 |
.. contents:: |
| 40 |
|
| 41 |
Quick Start |
| 42 |
----------- |
| 43 |
|
| 44 |
Using setuptools |
| 45 |
~~~~~~~~~~~~~~~~ |
| 46 |
|
| 47 |
Add Incremental to your ``pyproject.toml``: |
| 48 |
|
| 49 |
.. code-block:: toml |
| 50 |
|
| 51 |
[build-system] |
| 52 |
requires = [ |
| 53 |
"setuptools", |
| 54 |
"incremental>=24.7.2", # ← Add incremental as a build dependency |
| 55 |
] |
| 56 |
build-backend = "setuptools.build_meta" |
| 57 |
|
| 58 |
[project] |
| 59 |
name = "<projectname>" |
| 60 |
dynamic = ["version"] # ← Mark the version dynamic |
| 61 |
dependencies = [ |
| 62 |
"incremental>=24.7.2", # ← Depend on incremental at runtime |
| 63 |
] |
| 64 |
# ... |
| 65 |
|
| 66 |
[tool.incremental] # ← Activate Incremental's setuptools plugin |
| 67 |
|
| 68 |
It's fine if the ``[tool.incremental]`` table is empty, but it must be present. |
| 69 |
|
| 70 |
Remove any ``[project] version =`` entry and any ``[tool.setuptools.dynamic] version =`` entry. |
| 71 |
|
| 72 |
Next, `initialize the project`_. |
| 73 |
|
| 74 |
Using Hatchling |
| 75 |
~~~~~~~~~~~~~~~ |
| 76 |
|
| 77 |
If you're using `Hatchling <https://hatch.pypa.io/>`_ to package your project, |
| 78 |
activate Incremental's Hatchling plugin by altering your ``pyproject.toml``: |
| 79 |
|
| 80 |
.. code:: toml |
| 81 |
|
| 82 |
[build-system] |
| 83 |
requires = [ |
| 84 |
"hatchling", |
| 85 |
"incremental>=24.7.2", # ← Add incremental as a build dependency |
| 86 |
] |
| 87 |
build-backend = "hatchling.build" |
| 88 |
|
| 89 |
[project] |
| 90 |
name = "<projectname>" |
| 91 |
dynamic = ["version"] # ← Mark the version dynamic |
| 92 |
dependencies = [ |
| 93 |
"incremental>=24.7.2", # ← Depend on incremental at runtime |
| 94 |
] |
| 95 |
# ... |
| 96 |
|
| 97 |
[tool.hatch.version] |
| 98 |
source = "incremental" # ← Activate Incremental's Hatchling plugin |
| 99 |
|
| 100 |
Incremental can be configured as usual in an optional ``[tool.incremental]`` table. |
| 101 |
|
| 102 |
The ``hatch version`` command will report the Incremental-managed version. |
| 103 |
Use the ``python -m incremental.update`` command to change the version (setting it with ``hatch version`` is not supported). |
| 104 |
|
| 105 |
Next, `initialize the project`_. |
| 106 |
|
| 107 |
|
| 108 |
Using ``setup.py`` |
| 109 |
~~~~~~~~~~~~~~~~~~ |
| 110 |
|
| 111 |
Incremental may be used from ``setup.py`` instead of ``pyproject.toml``. |
| 112 |
Add this to your ``setup()`` call, removing any other versioning arguments: |
| 113 |
|
| 114 |
.. code:: python |
| 115 |
|
| 116 |
setup( |
| 117 |
use_incremental=True, |
| 118 |
setup_requires=['incremental'], |
| 119 |
install_requires=['incremental'], # along with any other install dependencies |
| 120 |
... |
| 121 |
} |
| 122 |
|
| 123 |
Then `initialize the project`_. |
| 124 |
|
| 125 |
|
| 126 |
Initialize the project |
| 127 |
~~~~~~~~~~~~~~~~~~~~~~ |
| 128 |
|
| 129 |
Install Incremental to your local environment with ``pip install incremental[scripts]``. |
| 130 |
Then run ``python -m incremental.update <projectname> --create``. |
| 131 |
It will create a file in your package named ``_version.py`` like this: |
| 132 |
|
| 133 |
.. code:: python |
| 134 |
|
| 135 |
from incremental import Version |
| 136 |
|
| 137 |
__version__ = Version("<projectname>", 24, 1, 0) |
| 138 |
__all__ = ["__version__"] |
| 139 |
|
| 140 |
|
| 141 |
Then, so users of your project can find your version, in your root package's ``__init__.py`` add: |
| 142 |
|
| 143 |
.. code:: python |
| 144 |
|
| 145 |
from ._version import __version__ |
| 146 |
|
| 147 |
|
| 148 |
Subsequent installations of your project will then use Incremental for versioning. |
| 149 |
|
| 150 |
|
| 151 |
|
| 152 |
Incremental Versions |
| 153 |
-------------------- |
| 154 |
|
| 155 |
``incremental.Version`` is a class that represents a version of a given project. |
| 156 |
It is made up of the following elements (which are given during instantiation): |
| 157 |
|
| 158 |
- ``package`` (required), the name of the package this ``Version`` represents. |
| 159 |
- ``major``, ``minor``, ``micro`` (all required), the X.Y.Z of your project's ``Version``. |
| 160 |
- ``release_candidate`` (optional), set to 0 or higher to mark this ``Version`` being of a release candidate (also sometimes called a "prerelease"). |
| 161 |
- ``post`` (optional), set to 0 or higher to mark this ``Version`` as a postrelease. |
| 162 |
- ``dev`` (optional), set to 0 or higher to mark this ``Version`` as a development release. |
| 163 |
|
| 164 |
You can extract a PEP-440 compatible version string by using the ``.public()`` method, which returns a ``str`` containing the full version. This is the version you should provide to users, or publicly use. An example output would be ``"13.2.0"``, ``"17.1.2dev1"``, or ``"18.8.0rc2"``. |
| 165 |
|
| 166 |
Calling ``repr()`` with a ``Version`` will give a Python-source-code representation of it, and calling ``str()`` on a ``Version`` produces a string like ``'[Incremental, version 16.10.1]'``. |
| 167 |
|
| 168 |
|
| 169 |
Updating |
| 170 |
-------- |
| 171 |
|
| 172 |
Incremental includes a tool to automate updating your Incremental-using project's version called ``incremental.update``. |
| 173 |
It updates the ``_version.py`` file and automatically updates some uses of Incremental versions from an indeterminate version to the current one. |
| 174 |
It requires ``click`` from PyPI. |
| 175 |
|
| 176 |
``python -m incremental.update <projectname>`` will perform updates on that package. |
| 177 |
The commands that can be given after that will determine what the next version is. |
| 178 |
|
| 179 |
- ``--newversion=<version>``, to set the project version to a fully-specified version (like 1.2.3, or 17.1.0dev1). |
| 180 |
- ``--rc``, to set the project version to ``<year-2000>.<month>.0rc1`` if the current version is not a release candidate, or bump the release candidate number by 1 if it is. |
| 181 |
- ``--dev``, to set the project development release number to 0 if it is not a development release, or bump the development release number by 1 if it is. |
| 182 |
- ``--patch``, to increment the patch number of the release. This will also reset the release candidate number, pass ``--rc`` at the same time to increment the patch number and make it a release candidate. |
| 183 |
- ``--post``, to set the project postrelease number to 0 if it is not a postrelease, or bump the postrelease number by 1 if it is. This will also reset the release candidate and development release numbers. |
| 184 |
|
| 185 |
If you give no arguments, it will strip the release candidate number, making it a "full release". |
| 186 |
|
| 187 |
Incremental supports "indeterminate" versions, as a stand-in for the next "full" version. This can be used when the version which will be displayed to the end-user is unknown (for example "introduced in" or "deprecated in"). Incremental supports the following indeterminate versions: |
| 188 |
|
| 189 |
- ``Version("<projectname>", "NEXT", 0, 0)`` |
| 190 |
- ``<projectname> NEXT`` |
| 191 |
|
| 192 |
When you run ``python -m incremental.update <projectname> --rc``, these will be updated to real versions (assuming the target final version is 17.1.0): |
| 193 |
|
| 194 |
- ``Version("<projectname>", 17, 1, 0, release_candidate=1)`` |
| 195 |
- ``<projectname> 17.1.0rc1`` |
| 196 |
|
| 197 |
Once the final version is made, it will become: |
| 198 |
|
| 199 |
- ``Version("<projectname>", 17, 1, 0)`` |
| 200 |
- ``<projectname> 17.1.0`` |
| 201 |
|
| 202 |
|
| 203 |
.. |coverage| image:: https://codecov.io/gh/twisted/incremental/branch/master/graph/badge.svg?token=K2ieeL887X |
| 204 |
.. _coverage: https://codecov.io/gh/twisted/incremental |
| 205 |
|
| 206 |
.. |gha| image:: https://github.com/twisted/incremental/actions/workflows/tests.yaml/badge.svg |
| 207 |
.. _gha: https://github.com/twisted/incremental/actions/workflows/tests.yaml |
| 208 |
|
| 209 |
.. |pypi| image:: http://img.shields.io/pypi/v/incremental.svg |
| 210 |
.. _pypi: https://pypi.python.org/pypi/incremental |