# `versions`
[![License][License Badge]][License]
[![Version][Version Badge]][Package]
[![Downloads][Downloads Badge]][Package]
[![Discord][Discord Badge]][Discord]
[![Documentation][Documentation Badge]][Documentation]
[![Check][Check Badge]][Actions]
[![Test][Test Badge]][Actions]
[![Coverage][Coverage Badge]][Coverage]
> *Parsing, inspecting and specifying versions.*
## Installing
**Python 3.8 or above is required.**
### pip
Installing the library with `pip` is quite simple:
```console
$ pip install versions
```
Alternatively, the library can be installed from source:
```console
$ git clone https://github.com/nekitdev/versions.git
$ cd versions
$ python -m pip install .
```
### poetry
You can add `versions` as a dependency with the following command:
```console
$ poetry add versions
```
Or by directly specifying it in the configuration like so:
```toml
[tool.poetry.dependencies]
versions = "^2.1.2"
```
Alternatively, you can add it directly from the source:
```toml
[tool.poetry.dependencies.versions]
git = "https://github.com/nekitdev/versions.git"
```
## Examples
### Versions
[`parse_version`][versions.functions.parse_version] is used to parse versions:
```python
from versions import parse_version
version = parse_version("1.0.0-dev.1+build.1")
print(version) # 1.0.0-dev.1+build.1
```
### Segments
All version segments can be fetched with their respective names:
```python
>>> print(version.release)
1.0.0
>>> version.release.parts
(1, 0, 0)
>>> print(version.dev)
dev.1
>>> (version.dev.phase, version.dev.value)
("dev", 1)
>>> print(version.local)
build.1
>>> version.local.parts
("build", 1)
```
### Comparison
Versions support total ordering:
```python
>>> v1 = parse_version("1.0.0")
>>> v2 = parse_version("2.0.0")
>>> v1 == v2
False
>>> v1 != v2
True
>>> v1 >= v2
False
>>> v1 <= v2
True
>>> v1 > v2
False
>>> v1 < v2
True
```
### Specification
`versions` also supports specifying version requirements and matching version against them.
Since versions support total ordering, they can be checked using *version sets*
(via [`parse_version_set`][versions.functions.parse_version_set]):
```python
>>> from versions import parse_version, parse_version_set
>>> version_set = parse_version_set("^1.0.0")
>>> version_set
<VersionRange (>= 1.0.0, < 2.0.0)>
>>> version = parse_version("1.3.0")
>>> version.matches(version_set)
True
>>> another = parse_version("2.2.0")
>>> another.matches(version_set)
False
```
Alternatively, one can use *specifiers*, which are similar to version sets, except they retain
the structure of specifications given (via [`parse_specifier`][versions.functions.parse_specifier]):
```python
>>> from versions import parse_specifier, parse_version
>>> specifier = parse_specifier("^1.0.0")
>>> specifier
<SpecifierOne (^1.0.0)>
>>> version = parse_version("1.3.0")
>>> version.matches(specifier)
True
>>> another = parse_version("2.2.0")
>>> another.matches(specifier)
False
```
## Versioned
`versions` allows users to access versions of items that have the `__version__` attribute:
```python
>>> from versions import get_version
>>> import versions
>>> get_version(versions)
<Version (2.1.2)>
```
## Documentation
You can find the documentation [here][Documentation].
## Support
If you need support with the library, you can send an [email][Email]
or refer to the official [Discord server][Discord].
## Changelog
You can find the changelog [here][Changelog].
## Security Policy
You can find the Security Policy of `versions` [here][Security].
## Contributing
If you are interested in contributing to `versions`, make sure to take a look at the
[Contributing Guide][Contributing Guide], as well as the [Code of Conduct][Code of Conduct].
## License
`versions` is licensed under the MIT License terms. See [License][License] for details.
[Email]: mailto:support@nekit.dev
[Discord]: https://nekit.dev/discord
[Actions]: https://github.com/nekitdev/versions/actions
[Changelog]: https://github.com/nekitdev/versions/blob/main/CHANGELOG.md
[Code of Conduct]: https://github.com/nekitdev/versions/blob/main/CODE_OF_CONDUCT.md
[Contributing Guide]: https://github.com/nekitdev/versions/blob/main/CONTRIBUTING.md
[Security]: https://github.com/nekitdev/versions/blob/main/SECURITY.md
[License]: https://github.com/nekitdev/versions/blob/main/LICENSE
[Package]: https://pypi.org/project/versions
[Coverage]: https://codecov.io/gh/nekitdev/versions
[Documentation]: https://nekitdev.github.io/versions
[Discord Badge]: https://img.shields.io/badge/chat-discord-5865f2
[License Badge]: https://img.shields.io/pypi/l/versions
[Version Badge]: https://img.shields.io/pypi/v/versions
[Downloads Badge]: https://img.shields.io/pypi/dm/versions
[Documentation Badge]: https://github.com/nekitdev/versions/workflows/docs/badge.svg
[Check Badge]: https://github.com/nekitdev/versions/workflows/check/badge.svg
[Test Badge]: https://github.com/nekitdev/versions/workflows/test/badge.svg
[Coverage Badge]: https://codecov.io/gh/nekitdev/versions/branch/main/graph/badge.svg
[versions.functions.parse_specifier]: https://nekitdev.github.io/versions/reference/functions#versions.functions.parse_specifier
[versions.functions.parse_version]: https://nekitdev.github.io/versions/reference/functions#versions.functions.parse_version
[versions.functions.parse_version_set]: https://nekitdev.github.io/versions/reference/functions#versions.functions.parse_version_set
Raw data
{
"_id": null,
"home_page": "https://github.com/nekitdev/versions",
"name": "versions",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "python,semver,version",
"author": "nekitdev",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/28/62/bf254f5c7d7aa884036ea9cdae13d32803849175d3e4a56c381b88878c33/versions-2.1.2.tar.gz",
"platform": null,
"description": "# `versions`\n\n[![License][License Badge]][License]\n[![Version][Version Badge]][Package]\n[![Downloads][Downloads Badge]][Package]\n[![Discord][Discord Badge]][Discord]\n\n[![Documentation][Documentation Badge]][Documentation]\n[![Check][Check Badge]][Actions]\n[![Test][Test Badge]][Actions]\n[![Coverage][Coverage Badge]][Coverage]\n\n> *Parsing, inspecting and specifying versions.*\n\n## Installing\n\n**Python 3.8 or above is required.**\n\n### pip\n\nInstalling the library with `pip` is quite simple:\n\n```console\n$ pip install versions\n```\n\nAlternatively, the library can be installed from source:\n\n```console\n$ git clone https://github.com/nekitdev/versions.git\n$ cd versions\n$ python -m pip install .\n```\n\n### poetry\n\nYou can add `versions` as a dependency with the following command:\n\n```console\n$ poetry add versions\n```\n\nOr by directly specifying it in the configuration like so:\n\n```toml\n[tool.poetry.dependencies]\nversions = \"^2.1.2\"\n```\n\nAlternatively, you can add it directly from the source:\n\n```toml\n[tool.poetry.dependencies.versions]\ngit = \"https://github.com/nekitdev/versions.git\"\n```\n\n## Examples\n\n### Versions\n\n[`parse_version`][versions.functions.parse_version] is used to parse versions:\n\n```python\nfrom versions import parse_version\n\nversion = parse_version(\"1.0.0-dev.1+build.1\")\n\nprint(version) # 1.0.0-dev.1+build.1\n```\n\n### Segments\n\nAll version segments can be fetched with their respective names:\n\n```python\n>>> print(version.release)\n1.0.0\n>>> version.release.parts\n(1, 0, 0)\n>>> print(version.dev)\ndev.1\n>>> (version.dev.phase, version.dev.value)\n(\"dev\", 1)\n>>> print(version.local)\nbuild.1\n>>> version.local.parts\n(\"build\", 1)\n```\n\n### Comparison\n\nVersions support total ordering:\n\n```python\n>>> v1 = parse_version(\"1.0.0\")\n>>> v2 = parse_version(\"2.0.0\")\n>>> v1 == v2\nFalse\n>>> v1 != v2\nTrue\n>>> v1 >= v2\nFalse\n>>> v1 <= v2\nTrue\n>>> v1 > v2\nFalse\n>>> v1 < v2\nTrue\n```\n\n### Specification\n\n`versions` also supports specifying version requirements and matching version against them.\n\nSince versions support total ordering, they can be checked using *version sets*\n(via [`parse_version_set`][versions.functions.parse_version_set]):\n\n```python\n>>> from versions import parse_version, parse_version_set\n>>> version_set = parse_version_set(\"^1.0.0\")\n>>> version_set\n<VersionRange (>= 1.0.0, < 2.0.0)>\n>>> version = parse_version(\"1.3.0\")\n>>> version.matches(version_set)\nTrue\n>>> another = parse_version(\"2.2.0\")\n>>> another.matches(version_set)\nFalse\n```\n\nAlternatively, one can use *specifiers*, which are similar to version sets, except they retain\nthe structure of specifications given (via [`parse_specifier`][versions.functions.parse_specifier]):\n\n```python\n>>> from versions import parse_specifier, parse_version\n>>> specifier = parse_specifier(\"^1.0.0\")\n>>> specifier\n<SpecifierOne (^1.0.0)>\n>>> version = parse_version(\"1.3.0\")\n>>> version.matches(specifier)\nTrue\n>>> another = parse_version(\"2.2.0\")\n>>> another.matches(specifier)\nFalse\n```\n\n## Versioned\n\n`versions` allows users to access versions of items that have the `__version__` attribute:\n\n```python\n>>> from versions import get_version\n>>> import versions\n>>> get_version(versions)\n<Version (2.1.2)>\n```\n\n## Documentation\n\nYou can find the documentation [here][Documentation].\n\n## Support\n\nIf you need support with the library, you can send an [email][Email]\nor refer to the official [Discord server][Discord].\n\n## Changelog\n\nYou can find the changelog [here][Changelog].\n\n## Security Policy\n\nYou can find the Security Policy of `versions` [here][Security].\n\n## Contributing\n\nIf you are interested in contributing to `versions`, make sure to take a look at the\n[Contributing Guide][Contributing Guide], as well as the [Code of Conduct][Code of Conduct].\n\n## License\n\n`versions` is licensed under the MIT License terms. See [License][License] for details.\n\n[Email]: mailto:support@nekit.dev\n\n[Discord]: https://nekit.dev/discord\n\n[Actions]: https://github.com/nekitdev/versions/actions\n\n[Changelog]: https://github.com/nekitdev/versions/blob/main/CHANGELOG.md\n[Code of Conduct]: https://github.com/nekitdev/versions/blob/main/CODE_OF_CONDUCT.md\n[Contributing Guide]: https://github.com/nekitdev/versions/blob/main/CONTRIBUTING.md\n[Security]: https://github.com/nekitdev/versions/blob/main/SECURITY.md\n\n[License]: https://github.com/nekitdev/versions/blob/main/LICENSE\n\n[Package]: https://pypi.org/project/versions\n[Coverage]: https://codecov.io/gh/nekitdev/versions\n[Documentation]: https://nekitdev.github.io/versions\n\n[Discord Badge]: https://img.shields.io/badge/chat-discord-5865f2\n[License Badge]: https://img.shields.io/pypi/l/versions\n[Version Badge]: https://img.shields.io/pypi/v/versions\n[Downloads Badge]: https://img.shields.io/pypi/dm/versions\n\n[Documentation Badge]: https://github.com/nekitdev/versions/workflows/docs/badge.svg\n[Check Badge]: https://github.com/nekitdev/versions/workflows/check/badge.svg\n[Test Badge]: https://github.com/nekitdev/versions/workflows/test/badge.svg\n[Coverage Badge]: https://codecov.io/gh/nekitdev/versions/branch/main/graph/badge.svg\n\n[versions.functions.parse_specifier]: https://nekitdev.github.io/versions/reference/functions#versions.functions.parse_specifier\n[versions.functions.parse_version]: https://nekitdev.github.io/versions/reference/functions#versions.functions.parse_version\n[versions.functions.parse_version_set]: https://nekitdev.github.io/versions/reference/functions#versions.functions.parse_version_set\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Parsing, inspecting and specifying versions.",
"version": "2.1.2",
"project_urls": {
"Chat": "https://nekit.dev/chat",
"Documentation": "https://nekitdev.github.io/versions",
"Funding": "https://nekit.dev/funding",
"Homepage": "https://github.com/nekitdev/versions",
"Issues": "https://github.com/nekitdev/versions/issues",
"Repository": "https://github.com/nekitdev/versions"
},
"split_keywords": [
"python",
"semver",
"version"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ffe4509d13728f45cc64de68df809419dfdf4bacd60d2545066a7211acd515f0",
"md5": "2349c555502cb8d6001456927d1e4124",
"sha256": "ca0d4968ecb382b351e73128276f166aefef8fba67f37c3d19c03d356c95dfeb"
},
"downloads": -1,
"filename": "versions-2.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2349c555502cb8d6001456927d1e4124",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 42895,
"upload_time": "2024-02-26T12:21:14",
"upload_time_iso_8601": "2024-02-26T12:21:14.273241Z",
"url": "https://files.pythonhosted.org/packages/ff/e4/509d13728f45cc64de68df809419dfdf4bacd60d2545066a7211acd515f0/versions-2.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2862bf254f5c7d7aa884036ea9cdae13d32803849175d3e4a56c381b88878c33",
"md5": "885c1ac87eb15d938f6b10f2bd079a72",
"sha256": "78ff96645a3b1afea09ca2c8482bcca0cd68d816a6a729565502c2eb6f2ef466"
},
"downloads": -1,
"filename": "versions-2.1.2.tar.gz",
"has_sig": false,
"md5_digest": "885c1ac87eb15d938f6b10f2bd079a72",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 35761,
"upload_time": "2024-02-26T12:21:16",
"upload_time_iso_8601": "2024-02-26T12:21:16.078820Z",
"url": "https://files.pythonhosted.org/packages/28/62/bf254f5c7d7aa884036ea9cdae13d32803849175d3e4a56c381b88878c33/versions-2.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-26 12:21:16",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "nekitdev",
"github_project": "versions",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "versions"
}
JSON
