1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
|
Incremental
===========
|gha|
|pypi|
|coverage|
Incremental is a small library that versions your Python projects.
API documentation can be found `here <https://twisted.org/incremental/docs/>`_.
.. contents::
Quick Start
-----------
Using setuptools
~~~~~~~~~~~~~~~~
Add Incremental to your ``pyproject.toml``:
.. code-block:: toml
[build-system]
requires = [
"setuptools",
"incremental>=24.7.2", # ← Add incremental as a build dependency
]
build-backend = "setuptools.build_meta"
[project]
name = "<projectname>"
dynamic = ["version"] # ← Mark the version dynamic
dependencies = [
"incremental>=24.7.2", # ← Depend on incremental at runtime
]
# ...
[tool.incremental] # ← Activate Incremental's setuptools plugin
It's fine if the ``[tool.incremental]`` table is empty, but it must be present.
Remove any ``[project] version =`` entry and any ``[tool.setuptools.dynamic] version =`` entry.
Next, `initialize the project`_.
Using Hatchling
~~~~~~~~~~~~~~~
If you're using `Hatchling <https://hatch.pypa.io/>`_ to package your project,
activate Incremental's Hatchling plugin by altering your ``pyproject.toml``:
.. code:: toml
[build-system]
requires = [
"hatchling",
"incremental>=24.7.2", # ← Add incremental as a build dependency
]
build-backend = "hatchling.build"
[project]
name = "<projectname>"
dynamic = ["version"] # ← Mark the version dynamic
dependencies = [
"incremental>=24.7.2", # ← Depend on incremental at runtime
]
# ...
[tool.hatch.version]
source = "incremental" # ← Activate Incremental's Hatchling plugin
Incremental can be configured as usual in an optional ``[tool.incremental]`` table.
The ``hatch version`` command will report the Incremental-managed version.
Use the ``python -m incremental.update`` command to change the version (setting it with ``hatch version`` is not supported).
Next, `initialize the project`_.
Using ``setup.py``
~~~~~~~~~~~~~~~~~~
Incremental may be used from ``setup.py`` instead of ``pyproject.toml``.
Add this to your ``setup()`` call, removing any other versioning arguments:
.. code:: python
setup(
use_incremental=True,
setup_requires=['incremental'],
install_requires=['incremental'], # along with any other install dependencies
...
}
Then `initialize the project`_.
Initialize the project
~~~~~~~~~~~~~~~~~~~~~~
Install Incremental to your local environment with ``pip install incremental[scripts]``.
Then run ``python -m incremental.update <projectname> --create``.
It will create a file in your package named ``_version.py`` like this:
.. code:: python
from incremental import Version
__version__ = Version("<projectname>", 24, 1, 0)
__all__ = ["__version__"]
Then, so users of your project can find your version, in your root package's ``__init__.py`` add:
.. code:: python
from ._version import __version__
Subsequent installations of your project will then use Incremental for versioning.
Incremental Versions
--------------------
``incremental.Version`` is a class that represents a version of a given project.
It is made up of the following elements (which are given during instantiation):
- ``package`` (required), the name of the package this ``Version`` represents.
- ``major``, ``minor``, ``micro`` (all required), the X.Y.Z of your project's ``Version``.
- ``release_candidate`` (optional), set to 0 or higher to mark this ``Version`` being of a release candidate (also sometimes called a "prerelease").
- ``post`` (optional), set to 0 or higher to mark this ``Version`` as a postrelease.
- ``dev`` (optional), set to 0 or higher to mark this ``Version`` as a development release.
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"``.
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]'``.
Updating
--------
Incremental includes a tool to automate updating your Incremental-using project's version called ``incremental.update``.
It updates the ``_version.py`` file and automatically updates some uses of Incremental versions from an indeterminate version to the current one.
It requires ``click`` from PyPI.
``python -m incremental.update <projectname>`` will perform updates on that package.
The commands that can be given after that will determine what the next version is.
- ``--newversion=<version>``, to set the project version to a fully-specified version (like 1.2.3, or 17.1.0dev1).
- ``--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.
- ``--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.
- ``--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.
- ``--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.
If you give no arguments, it will strip the release candidate number, making it a "full release".
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:
- ``Version("<projectname>", "NEXT", 0, 0)``
- ``<projectname> NEXT``
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):
- ``Version("<projectname>", 17, 1, 0, release_candidate=1)``
- ``<projectname> 17.1.0rc1``
Once the final version is made, it will become:
- ``Version("<projectname>", 17, 1, 0)``
- ``<projectname> 17.1.0``
.. |coverage| image:: https://codecov.io/gh/twisted/incremental/branch/master/graph/badge.svg?token=K2ieeL887X
.. _coverage: https://codecov.io/gh/twisted/incremental
.. |gha| image:: https://github.com/twisted/incremental/actions/workflows/tests.yaml/badge.svg
.. _gha: https://github.com/twisted/incremental/actions/workflows/tests.yaml
.. |pypi| image:: http://img.shields.io/pypi/v/incremental.svg
.. _pypi: https://pypi.python.org/pypi/incremental
|
