| Name | simple-git-versioning JSON |
| Version |
0.3.2
JSON |
| download |
| home_page | None |
| Summary | Thinly scoped and opinionated tool that computes a version number from git tags and trailers |
| upload_time | 2025-02-17 20:08:46 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <4,>=3.8.1 |
| license | MIT |
| keywords |
git
git-trailers
versioning
|
| 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))
```
## `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[setuptools]"]
build-backend = "setuptools.build_meta"
[tool.simple-git-versioning.setuptools]
# scheme = "pep440" (default) or "semver2"
```
## `hatchling`
If you use `hatchling` 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 `hatchling` integration in your `pyproject.toml`, and pick the
versioning scheme you wish to apply.
```toml
[project]
name = ...
dynamic = ["version"]
[build-system]
requires = ["hatchling", "simple-git-versioning[hatchling]"]
build-backend = "hatchling.build"
[tool.hatch.version]
source = "simple-git-versioning"
# scheme = "pep440" (default) or "semver2"
```
## `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[poetry]"
```
Enable the `poetry` integration in your `pyproject.toml`, and optionally pick
the versioning scheme you wish to apply:
```toml
[tool.poetry]
...
[tool.simple-git-versioning.poetry]
# scheme = "pep440" (default) 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"`).
Raw data
{
"_id": null,
"home_page": null,
"name": "simple-git-versioning",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.8.1",
"maintainer_email": null,
"keywords": "git, git-trailers, versioning",
"author": null,
"author_email": "Quentin Bouget <ypsah@devyard.org>",
"download_url": "https://files.pythonhosted.org/packages/f1/fc/2b0ee5fa7e45515e4a79809c10d53a80323942a30099c95797de908b8242/simple_git_versioning-0.3.2.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## `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[setuptools]\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[tool.simple-git-versioning.setuptools]\n# scheme = \"pep440\" (default) or \"semver2\"\n```\n\n## `hatchling`\n\nIf you use `hatchling` 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 `hatchling` 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 = [\"hatchling\", \"simple-git-versioning[hatchling]\"]\nbuild-backend = \"hatchling.build\"\n\n[tool.hatch.version]\nsource = \"simple-git-versioning\"\n# scheme = \"pep440\" (default) or \"semver2\"\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[poetry]\"\n```\n\nEnable the `poetry` integration in your `pyproject.toml`, and optionally pick\nthe versioning scheme you wish to apply:\n\n```toml\n[tool.poetry]\n...\n\n[tool.simple-git-versioning.poetry]\n# scheme = \"pep440\" (default) 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",
"bugtrack_url": null,
"license": "MIT",
"summary": "Thinly scoped and opinionated tool that computes a version number from git tags and trailers",
"version": "0.3.2",
"project_urls": {
"homepage": "https://gitlab.com/ypsah/simple-git-versioning",
"repository": "https://gitlab.com/ypsah/simple-git-versioning"
},
"split_keywords": [
"git",
" git-trailers",
" versioning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e180d010c58260537961e405a2bc2b3b82de125a8d7854203f277e81cdbf1889",
"md5": "d1e177889fed088a83f68b40eecec25d",
"sha256": "65d82717fe486c7dd667eba92990de9108eba294a458f03d90d8598445a0c270"
},
"downloads": -1,
"filename": "simple_git_versioning-0.3.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d1e177889fed088a83f68b40eecec25d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8.1",
"size": 17313,
"upload_time": "2025-02-17T20:08:43",
"upload_time_iso_8601": "2025-02-17T20:08:43.430573Z",
"url": "https://files.pythonhosted.org/packages/e1/80/d010c58260537961e405a2bc2b3b82de125a8d7854203f277e81cdbf1889/simple_git_versioning-0.3.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f1fc2b0ee5fa7e45515e4a79809c10d53a80323942a30099c95797de908b8242",
"md5": "85ff614d3d27472d611a5b9215a79b72",
"sha256": "25bb3904d83b090686104f3c90d3bf59ea043ec07dc8a4845bfb03905d9b8ad7"
},
"downloads": -1,
"filename": "simple_git_versioning-0.3.2.tar.gz",
"has_sig": false,
"md5_digest": "85ff614d3d27472d611a5b9215a79b72",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8.1",
"size": 17170021,
"upload_time": "2025-02-17T20:08:46",
"upload_time_iso_8601": "2025-02-17T20:08:46.930208Z",
"url": "https://files.pythonhosted.org/packages/f1/fc/2b0ee5fa7e45515e4a79809c10d53a80323942a30099c95797de908b8242/simple_git_versioning-0.3.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-17 20:08:46",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "ypsah",
"gitlab_project": "simple-git-versioning",
"lcname": "simple-git-versioning"
}
