# AwesomeVersion
[](https://codecov.io/gh/ludeeus/awesomeversion)
[](https://pypi.org/project/awesomeversion)
_One version package to rule them all, One version package to find them, One version package to bring them all, and in the darkness bind them._
Make anything a version object, and compare against a vast section of other version formats.
## Installation
```bash
python3 -m pip install awesomeversion
```
## AwesomeVersion class
The AwesomeVersion class takes a version as the first argument, you can also pass in additional kwargs to customize the version object.
Argument | Description
--- | ---
`version` | The version string to parse.
`ensure_strategy` | Match the `AwesomeVersion` object against spesific strategies when creating if. If it does not match `AwesomeVersionStrategyException` will be raised
`find_first_match` | If True, the version given will be scanned for the first match of the given `ensure_strategy`. Raises `AwesomeVersionStrategyException` If it is not found for any of the given strategies.
## AwesomeVersion methods
<details>
<summary><code>AwesomeVersion.in_range</code></summary>
This is a helper method to check if the version is in a range.
This method takes two arguments, `lowest` and `highest`, both are required, and returns a boolean.
> **Note** This method is the same as doing `lowest <= AwesomeVersion <= highest`
Example:
```python
from awesomeversion import AwesomeVersion
print(AwesomeVersion("1.2.2").in_range("1.2.1", "1.3"))
> True
print(AwesomeVersion("1.2.0").in_range("1.2.1", "1.3"))
> False
```
</details>
<details>
<summary><code>AwesomeVersion.diff</code></summary>
This is a helper method to get the difference between two versions.
This method takes one argument which is the version to compare against, and returns a `AwesomeVersionDiff` object.
> **Note** This method is the same as doing `AwesomeVersion - version`
Example:
```python
from awesomeversion import AwesomeVersion
> print(AwesomeVersion("1.0").diff("2.1"))
AwesomeVersionDiff(major=True, minor=True, patch=False, modifier=False, strategy=False)
```
</details>
<details>
<summary><code>AwesomeVersion.section</code></summary>
This is a helper method to get a section of the version.
This method takes one argument which is the section to get, and returns an integer representing it (or 0 if it does not exist).
Example:
```python
from awesomeversion import AwesomeVersion
> print(AwesomeVersion("1.0").section(0))
1
```
</details>
## AwesomeVersion properties
Argument | Description
--- | ---
`alpha` | This is a boolean representing if the version is an alpha version.
`beta` | This is a boolean representing if the version is a beta version.
`dev` | This is a boolean representing if the version is a dev version.
`major` | This is an `AwesomeVersion` object representing the major version or `None` if not present.
`micro` | This is an `AwesomeVersion` object representing the micro version or `None` if not present.
`minor` | This is an `AwesomeVersion` object representing the minor version or `None` if not present.
`modifier_type` | This is a string representing the modifier type of the version or `None` if not present.
`modifier` | This is a string representing the modifier of the version or `None` if not present.
`patch` | This is an `AwesomeVersion` object representing the patch version or `None` if not present.
`prefix` | This is the prefix of the version or `None` if not present.
`release_candidate` | This is a boolean representing if the version is a release candidate version.
`simple` | This is a boolean representing if the version is a simple version.
`strategy_description` | This is a `AwesomeVersionStrategyDescription` object representing the strategy description of the version.
`strategy` | This is a `AwesomeVersionStrategy` object representing the strategy of the version.
`string` | This is the string representation of the version (without the v prefix if present).
`valid` | This is a boolean representing if the version is valid (not unknown strategy).
`year` | This is alias to `major`, and is an `AwesomeVersion` object representing the year.
## Example usage
Here are some examples of how you can use this package, more examples can be found in the `tests` directory.
<details>
<summary><code>Basic compare</code></summary>
```python
from awesomeversion import AwesomeVersion
current = AwesomeVersion("1.2.2")
upstream = AwesomeVersion("1.2.3")
print(upstream > current)
> True
```
</details>
<details>
<summary><code>Compare beta version</code></summary>
```python
from awesomeversion import AwesomeVersion
current = AwesomeVersion("2021.1.0")
upstream = AwesomeVersion("2021.1.0b2")
print(current > upstream)
> True
```
</details>
<details>
<summary><code>Check if version is a beta version</code></summary>
```python
from awesomeversion import AwesomeVersion
print(AwesomeVersion("1.2.3b0").beta)
> True
print(AwesomeVersion("1.2.3").beta)
> False
```
</details>
<details>
<summary>Use <code>AwesomeVersion</code> with <code>with ...</code></summary>
```python
from awesomeversion import AwesomeVersion
with AwesomeVersion("20.12.0") as current:
with AwesomeVersion("20.12.1") as upstream:
print(upstream > current)
> True
```
</details>
<details>
<summary>Compare <code>AwesomeVersion</code> with other non-<code>AwesomeVersion</code> formats</summary>
```python
from awesomeversion import AwesomeVersion
base = AwesomeVersion("20.12.0")
print(base > "20.12.1")
> False
print(base > "19")
> True
print(base > 5)
> True
```
</details>
## General behavior
You can test your versions on the [demo page][awesomeversion_demo].
### Modifiers
When comparing versions with modifiers, if the base version is the same the modifier will be used to determine the order.
If one of the versions do not have a modifier, the one without will be considered newer.
The order of the modifiers are:
- No modifier
- RC
- Beta
- Alpha
- Dev
<details>
<summary>Examples</summary>
```python
from awesomeversion import AwesomeVersion
print(AwesomeVersion("1.0.0") > AwesomeVersion("1.0.0b6"))
> True
print(AwesomeVersion("1.0.0") > AwesomeVersion("1.0.0.dev6"))
> True
print(AwesomeVersion("1.0.0.dev19") > AwesomeVersion("1.0.0b4"))
> False
```
</details>
### Special versions (container)
There are some special versions for container that are handled differently than typical version formats.
The special versions are in the following order:
- `dev` (newest)
- `latest`
- `beta`
- `stable` (oldest)
If only the first version is this special version, it will be considered newer.
If only the second version is this special version, it will be considered older.
<details>
<summary>Examples</summary>
```python
from awesomeversion import AwesomeVersion
print(AwesomeVersion("latest") > AwesomeVersion("1.0.0b6"))
> True
print(AwesomeVersion("1.0.0") > AwesomeVersion("latest"))
> False
print(AwesomeVersion("stable") > AwesomeVersion("latest"))
> False
print(AwesomeVersion("beta") > AwesomeVersion("dev"))
> False
```
</details>
## Contribute
**All** contributions are welcome!
1. Fork the repository
2. Clone the repository locally and open the devcontainer or use GitHub codespaces
3. Do your changes
4. Lint the files with `make lint`
5. Ensure all tests passes with `make test`
6. Ensure 100% coverage with `make coverage`
7. Commit your work, and push it to GitHub
8. Create a PR against the `main` branch
[awesomeversion_demo]: https://ludeeus.github.io/awesomeversion/
Raw data
{
"_id": null,
"home_page": "https://github.com/ludeeus/awesomeversion",
"name": "awesomeversion",
"maintainer": "Ludeeus",
"docs_url": null,
"requires_python": ">=3.8,<4.0",
"maintainer_email": "ludeeus@ludeeus.dev",
"keywords": "calver,semver,0ver,version,pep440,buildver",
"author": "Ludeeus",
"author_email": "ludeeus@ludeeus.dev",
"download_url": "https://files.pythonhosted.org/packages/a6/9f/fcc3018c04703bac014acc7f7043d8db6929a330757bccbbfbbf6b034867/awesomeversion-24.2.0.tar.gz",
"platform": null,
"description": "# AwesomeVersion\n\n[](https://codecov.io/gh/ludeeus/awesomeversion)\n\n\n[](https://pypi.org/project/awesomeversion)\n\n\n_One version package to rule them all, One version package to find them, One version package to bring them all, and in the darkness bind them._\n\nMake anything a version object, and compare against a vast section of other version formats.\n\n## Installation\n\n```bash\npython3 -m pip install awesomeversion\n```\n\n## AwesomeVersion class\n\nThe AwesomeVersion class takes a version as the first argument, you can also pass in additional kwargs to customize the version object.\n\nArgument | Description\n--- | ---\n`version` | The version string to parse.\n`ensure_strategy` | Match the `AwesomeVersion` object against spesific strategies when creating if. If it does not match `AwesomeVersionStrategyException` will be raised\n`find_first_match` | If True, the version given will be scanned for the first match of the given `ensure_strategy`. Raises `AwesomeVersionStrategyException` If it is not found for any of the given strategies.\n\n## AwesomeVersion methods\n\n<details>\n<summary><code>AwesomeVersion.in_range</code></summary>\n\nThis is a helper method to check if the version is in a range.\nThis method takes two arguments, `lowest` and `highest`, both are required, and returns a boolean.\n\n> **Note** This method is the same as doing `lowest <= AwesomeVersion <= highest`\n\nExample:\n\n```python\nfrom awesomeversion import AwesomeVersion\nprint(AwesomeVersion(\"1.2.2\").in_range(\"1.2.1\", \"1.3\"))\n> True\nprint(AwesomeVersion(\"1.2.0\").in_range(\"1.2.1\", \"1.3\"))\n> False\n```\n\n</details>\n\n<details>\n<summary><code>AwesomeVersion.diff</code></summary>\n\nThis is a helper method to get the difference between two versions.\nThis method takes one argument which is the version to compare against, and returns a `AwesomeVersionDiff` object.\n\n> **Note** This method is the same as doing `AwesomeVersion - version`\n\nExample:\n\n```python\nfrom awesomeversion import AwesomeVersion\n> print(AwesomeVersion(\"1.0\").diff(\"2.1\"))\nAwesomeVersionDiff(major=True, minor=True, patch=False, modifier=False, strategy=False)\n```\n\n</details>\n\n\n<details>\n<summary><code>AwesomeVersion.section</code></summary>\n\nThis is a helper method to get a section of the version.\nThis method takes one argument which is the section to get, and returns an integer representing it (or 0 if it does not exist).\n\nExample:\n\n```python\nfrom awesomeversion import AwesomeVersion\n> print(AwesomeVersion(\"1.0\").section(0))\n1\n```\n\n</details>\n\n\n## AwesomeVersion properties\n\nArgument | Description\n--- | ---\n`alpha` | This is a boolean representing if the version is an alpha version.\n`beta` | This is a boolean representing if the version is a beta version.\n`dev` | This is a boolean representing if the version is a dev version.\n`major` | This is an `AwesomeVersion` object representing the major version or `None` if not present.\n`micro` | This is an `AwesomeVersion` object representing the micro version or `None` if not present.\n`minor` | This is an `AwesomeVersion` object representing the minor version or `None` if not present.\n`modifier_type` | This is a string representing the modifier type of the version or `None` if not present.\n`modifier` | This is a string representing the modifier of the version or `None` if not present.\n`patch` | This is an `AwesomeVersion` object representing the patch version or `None` if not present.\n`prefix` | This is the prefix of the version or `None` if not present.\n`release_candidate` | This is a boolean representing if the version is a release candidate version.\n`simple` | This is a boolean representing if the version is a simple version.\n`strategy_description` | This is a `AwesomeVersionStrategyDescription` object representing the strategy description of the version.\n`strategy` | This is a `AwesomeVersionStrategy` object representing the strategy of the version.\n`string` | This is the string representation of the version (without the v prefix if present).\n`valid` | This is a boolean representing if the version is valid (not unknown strategy).\n`year` | This is alias to `major`, and is an `AwesomeVersion` object representing the year.\n\n\n## Example usage\n\nHere are some examples of how you can use this package, more examples can be found in the `tests` directory.\n\n<details>\n<summary><code>Basic compare</code></summary>\n\n```python\nfrom awesomeversion import AwesomeVersion\n\ncurrent = AwesomeVersion(\"1.2.2\")\nupstream = AwesomeVersion(\"1.2.3\")\n\nprint(upstream > current)\n> True\n```\n\n</details>\n\n<details>\n<summary><code>Compare beta version</code></summary>\n\n```python\nfrom awesomeversion import AwesomeVersion\n\ncurrent = AwesomeVersion(\"2021.1.0\")\nupstream = AwesomeVersion(\"2021.1.0b2\")\n\nprint(current > upstream)\n> True\n```\n\n</details>\n\n<details>\n<summary><code>Check if version is a beta version</code></summary>\n\n```python\nfrom awesomeversion import AwesomeVersion\n\nprint(AwesomeVersion(\"1.2.3b0\").beta)\n> True\n\nprint(AwesomeVersion(\"1.2.3\").beta)\n> False\n```\n\n</details>\n\n<details>\n<summary>Use <code>AwesomeVersion</code> with <code>with ...</code></summary>\n\n```python\nfrom awesomeversion import AwesomeVersion\n\nwith AwesomeVersion(\"20.12.0\") as current:\n with AwesomeVersion(\"20.12.1\") as upstream:\n print(upstream > current)\n> True\n```\n\n</details>\n\n<details>\n<summary>Compare <code>AwesomeVersion</code> with other non-<code>AwesomeVersion</code> formats</summary>\n\n```python\nfrom awesomeversion import AwesomeVersion\n\nbase = AwesomeVersion(\"20.12.0\")\n\nprint(base > \"20.12.1\")\n> False\n\nprint(base > \"19\")\n> True\n\nprint(base > 5)\n> True\n```\n\n</details>\n\n\n## General behavior\n\nYou can test your versions on the [demo page][awesomeversion_demo].\n\n### Modifiers\n\nWhen comparing versions with modifiers, if the base version is the same the modifier will be used to determine the order.\nIf one of the versions do not have a modifier, the one without will be considered newer.\n\nThe order of the modifiers are:\n- No modifier\n- RC\n- Beta\n- Alpha\n- Dev\n\n<details>\n<summary>Examples</summary>\n\n```python\nfrom awesomeversion import AwesomeVersion\n\nprint(AwesomeVersion(\"1.0.0\") > AwesomeVersion(\"1.0.0b6\"))\n> True\nprint(AwesomeVersion(\"1.0.0\") > AwesomeVersion(\"1.0.0.dev6\"))\n> True\nprint(AwesomeVersion(\"1.0.0.dev19\") > AwesomeVersion(\"1.0.0b4\"))\n> False\n```\n\n</details>\n\n\n### Special versions (container)\n\nThere are some special versions for container that are handled differently than typical version formats.\nThe special versions are in the following order:\n- `dev` (newest)\n- `latest`\n- `beta`\n- `stable` (oldest)\n\nIf only the first version is this special version, it will be considered newer.\nIf only the second version is this special version, it will be considered older.\n\n\n<details>\n<summary>Examples</summary>\n\n```python\nfrom awesomeversion import AwesomeVersion\n\nprint(AwesomeVersion(\"latest\") > AwesomeVersion(\"1.0.0b6\"))\n> True\nprint(AwesomeVersion(\"1.0.0\") > AwesomeVersion(\"latest\"))\n> False\nprint(AwesomeVersion(\"stable\") > AwesomeVersion(\"latest\"))\n> False\nprint(AwesomeVersion(\"beta\") > AwesomeVersion(\"dev\"))\n> False\n```\n\n</details>\n\n\n\n\n## Contribute\n\n**All** contributions are welcome!\n\n1. Fork the repository\n2. Clone the repository locally and open the devcontainer or use GitHub codespaces\n3. Do your changes\n4. Lint the files with `make lint`\n5. Ensure all tests passes with `make test`\n6. Ensure 100% coverage with `make coverage`\n7. Commit your work, and push it to GitHub\n8. Create a PR against the `main` branch\n\n\n[awesomeversion_demo]: https://ludeeus.github.io/awesomeversion/\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "One version package to rule them all, One version package to find them, One version package to bring them all, and in the darkness bind them.",
"version": "24.2.0",
"project_urls": {
"Homepage": "https://github.com/ludeeus/awesomeversion",
"Repository": "https://github.com/ludeeus/awesomeversion"
},
"split_keywords": [
"calver",
"semver",
"0ver",
"version",
"pep440",
"buildver"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "9937c1a78ddd853e2db9d509994f57063f75e70b21844585f38f37867c423f50",
"md5": "bea625328d7ee88e04f79d12ef3d0514",
"sha256": "ba365d1ad4e42aa5afdbc46b639f349e52db2d859d7c46a34744ca15ebf1430a"
},
"downloads": -1,
"filename": "awesomeversion-24.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bea625328d7ee88e04f79d12ef3d0514",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8,<4.0",
"size": 13946,
"upload_time": "2024-02-06T19:35:42",
"upload_time_iso_8601": "2024-02-06T19:35:42.775900Z",
"url": "https://files.pythonhosted.org/packages/99/37/c1a78ddd853e2db9d509994f57063f75e70b21844585f38f37867c423f50/awesomeversion-24.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "a69ffcc3018c04703bac014acc7f7043d8db6929a330757bccbbfbbf6b034867",
"md5": "42a4f17e7abfff9c7aec11dc58707147",
"sha256": "47a6dcbbe2921b725f75106a66ab30f26f1f33dbc5e07bc8e1e39d8eb921f53c"
},
"downloads": -1,
"filename": "awesomeversion-24.2.0.tar.gz",
"has_sig": false,
"md5_digest": "42a4f17e7abfff9c7aec11dc58707147",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8,<4.0",
"size": 12040,
"upload_time": "2024-02-06T19:35:45",
"upload_time_iso_8601": "2024-02-06T19:35:45.554966Z",
"url": "https://files.pythonhosted.org/packages/a6/9f/fcc3018c04703bac014acc7f7043d8db6929a330757bccbbfbbf6b034867/awesomeversion-24.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-06 19:35:45",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ludeeus",
"github_project": "awesomeversion",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "awesomeversion"
}
JSON
