# Antares Study Version
[](https://pypi.org/project/antares-study-version)
[](https://pypi.org/project/antares-study-version)
-----
**Table of Contents**
- [Overview](#overview)
- [Installation](#installation)
- [Usage](#usage)
- [StudyVersion](#studyversion)
- [SolverVersion](#solverversion)
- [Pydantic model](#pydantic-model)
- [Development](#development)
- [Development tasks](#development-tasks)
- [Building the package](#building-the-package)
- [License](#license)
- [Changelog](CHANGELOG.md)
## Overview
The `antares-study-version` package defines `StudyVersion` and `SolverVersion` classes to manage version numbers.
It can be used to manage the version of a study, but also the version
of [Antares Solver](https://github.com/AntaresSimulatorTeam/Antares_Simulator).
It supports the [semver](https://semver.org/) format ("major.minor.patch") and the integer format
(major×100 + minor×10 + patch), which is specific to Antares.
This module harmonizes the management of versions in Antares:
- at the level of Antares studies (configuration files, database, etc.)
- at the level of Antares applications, in particular [AntaREST](https://github.com/AntaresSimulatorTeam/AntaREST/).
In the data of a study and in the programs, we encounter several version formats:
- dotted string (ex. `"8.7"` or `"8.7.2"`),
- compact string (ex. `"870"`),
- integer (ex. `870`).
- tuples or lists (ex. `(8, 7)` or `[8, 7, 2]`).
- dictionaries (ex. `{"major": 8, "minor": 7, "patch": 2}`).
For instance, since
[version 9.0](https://antares-simulator.readthedocs.io/en/latest/reference-guide/13-file-format/#v900)
of Antares Solver, versions are stored as dotted strings;
the compact format is now obsolete (backward compatibility is ensured for versions prior to 9.0);
For instance, the `study.antares` configuration file now uses the "X.Y" format for the study version instead
of the "XYZ" format.
```ini
[antares]
version = 9.1
caption = My Study
created = 1618413128
lastsave = 1625583204
author = John DOE
```
This module allows to convert these formats to each other, and to compare versions.
## Installation
```console
pip install antares-study-version
```
## Usage
This package provides a `StudyVersion` class to manage study version numbers,
and a `SolverVersion` class to manage Antares Solver version numbers.
The difference between `StudyVersion` and `SolverVersion` is that Solver versions are generally on 3 digits
(with the `major`, `minor` and `patch` components), while study versions are on 2 digits
(with the `major` and `minor` components only), and the `patch` component is not used (always 0).
### StudyVersion
Using the `antares-study-version` module is straightforward:
```python
from antares.study.version import StudyVersion
version = StudyVersion(8, 7, 2) # patch component is not used
print(version) # 8.7
```
You can also create a version object from a dotted string:
```python
from antares.study.version import StudyVersion
version = StudyVersion.parse("8.7")
print(version) # 8.7
```
You can create a version object from a compact string:
```python
from antares.study.version import StudyVersion
version = StudyVersion.parse("870")
print(version) # 8.7
```
You can create a version object from an integer:
```python
from antares.study.version import StudyVersion
version = StudyVersion.parse(870)
print(version) # 8.7
```
You can compare versions:
```python
from antares.study.version import StudyVersion
version1 = StudyVersion(8, 6)
version2 = StudyVersion(8, 7)
print(version1 < version2) # True
```
You can convert a version to string using format specifiers:
```python
from antares.study.version import StudyVersion
version = StudyVersion(8, 7)
print(f"{version}") # 8.7
print(f"{version:02d}") # 08.07
print(f"{version:03d}") # 08.07.00
print(f"{version:ddd}") # 870
```
You can convert a version to an integer:
```python
from antares.study.version import StudyVersion
version = StudyVersion(8, 7)
print(int(version)) # 870
```
### SolverVersion
Of course, the same operations can be done with `SolverVersion` objects, but with 3 digits:
```python
from antares.study.version import SolverVersion
version = SolverVersion(8, 7, 2)
print(version) # 8.7.2
```
Objects of the `StudyVersion` and `SolverVersion` classes can be compared to each other:
```python
from antares.study.version import StudyVersion, SolverVersion
study_version = StudyVersion(8, 7)
solver_version = SolverVersion(8, 7, 2)
print(study_version <= solver_version) # True
```
### Pydantic model
You can even use the `StudyVersion` or `SolverVersion` classes in a Pydantic model:
```python
import datetime
import typing as t
import uuid
from pydantic import BaseModel, Field, validator
from antares.study.version import StudyVersion
class StudyDTO(BaseModel):
id: uuid.UUID = Field(default_factory=lambda: uuid.uuid4())
name: str
version: StudyVersion
created: datetime.datetime = Field(default_factory=lambda: datetime.datetime.now(tz=datetime.timezone.utc))
@validator("version", pre=True)
def _validate_version(cls, v: t.Any) -> StudyVersion:
return StudyVersion.parse(v)
study = StudyDTO(name="foo", version=StudyVersion(4, 5))
obj = study.json()
print(obj)
# {
# "created": "2024-12-31T12:30:00+00:00",
# "id": "4930a577-63d2-4ea9-b0b9-581110d97475",
# "name": "foo",
# "version": {"major": 4, "minor": 5, "patch": 0}
# }
```
## Development
This projet uses [Hach](https://hatch.pypa.io/latest/) to manage the development environment.
### Project setup
➢ To install the [development environment](https://hatch.pypa.io/latest/environment/), run:
```shell
hatch env create
```
> See [hatch env create](https://hatch.pypa.io/latest/cli/reference/#hatch-env-create) documentation
This command will create a virtual environment and install the development dependencies.
> NOTE: `hatch` creates a virtual environment in the `~/.local/share/hatch/env/virtual/antares-study-version` directory.
➢ To activate the virtual environment, run:
```shell
hatch shell
```
> See [hatch shell](https://hatch.pypa.io/latest/cli/reference/#hatch-shell) documentation
This command will spawn a new shell with the virtual environment activated. Use Ctrl+D to exit the shell.
> NOTE: this command will display the full path to the virtual environment.
> You can use it to configure PyCharm or Visual Studio Code to use this virtual environment.
### Development tasks
➢ To format and lint the source code with [ruff](https://docs.astral.sh/ruff/), run:
```shell
hatch fmt
```
> See [hatch fmt](https://hatch.pypa.io/latest/cli/reference/#hatch-fmt) documentation
➢ To run the tests on the current Python version, run:
```shell
hatch run test
```
> See [hatch run](https://hatch.pypa.io/latest/cli/reference/#hatch-run) documentation
➢ To run the tests on Python 3.12, for example, run:
```shell
hatch run all.py3.12:test
```
➢ To generate the test coverage report, run:
```shell
hatch run cov
```
This command will run the unit tests and generate a coverage report in the `htmlcov` directory.
➢ To check the typing with [mypy](http://mypy-lang.org/), run:
```shell
hatch run types:check
```
➢ To check the typing on unit tests, run:
```shell
hatch run types:check-tests
```
### Building the package
➢ To build the package, run:
```shell
hatch build
```
This command will create a `dist` directory with the built package.
➢ To build the package and upload it to [PyPI](https://pypi.org/), run:
```shell
hatch publish
```
➢ To clean the project, run:
```shell
hatch clean
```
This command will remove the `dist` directory.
## License
`antares-study-version` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.
Raw data
{
"_id": null,
"home_page": null,
"name": "antares-study-version",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "antares, config, configuration, model, study, versionning",
"author": null,
"author_email": "Laurent LAPORTE <laurent.laporte.pro@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/a0/c8/b24c77755f236a06f01f44393524ce236bcda38de135b9ca4f44b2abc403/antares_study_version-0.1.1.tar.gz",
"platform": null,
"description": "# Antares Study Version\n\n[](https://pypi.org/project/antares-study-version)\n[](https://pypi.org/project/antares-study-version)\n\n-----\n\n**Table of Contents**\n\n- [Overview](#overview)\n- [Installation](#installation)\n- [Usage](#usage)\n - [StudyVersion](#studyversion)\n - [SolverVersion](#solverversion)\n - [Pydantic model](#pydantic-model)\n- [Development](#development)\n - [Development tasks](#development-tasks)\n - [Building the package](#building-the-package)\n- [License](#license)\n- [Changelog](CHANGELOG.md)\n\n## Overview\n\nThe `antares-study-version` package defines `StudyVersion` and `SolverVersion` classes to manage version numbers.\nIt can be used to manage the version of a study, but also the version\nof [Antares Solver](https://github.com/AntaresSimulatorTeam/Antares_Simulator).\nIt supports the [semver](https://semver.org/) format (\"major.minor.patch\") and the integer format\n(major\u00d7100 + minor\u00d710 + patch), which is specific to Antares.\n\nThis module harmonizes the management of versions in Antares:\n\n- at the level of Antares studies (configuration files, database, etc.)\n- at the level of Antares applications, in particular [AntaREST](https://github.com/AntaresSimulatorTeam/AntaREST/).\n\nIn the data of a study and in the programs, we encounter several version formats:\n\n- dotted string (ex. `\"8.7\"` or `\"8.7.2\"`),\n- compact string (ex. `\"870\"`),\n- integer (ex. `870`).\n- tuples or lists (ex. `(8, 7)` or `[8, 7, 2]`).\n- dictionaries (ex. `{\"major\": 8, \"minor\": 7, \"patch\": 2}`).\n\nFor instance, since\n[version 9.0](https://antares-simulator.readthedocs.io/en/latest/reference-guide/13-file-format/#v900)\nof Antares Solver, versions are stored as dotted strings;\nthe compact format is now obsolete (backward compatibility is ensured for versions prior to 9.0);\n\nFor instance, the `study.antares` configuration file now uses the \"X.Y\" format for the study version instead\nof the \"XYZ\" format.\n\n```ini\n[antares]\nversion = 9.1\ncaption = My Study\ncreated = 1618413128\nlastsave = 1625583204\nauthor = John DOE\n```\n\nThis module allows to convert these formats to each other, and to compare versions.\n\n## Installation\n\n```console\npip install antares-study-version\n```\n\n## Usage\n\nThis package provides a `StudyVersion` class to manage study version numbers,\nand a `SolverVersion` class to manage Antares Solver version numbers.\n\nThe difference between `StudyVersion` and `SolverVersion` is that Solver versions are generally on 3 digits\n(with the `major`, `minor` and `patch` components), while study versions are on 2 digits\n(with the `major` and `minor` components only), and the `patch` component is not used (always 0).\n\n### StudyVersion\n\nUsing the `antares-study-version` module is straightforward:\n\n```python\nfrom antares.study.version import StudyVersion\n\nversion = StudyVersion(8, 7, 2) # patch component is not used\nprint(version) # 8.7\n```\n\nYou can also create a version object from a dotted string:\n\n```python\nfrom antares.study.version import StudyVersion\n\nversion = StudyVersion.parse(\"8.7\")\nprint(version) # 8.7\n```\n\nYou can create a version object from a compact string:\n\n```python\nfrom antares.study.version import StudyVersion\n\nversion = StudyVersion.parse(\"870\")\nprint(version) # 8.7\n```\n\nYou can create a version object from an integer:\n\n```python\nfrom antares.study.version import StudyVersion\n\nversion = StudyVersion.parse(870)\nprint(version) # 8.7\n```\n\nYou can compare versions:\n\n```python\nfrom antares.study.version import StudyVersion\n\nversion1 = StudyVersion(8, 6)\nversion2 = StudyVersion(8, 7)\nprint(version1 < version2) # True\n```\n\nYou can convert a version to string using format specifiers:\n\n```python\nfrom antares.study.version import StudyVersion\n\nversion = StudyVersion(8, 7)\nprint(f\"{version}\") # 8.7\nprint(f\"{version:02d}\") # 08.07\nprint(f\"{version:03d}\") # 08.07.00\nprint(f\"{version:ddd}\") # 870\n```\n\nYou can convert a version to an integer:\n\n```python\nfrom antares.study.version import StudyVersion\n\nversion = StudyVersion(8, 7)\nprint(int(version)) # 870\n```\n\n### SolverVersion\n\nOf course, the same operations can be done with `SolverVersion` objects, but with 3 digits:\n\n```python\nfrom antares.study.version import SolverVersion\n\nversion = SolverVersion(8, 7, 2)\nprint(version) # 8.7.2\n```\n\nObjects of the `StudyVersion` and `SolverVersion` classes can be compared to each other:\n\n```python\nfrom antares.study.version import StudyVersion, SolverVersion\n\nstudy_version = StudyVersion(8, 7)\nsolver_version = SolverVersion(8, 7, 2)\nprint(study_version <= solver_version) # True\n```\n\n### Pydantic model\n\nYou can even use the `StudyVersion` or `SolverVersion` classes in a Pydantic model:\n\n```python\nimport datetime\nimport typing as t\nimport uuid\n\nfrom pydantic import BaseModel, Field, validator\n\nfrom antares.study.version import StudyVersion\n\n\nclass StudyDTO(BaseModel):\n id: uuid.UUID = Field(default_factory=lambda: uuid.uuid4())\n name: str\n version: StudyVersion\n created: datetime.datetime = Field(default_factory=lambda: datetime.datetime.now(tz=datetime.timezone.utc))\n\n @validator(\"version\", pre=True)\n def _validate_version(cls, v: t.Any) -> StudyVersion:\n return StudyVersion.parse(v)\n\n\nstudy = StudyDTO(name=\"foo\", version=StudyVersion(4, 5))\nobj = study.json()\nprint(obj)\n# {\n# \"created\": \"2024-12-31T12:30:00+00:00\",\n# \"id\": \"4930a577-63d2-4ea9-b0b9-581110d97475\",\n# \"name\": \"foo\",\n# \"version\": {\"major\": 4, \"minor\": 5, \"patch\": 0}\n# }\n```\n\n## Development\n\nThis projet uses [Hach](https://hatch.pypa.io/latest/) to manage the development environment.\n\n### Project setup\n\n\u27a2 To install the [development environment](https://hatch.pypa.io/latest/environment/), run:\n\n```shell\nhatch env create\n```\n\n> See [hatch env create](https://hatch.pypa.io/latest/cli/reference/#hatch-env-create) documentation\n\nThis command will create a virtual environment and install the development dependencies.\n\n> NOTE: `hatch` creates a virtual environment in the `~/.local/share/hatch/env/virtual/antares-study-version` directory.\n\n\u27a2 To activate the virtual environment, run:\n\n```shell\nhatch shell\n```\n\n> See [hatch shell](https://hatch.pypa.io/latest/cli/reference/#hatch-shell) documentation\n\nThis command will spawn a new shell with the virtual environment activated. Use Ctrl+D to exit the shell.\n\n> NOTE: this command will display the full path to the virtual environment.\n> You can use it to configure PyCharm or Visual Studio Code to use this virtual environment.\n\n### Development tasks\n\n\u27a2 To format and lint the source code with [ruff](https://docs.astral.sh/ruff/), run:\n\n```shell\nhatch fmt\n```\n\n> See [hatch fmt](https://hatch.pypa.io/latest/cli/reference/#hatch-fmt) documentation\n\n\u27a2 To run the tests on the current Python version, run:\n\n```shell\nhatch run test\n```\n\n> See [hatch run](https://hatch.pypa.io/latest/cli/reference/#hatch-run) documentation\n\n\u27a2 To run the tests on Python 3.12, for example, run:\n\n```shell\nhatch run all.py3.12:test\n```\n\n\u27a2 To generate the test coverage report, run:\n\n```shell\nhatch run cov\n```\n\nThis command will run the unit tests and generate a coverage report in the `htmlcov` directory.\n\n\u27a2 To check the typing with [mypy](http://mypy-lang.org/), run:\n\n```shell\nhatch run types:check\n```\n\n\u27a2 To check the typing on unit tests, run:\n\n```shell\nhatch run types:check-tests\n```\n\n### Building the package\n\n\u27a2 To build the package, run:\n\n```shell\nhatch build\n```\n\nThis command will create a `dist` directory with the built package.\n\n\u27a2 To build the package and upload it to [PyPI](https://pypi.org/), run:\n\n```shell\nhatch publish\n```\n\n\u27a2 To clean the project, run:\n\n```shell\nhatch clean\n```\n\nThis command will remove the `dist` directory.\n\n## License\n\n`antares-study-version` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.\n",
"bugtrack_url": null,
"license": null,
"summary": "Antares Study (and Solver) version number models",
"version": "0.1.1",
"project_urls": {
"Documentation": "https://github.com/AntaresSimulatorTeam/antares-study-version#readme",
"Issues": "https://github.com/AntaresSimulatorTeam/antares-study-version/issues",
"Source": "https://github.com/AntaresSimulatorTeam/antares-study-version"
},
"split_keywords": [
"antares",
" config",
" configuration",
" model",
" study",
" versionning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "0445186287cbb6dae2a9625e1072024637f73cdff5d1abf39329d073884db6a9",
"md5": "4300c5558563d44270ddd860f6c64df9",
"sha256": "59b44b79c99f4154f531c63a4425c017a741435318f2be130ffbe7f993e5e0b3"
},
"downloads": -1,
"filename": "antares_study_version-0.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4300c5558563d44270ddd860f6c64df9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 7510,
"upload_time": "2024-04-10T06:39:54",
"upload_time_iso_8601": "2024-04-10T06:39:54.261039Z",
"url": "https://files.pythonhosted.org/packages/04/45/186287cbb6dae2a9625e1072024637f73cdff5d1abf39329d073884db6a9/antares_study_version-0.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "a0c8b24c77755f236a06f01f44393524ce236bcda38de135b9ca4f44b2abc403",
"md5": "31a49fc0cdae57c77e3ab4cd6593b0c9",
"sha256": "7d29ee7b9d49153d7357db1f278cf86b1cf910fc8e4c493bd7da9955a6e7db39"
},
"downloads": -1,
"filename": "antares_study_version-0.1.1.tar.gz",
"has_sig": false,
"md5_digest": "31a49fc0cdae57c77e3ab4cd6593b0c9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 14812,
"upload_time": "2024-04-10T06:39:52",
"upload_time_iso_8601": "2024-04-10T06:39:52.546048Z",
"url": "https://files.pythonhosted.org/packages/a0/c8/b24c77755f236a06f01f44393524ce236bcda38de135b9ca4f44b2abc403/antares_study_version-0.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-10 06:39:52",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "AntaresSimulatorTeam",
"github_project": "antares-study-version#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "antares-study-version"
}
JSON
