feat: add the show, create and upgrade applications

pyproject.toml

@@ -2,6 +2,7 @@
 requires = ["hatchling"]
 build-backend = "hatchling.build"
 
+
 [project]
 name = "antares-study-version"
 dynamic = ["version"]
@@ -25,17 +26,24 @@ classifiers = [
     "Programming Language :: Python :: Implementation :: PyPy",
 ]
 
-dependencies = []
+dependencies = ["click", "pandas"]
+
 
 [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"
 
+
+[project.scripts]
+antares-study-version = "antares.study.version.cli:cli"
+
+
 [tool.hatch.version]
 path = "src/antares/study/version/__about__.py"
 attr = "__version__"
 
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/antares"]
 
@@ -48,6 +56,7 @@ dependencies = [
     "pytest-freezer<0.5",
 ]
 
+
 [tool.hatch.envs.default.scripts]
 test = "pytest {args:tests}"
 test-cov = "coverage run -m pytest {args:tests}"
@@ -61,6 +70,7 @@ cov = [
     "cov-report",
 ]
 
+
 [[tool.hatch.envs.all.matrix]]
 python = ["3.8", "3.9", "3.10", "3.11", "3.12"]
 
@@ -72,6 +82,8 @@ dependencies = [
     "pytest-freezer<0.5",
     "mypy>=1.0.0",
 ]
+
+
 [tool.hatch.envs.types.scripts]
 check = "mypy --namespace-packages --package antares.study.version --install-types --non-interactive"
 check-tests = "mypy --install-types --non-interactive {args:tests}"
@@ -81,6 +93,7 @@ check-tests = "mypy --install-types --non-interactive {args:tests}"
 detached = true
 dependencies = ["mkdocs"]
 
+
 [tool.hatch.envs.docs.scripts]
 build = "mkdocs build -f mkdocs.yml {args}"
 serve = "mkdocs serve -f mkdocs.yml {args}"
@@ -90,34 +103,39 @@ gh-deploy = "mkdocs gh-deploy -f mkdocs.yml {args}"
 [tool.mypy]
 mypy_path = 'src, tests'
 
+
 [tool.coverage.run]
 source_pkgs = ["antares.study.version", "tests"]
 branch = true
 parallel = true
-omit = [
-]
+omit = []
+
 
 [tool.coverage.paths]
 antares_study_config = ["src/antares/study/version", "*/antares-study-version/src/antares/study/version"]
 tests = ["tests", "*/antares-study-version/tests"]
 
+
 [tool.coverage.report]
 exclude_lines = [
     "no cov",
     "if __name__ == .__main__.:",
     "if TYPE_CHECKING:",
 ]
 
+
 [tool.black]
 target-version = ["py38"]
 line-length = 120
 
+
 [tool.isort]
 profile = "black"
 line_length = 120
 src_paths = ["src", "tests"]
 skip_gitignore = true
 
+
 [tool.ruff]
 # Exclude a variety of commonly ignored directories.
 exclude = [

src/antares/study/version/__init__.py

@@ -2,5 +2,5 @@
 Antares Study (and Solver) version models.
 """
 
-from .model import StudyVersion, SolverVersion  # noqa: F401
 from .converters import version_to_triplet  # noqa: F401
+from .model import SolverVersion, StudyVersion  # noqa: F401

src/antares/study/version/__main__.py

@@ -0,0 +1,15 @@
+"""
+Main entrypoint for the CLI application.
+"""
+
+import sys
+
+from antares.study.version.cli import cli
+
+
+def main():
+    cli(sys.argv[1:])
+
+
+if __name__ == "__main__":
+    main()

src/antares/study/version/cli.py

@@ -0,0 +1,152 @@
+"""
+The CLI module for the study version.
+
+This module defines the following CLI commands:
+
+- antares-study-version show: display the details of a study in human-readable format (name, version, creation date, etc.)
+- antares-study-version create: create a new study.
+"""
+
+import click
+
+from antares.study.version.__about__ import __date__, __version__
+from antares.study.version.create_app import CreateApp, available_versions
+from antares.study.version.exceptions import ApplicationError
+from antares.study.version.show_app import ShowApp
+from antares.study.version.upgrade_app import UpgradeApp
+
+INTERRUPTED_BY_THE_USER = "Operation interrupted by the user."
+
+
+@click.group(context_settings={"max_content_width": 120})
+@click.version_option(package_name="antares-study-version", message=f"v{__version__} ({__date__})")
+def cli() -> None:
+    """
+    Main entrypoint for the CLI application.
+    """
+
+
+@cli.command()
+@click.argument(
+    "study_dir",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, resolve_path=True),
+)
+def show(study_dir: str) -> None:
+    """
+    Display the details of a study in human-readable format.
+
+    STUDY_DIR: The directory containing the study.
+    """
+    try:
+        app = ShowApp(study_dir)  # type: ignore
+    except (ValueError, FileNotFoundError) as e:
+        click.echo(f"Error: {e}", err=True)
+        raise click.Abort()
+
+    try:
+        app()
+    except ApplicationError as e:
+        click.echo(f"Error: {e}", err=True)
+        raise click.Abort()
+    except KeyboardInterrupt:
+        click.echo(INTERRUPTED_BY_THE_USER, err=True)
+        raise click.Abort()
+
+
+def _display_available_versions(ctx: click.Context, _param: click.Option, value: bool) -> None:
+    if not value or ctx.resilient_parsing:
+        return
+    click.echo(f"Available versions: {', '.join(available_versions())}")
+    ctx.exit()
+
+
+@cli.command()
+@click.argument(
+    "study_dir",
+    type=click.Path(exists=False, file_okay=False, dir_okay=True, resolve_path=True),
+)
+@click.option(
+    "-c",
+    "--caption",
+    default="New Study",
+    help="Caption of the study",
+    show_default=True,
+)
+@click.option(
+    "-v",
+    "--version",
+    default=available_versions()[-1],
+    help="Version of the study to create",
+    show_default=True,
+    type=click.Choice(available_versions()),
+)
+@click.option(
+    "-a",
+    "--author",
+    default="Anonymous",
+    help="Author of the study",
+    show_default=True,
+)
+@click.option(
+    "--versions",
+    is_flag=True,
+    callback=_display_available_versions,
+    expose_value=False,
+    is_eager=True,
+    help="Display all available upgrade versions and quit.",
+)
+def create(study_dir: str, caption: str, version: str, author: str) -> None:
+    """
+    Create a new study in the specified directory.
+
+    STUDY_DIR: The directory where the study will be created.
+    """
+    try:
+        app = CreateApp(study_dir, caption=caption, version=version, author=author)  # type: ignore
+    except (ValueError, FileExistsError) as e:
+        click.echo(f"Error: {e}", err=True)
+        raise click.Abort()
+
+    try:
+        app()
+    except ApplicationError as e:
+        click.echo(f"Error: {e}", err=True)
+        raise click.Abort()
+    except KeyboardInterrupt:
+        click.echo(INTERRUPTED_BY_THE_USER, err=True)
+        raise click.Abort()
+
+
+@cli.command()
+@click.argument(
+    "study_dir",
+    type=click.Path(exists=True, file_okay=False, dir_okay=True, resolve_path=True),
+)
+@click.option(
+    "-v",
+    "--version",
+    default=available_versions()[-1],
+    help="Version of the study to create",
+    show_default=True,
+    type=click.Choice(available_versions()),
+)
+def upgrade(study_dir: str, version: str) -> None:
+    """
+    Upgrade a study to a new version.
+
+    STUDY_DIR: The directory containing the study to upgrade.
+    """
+    try:
+        app = UpgradeApp(study_dir, version=version)  # type: ignore
+    except (ValueError, FileNotFoundError) as e:
+        click.echo(f"Error: {e}", err=True)
+        raise click.Abort()
+
+    try:
+        app()
+    except ApplicationError as e:
+        click.echo(f"Error: {e}", err=True)
+        raise click.Abort()
+    except KeyboardInterrupt:
+        click.echo(INTERRUPTED_BY_THE_USER, err=True)
+        raise click.Abort()

src/antares/study/version/create_app/__init__.py

@@ -0,0 +1,78 @@
+import dataclasses
+import datetime
+import typing as t
+import zipfile
+from importlib.resources import contents, open_binary
+from pathlib import Path
+
+from antares.study.version.exceptions import ApplicationError
+from antares.study.version.model.study_antares import StudyAntares
+from antares.study.version.model.study_version import StudyVersion
+
+_RESOURCES_PACKAGE = "antares.study.version.create_app.resources"
+
+
+def get_template_version(template_name: str) -> StudyVersion:
+    template_name = template_name.replace(".zip", "")
+    version_str = template_name.split("_")[-1]  # 880.zip
+    return StudyVersion.parse(version_str)
+
+
+TEMPLATES_BY_VERSIONS: t.Dict[StudyVersion, str] = {
+    get_template_version(name): name for name in contents(_RESOURCES_PACKAGE) if name.endswith(".zip")
+}
+
+
+def available_versions() -> t.List[str]:
+    """
+    Return a list of available template versions.
+
+    Returns:
+        A list of available template versions.
+    """
+    return [f"{ver:2d}" for ver in sorted(TEMPLATES_BY_VERSIONS)]
+
+
+@dataclasses.dataclass
+class CreateApp:
+    """
+    Create a new study.
+    """
+
+    study_dir: Path
+    caption: str
+    version: StudyVersion
+    author: str
+
+    def __post_init__(self):
+        self.study_dir = Path(self.study_dir)
+        self.caption = self.caption.strip()
+        self.version = StudyVersion.parse(self.version)
+        self.author = self.author.strip()
+        if self.study_dir.exists():
+            raise FileExistsError(f"Study directory already exists: '{self.study_dir}'")
+        if not self.caption:
+            raise ValueError("Caption cannot be empty")
+
+    def __call__(self) -> None:
+        try:
+            template_name = TEMPLATES_BY_VERSIONS[self.version]
+        except KeyError:
+            msg = f"No available template for version {self.version}: available templates are {available_versions()}"
+            raise ApplicationError(msg)
+        print(f"Extracting template {template_name} to '{self.study_dir}'...")
+        with open_binary(_RESOURCES_PACKAGE, template_name) as zip_file:
+            with zipfile.ZipFile(zip_file, mode="r") as archive:
+                archive.extractall(self.study_dir)
+
+        creation_date = datetime.datetime.now()
+        study_antares = StudyAntares(
+            version=self.version,
+            caption=self.caption,
+            created_date=creation_date,
+            last_save_date=creation_date,
+            author=self.author,
+        )
+        print("Writing 'study.antares' file...")
+        study_antares.to_ini_file(self.study_dir, update_save_date=False)
+        print(f"Study '{self.caption}' created successfully.")

src/antares/study/version/exceptions.py

@@ -0,0 +1,4 @@
+class ApplicationError(Exception):
+    """
+    Base class for all exceptions raised by the application.
+    """