Debian Codegraph @

PKG-INFO

raw
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