| Name | incremental JSON |
| Version |
24.7.1
JSON |
| download |
| home_page | None |
| Summary | A small library that versions your Python projects. |
| upload_time | 2024-07-27 07:19:11 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
|
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.0", # ← Add incremental as a build dependency
]
build-backend = "setuptools.build_meta"
[project]
name = "<projectname>"
dynamic = ["version"] # ← Mark the version dynamic
dependencies = [
"incremental>=24.7.0", # ← 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.0", # ← Add incremental as a build dependency
]
build-backend = "hatchling.build"
[project]
name = "<projectname>"
dynamic = ["version"] # ← Mark the version dynamic
dependencies = [
"incremental>=24.7.0", # ← 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
Raw data
{
"_id": null,
"home_page": null,
"name": "incremental",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Amber Brown <hawkowl@twistedmatrix.com>",
"keywords": null,
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ea/83/1afcf0023de837cc9102c23ea8d0748d36a062dfe4e69927a73ecccaaba4/incremental-24.7.1.tar.gz",
"platform": null,
"description": "Incremental\n===========\n\n|gha|\n|pypi|\n|coverage|\n\nIncremental is a small library that versions your Python projects.\n\nAPI documentation can be found `here <https://twisted.org/incremental/docs/>`_.\n\n.. contents::\n\nQuick Start\n-----------\n\nUsing setuptools\n~~~~~~~~~~~~~~~~\n\nAdd Incremental to your ``pyproject.toml``:\n\n.. code-block:: toml\n\n [build-system]\n requires = [\n \"setuptools\",\n \"incremental>=24.7.0\", # \u2190 Add incremental as a build dependency\n ]\n build-backend = \"setuptools.build_meta\"\n\n [project]\n name = \"<projectname>\"\n dynamic = [\"version\"] # \u2190 Mark the version dynamic\n dependencies = [\n \"incremental>=24.7.0\", # \u2190 Depend on incremental at runtime\n ]\n # ...\n\n [tool.incremental] # \u2190 Activate Incremental's setuptools plugin\n\nIt's fine if the ``[tool.incremental]`` table is empty, but it must be present.\n\nRemove any ``[project] version =`` entry and any ``[tool.setuptools.dynamic] version =`` entry.\n\nNext, `initialize the project`_.\n\nUsing Hatchling\n~~~~~~~~~~~~~~~\n\nIf you're using `Hatchling <https://hatch.pypa.io/>`_ to package your project,\nactivate Incremental's Hatchling plugin by altering your ``pyproject.toml``:\n\n.. code:: toml\n\n [build-system]\n requires = [\n \"hatchling\",\n \"incremental>=24.7.0\", # \u2190 Add incremental as a build dependency\n ]\n build-backend = \"hatchling.build\"\n\n [project]\n name = \"<projectname>\"\n dynamic = [\"version\"] # \u2190 Mark the version dynamic\n dependencies = [\n \"incremental>=24.7.0\", # \u2190 Depend on incremental at runtime\n ]\n # ...\n\n [tool.hatch.version]\n source = \"incremental\" # \u2190 Activate Incremental's Hatchling plugin\n\nIncremental can be configured as usual in an optional ``[tool.incremental]`` table.\n\nThe ``hatch version`` command will report the Incremental-managed version.\nUse the ``python -m incremental.update`` command to change the version (setting it with ``hatch version`` is not supported).\n\nNext, `initialize the project`_.\n\n\nUsing ``setup.py``\n~~~~~~~~~~~~~~~~~~\n\nIncremental may be used from ``setup.py`` instead of ``pyproject.toml``.\nAdd this to your ``setup()`` call, removing any other versioning arguments:\n\n.. code:: python\n\n setup(\n use_incremental=True,\n setup_requires=['incremental'],\n install_requires=['incremental'], # along with any other install dependencies\n ...\n }\n\nThen `initialize the project`_.\n\n\nInitialize the project\n~~~~~~~~~~~~~~~~~~~~~~\n\nInstall Incremental to your local environment with ``pip install incremental[scripts]``.\nThen run ``python -m incremental.update <projectname> --create``.\nIt will create a file in your package named ``_version.py`` like this:\n\n.. code:: python\n\n from incremental import Version\n\n __version__ = Version(\"<projectname>\", 24, 1, 0)\n __all__ = [\"__version__\"]\n\n\nThen, so users of your project can find your version, in your root package's ``__init__.py`` add:\n\n.. code:: python\n\n from ._version import __version__\n\n\nSubsequent installations of your project will then use Incremental for versioning.\n\n\n\nIncremental Versions\n--------------------\n\n``incremental.Version`` is a class that represents a version of a given project.\nIt is made up of the following elements (which are given during instantiation):\n\n- ``package`` (required), the name of the package this ``Version`` represents.\n- ``major``, ``minor``, ``micro`` (all required), the X.Y.Z of your project's ``Version``.\n- ``release_candidate`` (optional), set to 0 or higher to mark this ``Version`` being of a release candidate (also sometimes called a \"prerelease\").\n- ``post`` (optional), set to 0 or higher to mark this ``Version`` as a postrelease.\n- ``dev`` (optional), set to 0 or higher to mark this ``Version`` as a development release.\n\nYou 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\"``.\n\nCalling ``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]'``.\n\n\nUpdating\n--------\n\nIncremental includes a tool to automate updating your Incremental-using project's version called ``incremental.update``.\nIt updates the ``_version.py`` file and automatically updates some uses of Incremental versions from an indeterminate version to the current one.\nIt requires ``click`` from PyPI.\n\n``python -m incremental.update <projectname>`` will perform updates on that package.\nThe commands that can be given after that will determine what the next version is.\n\n- ``--newversion=<version>``, to set the project version to a fully-specified version (like 1.2.3, or 17.1.0dev1).\n- ``--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.\n- ``--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.\n- ``--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.\n- ``--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.\n\nIf you give no arguments, it will strip the release candidate number, making it a \"full release\".\n\nIncremental 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:\n\n- ``Version(\"<projectname>\", \"NEXT\", 0, 0)``\n- ``<projectname> NEXT``\n\nWhen you run ``python -m incremental.update <projectname> --rc``, these will be updated to real versions (assuming the target final version is 17.1.0):\n\n- ``Version(\"<projectname>\", 17, 1, 0, release_candidate=1)``\n- ``<projectname> 17.1.0rc1``\n\nOnce the final version is made, it will become:\n\n- ``Version(\"<projectname>\", 17, 1, 0)``\n- ``<projectname> 17.1.0``\n\n\n.. |coverage| image:: https://codecov.io/gh/twisted/incremental/branch/master/graph/badge.svg?token=K2ieeL887X\n.. _coverage: https://codecov.io/gh/twisted/incremental\n\n.. |gha| image:: https://github.com/twisted/incremental/actions/workflows/tests.yaml/badge.svg\n.. _gha: https://github.com/twisted/incremental/actions/workflows/tests.yaml\n\n.. |pypi| image:: http://img.shields.io/pypi/v/incremental.svg\n.. _pypi: https://pypi.python.org/pypi/incremental\n",
"bugtrack_url": null,
"license": null,
"summary": "A small library that versions your Python projects.",
"version": "24.7.1",
"project_urls": {
"Changelog": "https://github.com/twisted/incremental/blob/trunk/NEWS.rst",
"Documentation": "https://twisted.org/incremental/docs/",
"Homepage": "https://github.com/twisted/incremental",
"Issues": "https://github.com/twisted/incremental/issues"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "faf1981251a2b7ada8040264ed71de2524d50b7a7daea8c0df29b7bd9bf94e53",
"md5": "28d1143bcae03d372680c7aa66ecc319",
"sha256": "fdec6e533d06fd5497080fad4d8b78416c98801588551c9e620409940e8745f7"
},
"downloads": -1,
"filename": "incremental-24.7.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "28d1143bcae03d372680c7aa66ecc319",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 20089,
"upload_time": "2024-07-27T07:19:09",
"upload_time_iso_8601": "2024-07-27T07:19:09.513164Z",
"url": "https://files.pythonhosted.org/packages/fa/f1/981251a2b7ada8040264ed71de2524d50b7a7daea8c0df29b7bd9bf94e53/incremental-24.7.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "ea831afcf0023de837cc9102c23ea8d0748d36a062dfe4e69927a73ecccaaba4",
"md5": "e3d53d88c2e00e361105e6180e2c47e5",
"sha256": "a3717c20534499835555ba727b32ee087945ba9daaf23851471dfe3d1e3d1698"
},
"downloads": -1,
"filename": "incremental-24.7.1.tar.gz",
"has_sig": false,
"md5_digest": "e3d53d88c2e00e361105e6180e2c47e5",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 26768,
"upload_time": "2024-07-27T07:19:11",
"upload_time_iso_8601": "2024-07-27T07:19:11.000480Z",
"url": "https://files.pythonhosted.org/packages/ea/83/1afcf0023de837cc9102c23ea8d0748d36a062dfe4e69927a73ecccaaba4/incremental-24.7.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-27 07:19:11",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "twisted",
"github_project": "incremental",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"tox": true,
"lcname": "incremental"
}
