| Name | simple-git-versioning JSON |
| Version |
0.2.5
JSON |
| download |
| home_page | |
| Summary | Thinly scoped and opinionated tool that computes a version number from git tags and trailers |
| upload_time | 2024-02-02 00:30:36 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | <4,>=3.8.1 |
| license | MIT |
| keywords |
versioning
git
git-trailers
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
Opinionated version numbering CLIs, and library
--------------------------------------------------------------------------------
This project aims at easing the burden of computing and managing a project's
version numbers by leveraging `git` tags and commit trailers.
`simple-git-versioning` provides two CLIs: `semver2` and `pep440`, one for each
supported versioning sheme of the same name: [`SemVer2`](https://semver.org) and
[`PEP440`](https://peps.python.org/pep-0440/).
Integration with [`setuptools`](#setuptools) is supported.
Snippets to expose your project's version number programatically are provided in
the [`Libraries`](#libraries) section.
# Installation
With `pip`:
```python
pip install simple-git-versioning
```
# Usage
By default, `pep440` and `semver2` will compute a version number of the form
`X.Y.Z`. Every project starts at `0.0.0` on their initial commit, and each
commit after that increments the number `Z` by one, unless they include a
`Version-Bump` trailer (case-insensitive) with a value of:
- `major`: `X` is incremented;
- `minor`: `Y` is incremented;
- `patch`: `Z` is incremented (same as the default).
Each tool then provides the ability to _switch_ to a pre-release mode; or
post-release, and/or dev release, etc. in the case of `pep440`.
## CLIs
All CLIs provide comprehensive help messages, available via the `--help` option.
## Libraries
Libraries that wish to expose their version number programatically may do so by
including the following snippet:
### `PEP440`
```python
from importlib.metadata import PackageNotFoundError, version
from pathlib import Path
from versioning.pep440 import NoVersion, Project
try:
__version__ = version("<your python package's name>")
except PackageNotFoundError:
# package is not installed
with Project(path=Path(__file__).parent) as project:
try:
__version__ = str(project.version())
except NoVersion:
__version__ = str(project.release(dev=0))
```
### `SemVer2`
```python
from importlib.metadata import PackageNotFoundError, version
from pathlib import Path
from versioning.semver2 import NoVersion, Project
try:
__version__ = version("<your python package's name>")
except PackageNotFoundError:
# package is not installed
with Project(path=Path(__file__).parent) as project:
try:
__version__ = str(project.version())
except NoVersion:
__version__ = str(project.release(pre=("dev", 0))
```
## `poetry`
If you use `poetry` as a build frontend and backend for your project, you can
configure `simple-git-versioning` to derive a version automatically as follows:
Install `simple-git-versioning` alongside `poetry`:
```bash
poetry self add "simple-git-versioning>=0.2"
```
Enable the `poetry` integration in your `pyproject.toml`, and pick the
versioning scheme you wish to apply:
```toml
[tool.poetry]
...
[tool.simple-git-versioning]
poetry = "pep440" # or "semver2"
```
> Note that `poetry` mandates a `version` always be set in `pyproject.toml`, so
> you will have to keep a placeholder there (e.g. `version: "0.0.0"`).
## `setuptools`
If you use `setuptools` as a build backend for your project, you can configure
`simple-git-versioning` to derive a version automatically as follows:
In your `pyproject.toml`:
- declare `version` as a dynamic metadata field;
- add `simple-git-versioning` to your project's `build-system.requires`;
- enable the `setuptools` integration in your `pyproject.toml`, and pick the
versioning scheme you wish to apply.
```toml
[project]
name = ...
dynamic = ["version"]
[build-system]
requires = ["setuptools>=63", "simple-git-versioning"]
build-backend = "setuptools.build_meta"
[tool.simple-git-versioning]
setuptools = "pep440" # or "semver2"
```
> I recommend checking out [`setuptools-scm`](https://pypi.org/project/setuptools-scm/)
and [`setuptools-pipfile`](https://pypi.org/project/setuptools-pipfile/), two
other `setuptools` extensions I find greatly helpful.
Raw data
{
"_id": null,
"home_page": "",
"name": "simple-git-versioning",
"maintainer": "",
"docs_url": null,
"requires_python": "<4,>=3.8.1",
"maintainer_email": "",
"keywords": "versioning,git,git-trailers",
"author": "",
"author_email": "Quentin Bouget <ypsah@devyard.org>",
"download_url": "https://files.pythonhosted.org/packages/a9/56/c9ab6d0e0ab7f6852f003d5b7719f71d831125d6656c396721867511ade0/simple-git-versioning-0.2.5.tar.gz",
"platform": null,
"description": "Opinionated version numbering CLIs, and library\n\n--------------------------------------------------------------------------------\n\nThis project aims at easing the burden of computing and managing a project's\nversion numbers by leveraging `git` tags and commit trailers.\n\n`simple-git-versioning` provides two CLIs: `semver2` and `pep440`, one for each\nsupported versioning sheme of the same name: [`SemVer2`](https://semver.org) and \n[`PEP440`](https://peps.python.org/pep-0440/).\n\nIntegration with [`setuptools`](#setuptools) is supported.\n\nSnippets to expose your project's version number programatically are provided in\nthe [`Libraries`](#libraries) section.\n\n# Installation\n\nWith `pip`:\n\n```python\npip install simple-git-versioning\n```\n\n# Usage\n\nBy default, `pep440` and `semver2` will compute a version number of the form\n`X.Y.Z`. Every project starts at `0.0.0` on their initial commit, and each\ncommit after that increments the number `Z` by one, unless they include a\n`Version-Bump` trailer (case-insensitive) with a value of:\n- `major`: `X` is incremented;\n- `minor`: `Y` is incremented;\n- `patch`: `Z` is incremented (same as the default).\n\nEach tool then provides the ability to _switch_ to a pre-release mode; or\npost-release, and/or dev release, etc. in the case of `pep440`.\n\n## CLIs\n\nAll CLIs provide comprehensive help messages, available via the `--help` option.\n\n## Libraries\n\nLibraries that wish to expose their version number programatically may do so by\nincluding the following snippet:\n\n### `PEP440`\n\n```python\nfrom importlib.metadata import PackageNotFoundError, version\nfrom pathlib import Path\n\nfrom versioning.pep440 import NoVersion, Project\n\ntry:\n __version__ = version(\"<your python package's name>\")\nexcept PackageNotFoundError:\n # package is not installed\n with Project(path=Path(__file__).parent) as project:\n try:\n __version__ = str(project.version())\n except NoVersion:\n __version__ = str(project.release(dev=0))\n```\n\n### `SemVer2`\n\n```python\nfrom importlib.metadata import PackageNotFoundError, version\nfrom pathlib import Path\n\nfrom versioning.semver2 import NoVersion, Project\n\ntry:\n __version__ = version(\"<your python package's name>\")\nexcept PackageNotFoundError:\n # package is not installed\n with Project(path=Path(__file__).parent) as project:\n try:\n __version__ = str(project.version())\n except NoVersion:\n __version__ = str(project.release(pre=(\"dev\", 0))\n```\n\n## `poetry`\n\nIf you use `poetry` as a build frontend and backend for your project, you can\nconfigure `simple-git-versioning` to derive a version automatically as follows:\n\nInstall `simple-git-versioning` alongside `poetry`:\n\n```bash\npoetry self add \"simple-git-versioning>=0.2\"\n```\n\nEnable the `poetry` integration in your `pyproject.toml`, and pick the\nversioning scheme you wish to apply:\n\n```toml\n[tool.poetry]\n...\n\n[tool.simple-git-versioning]\npoetry = \"pep440\" # or \"semver2\"\n```\n\n> Note that `poetry` mandates a `version` always be set in `pyproject.toml`, so\n> you will have to keep a placeholder there (e.g. `version: \"0.0.0\"`).\n\n## `setuptools`\n\nIf you use `setuptools` as a build backend for your project, you can configure\n`simple-git-versioning` to derive a version automatically as follows:\n\nIn your `pyproject.toml`:\n - declare `version` as a dynamic metadata field;\n - add `simple-git-versioning` to your project's `build-system.requires`;\n - enable the `setuptools` integration in your `pyproject.toml`, and pick the\n versioning scheme you wish to apply.\n\n```toml\n[project]\nname = ...\ndynamic = [\"version\"]\n\n[build-system]\nrequires = [\"setuptools>=63\", \"simple-git-versioning\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[tool.simple-git-versioning]\nsetuptools = \"pep440\" # or \"semver2\"\n```\n\n> I recommend checking out [`setuptools-scm`](https://pypi.org/project/setuptools-scm/)\n and [`setuptools-pipfile`](https://pypi.org/project/setuptools-pipfile/), two\n other `setuptools` extensions I find greatly helpful.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Thinly scoped and opinionated tool that computes a version number from git tags and trailers",
"version": "0.2.5",
"project_urls": {
"homepage": "https://gitlab.com/ypsah/simple-git-versioning",
"repository": "https://gitlab.com/ypsah/simple-git-versioning"
},
"split_keywords": [
"versioning",
"git",
"git-trailers"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "f039764a6be98ed9e83657b22ffb5555419b2dfa513ea98e35c3cde477da0c2c",
"md5": "74ec4134c6da2ab21a164d1228039fe4",
"sha256": "4b5c4733354a350bdefcc5353505655397a305fbe48b768a821e0ef3f9d90693"
},
"downloads": -1,
"filename": "simple_git_versioning-0.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "74ec4134c6da2ab21a164d1228039fe4",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8.1",
"size": 16702,
"upload_time": "2024-02-02T00:30:35",
"upload_time_iso_8601": "2024-02-02T00:30:35.037648Z",
"url": "https://files.pythonhosted.org/packages/f0/39/764a6be98ed9e83657b22ffb5555419b2dfa513ea98e35c3cde477da0c2c/simple_git_versioning-0.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a956c9ab6d0e0ab7f6852f003d5b7719f71d831125d6656c396721867511ade0",
"md5": "e757e31b42788ae4a4aae1111c094180",
"sha256": "876d31ff12a3b7dd158ff0147c2cb06becf1f86a9bb75f019326fa39107f1202"
},
"downloads": -1,
"filename": "simple-git-versioning-0.2.5.tar.gz",
"has_sig": false,
"md5_digest": "e757e31b42788ae4a4aae1111c094180",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8.1",
"size": 61688,
"upload_time": "2024-02-02T00:30:36",
"upload_time_iso_8601": "2024-02-02T00:30:36.446706Z",
"url": "https://files.pythonhosted.org/packages/a9/56/c9ab6d0e0ab7f6852f003d5b7719f71d831125d6656c396721867511ade0/simple-git-versioning-0.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-02 00:30:36",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "ypsah",
"gitlab_project": "simple-git-versioning",
"lcname": "simple-git-versioning"
}
