ansys-saf-cli 4.1.dev0__py3-none-any.whl

ansys/saf/cli/_utilities/backup.py

@@ -0,0 +1,181 @@
+# Copyright (C) 2026 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+#
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from pathlib import Path
+import shutil
+import tempfile
+
+import click
+
+from ansys.saf.cli._utilities.conversion import namespace_to_path
+
+
+class BackupManager:
+    """
+    Handles snapshot, backup, restore and cleanup operations for a solution add-step workflow.
+    Implements context manager protocol for automatic rollback on exceptions.
+
+    When used as a context manager, ``__enter__`` snapshots the solution module directory
+    and backs up all provided files upfront (non-existent files are silently skipped).
+    On exception, ``__exit__`` removes newly created files and restores all backed-up files;
+    the backup directory is always removed on exit.
+
+    Attributes:
+        solution_root_dir: The root directory of the solution.
+        solution_package_name: The name of the solution package module.
+        files_to_backup: List of (file_path, base_dir) tuples to back up.
+    """
+
+    def __init__(
+        self,
+        solution_root_dir: Path,
+        solution_package_name: str,
+        namespace_root: str,
+        files_to_backup: list[tuple[Path, Path]] | None = None,
+    ):
+        """Initialize BackupManager.
+
+        Args:
+            solution_root_dir: Root directory of the solution.
+            solution_package_name: Name of the solution package (used to compute base_solution_dir).
+            namespace_root: Root namespace of the solution.
+            files_to_backup: List of (file_path, base_dir) tuples to back up. If None, uses default files
+                           (page.py, definition.py, pyproject.toml, poetry.lock).
+        """
+        self._solution_root_dir = solution_root_dir
+        # Compute base_solution_dir from solution_root_dir and solution_package_name
+        self._base_solution_dir = solution_root_dir / "src" / namespace_to_path(namespace_root) / solution_package_name
+
+        # If files_to_backup is not provided, use default files
+        if files_to_backup is None:
+            files_to_backup = [
+                # even if some of these files are not modified explicitly by the saf-cli,
+                # they can be modified by the post-gen hooks in the step templates themselves
+                (self._base_solution_dir / "ui" / "pages" / "page.py", self._base_solution_dir),
+                (self._base_solution_dir / "solution" / "definition.py", self._base_solution_dir),
+                (solution_root_dir / "pyproject.toml", solution_root_dir),
+                (solution_root_dir / "poetry.lock", solution_root_dir),
+            ]
+
+        self._files_to_backup = files_to_backup
+        self._backup_dir = Path(tempfile.mkdtemp())
+        self._preexisting_paths: set[str] = set()
+        self._backup_mapping: dict[Path, Path] = {}
+        self._missing_files_to_remove_on_restore: set[Path] = set()
+        self._snapshot_taken = False
+
+    def _snapshot_directory_paths(self) -> set[str]:
+        """Return relative paths of all files and directories under the solution module directory."""
+        if not self._base_solution_dir.exists():
+            return set()
+        return {str(p.relative_to(self._base_solution_dir)) for p in self._base_solution_dir.rglob("*")}
+
+    def _rollback_newly_created_files_and_empty_dirs(self) -> None:
+        """Remove newly created files and empty directories."""
+        if not self._snapshot_taken:
+            raise RuntimeError("Cannot rollback before taking a snapshot.")
+
+        post_paths = self._snapshot_directory_paths()
+        created_paths = post_paths - self._preexisting_paths
+
+        for rel in sorted(created_paths, reverse=True):
+            target = self._base_solution_dir / rel
+            try:
+                if target.is_file() or target.is_symlink():
+                    target.unlink()
+                elif target.is_dir() and not any(target.iterdir()):
+                    target.rmdir()
+            except OSError as e:
+                click.secho(
+                    f"Warning: Failed cleanup: {target} ({e})",
+                    fg="yellow",
+                )
+
+        for target in sorted(self._missing_files_to_remove_on_restore, reverse=True):
+            if not target.exists():
+                continue
+
+            try:
+                if target.is_file() or target.is_symlink():
+                    target.unlink()
+            except OSError as e:
+                click.secho(
+                    f"Warning: Failed cleanup: {target} ({e})",
+                    fg="yellow",
+                )
+
+    def _backup_files(self) -> None:
+        """Backup files preserving relative structure."""
+        for src in (file for file, _ in self._files_to_backup):
+            if not src.is_file():
+                continue
+
+            # Find the base_dir for this file from _files_to_backup
+            base_dir = next((bd for f, bd in self._files_to_backup if f == src), self._base_solution_dir)
+            relative_path = src.relative_to(base_dir) if src.is_relative_to(base_dir) else Path(src.name)
+            backup_file = self._backup_dir / relative_path
+
+            try:
+                backup_file.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(src, backup_file)
+                self._backup_mapping[src] = backup_file
+            except OSError as e:
+                click.secho(
+                    f"Warning: Failed to backup '{src}' -> '{backup_file}' ({e})",
+                    fg="yellow",
+                )
+
+    def _restore_files(self) -> None:
+        """Restore files from backup."""
+        for original, backup in self._backup_mapping.items():
+            try:
+                original.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(backup, original)
+            except OSError as e:
+                click.secho(
+                    f"Restore failed: {original} ({e})",
+                    fg="yellow",
+                )
+
+    def __enter__(self) -> "BackupManager":
+        """Enter context manager.
+
+        Snapshots ``base_solution_dir`` and backs up every file supplied via ``files_to_backup``.
+        Files that do not yet exist (e.g. an optional ``poetry.lock``) are silently skipped.
+        """
+        # Take snapshot of the solution module directory
+        self._preexisting_paths = self._snapshot_directory_paths()
+        self._missing_files_to_remove_on_restore = {
+            file_path for file_path, _ in self._files_to_backup if not file_path.exists()
+        }
+        self._snapshot_taken = True
+
+        # Back up specified files
+        self._backup_files()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb) -> bool:  # type: ignore
+        """Exit context manager: restore state if exception occurred, always cleanup."""
+        try:
+            if exc_type is not None:
+                # Remove newly created files and empty directories
+                self._rollback_newly_created_files_and_empty_dirs()
+                # Restore all backed-up files
+                self._restore_files()
+        finally:
+            # Always cleanup backup directory
+            shutil.rmtree(self._backup_dir, ignore_errors=True)
+        return False

ansys/saf/cli/_utilities/conversion.py

@@ -0,0 +1,64 @@
+# Copyright (C) 2026 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+#
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+def to_display_name(name: str) -> str:
+    # input: "my-name" or "my_name" or "my name" or "My name"
+    # output: "My Name"
+    return name.replace("-", " ").replace("_", " ").title()
+
+
+def to_module_name(name: str, module_type: str = "") -> str:
+    # input: "my-name" or "my_name" or "my name" or "My name"
+    # output: "my_name{_module-type}" (module_type: _step or _page)
+    module_name = name.lower().replace("-", "_").replace(" ", "_")
+    if module_type and not module_name.endswith(module_type):
+        module_name += f"_{module_type}"
+    return module_name
+
+
+def to_class_name(name: str, class_type: str) -> str:
+    # input: "my-name" or "my_name" or "my name" or "My name"
+    # output: "MyName{ClassType}" (class_type: Solution or Step)
+    class_name = name.title().replace("-", "").replace("_", "").replace(" ", "")
+    if not class_name.endswith(class_type):
+        class_name += class_type
+    return class_name
+
+
+def to_package_name(name: str) -> str:
+    # input: "my-name" or "my_name" or "my name" or "My name"
+    # output: "my-name"
+    return name.lower().replace("_", "-").replace(" ", "-")
+
+
+def namespace_to_pkg_name(namespace: str) -> str:
+    # input:  "my_org.my_project"
+    # output: "my-org-my-project"
+    namespace_parts = [to_package_name(part) for part in namespace.split(".")]
+    return "-".join(namespace_parts)
+
+
+def to_docker_name(name: str, version: str) -> str:
+    # input: "my-name" or "my_name" or "my name" or "My name" and version = "0.1.dev0"
+    # output: "my-name-0-1-dev0"
+    return f"{to_package_name(name)}_{version.replace('.', '-')}"
+
+
+def namespace_to_path(namespace: str) -> str:
+    # input:  "my_org.my_project"
+    # output: "my_org/my_project"
+    return namespace.replace(".", "/")

ansys/saf/cli/_utilities/platform.py

@@ -0,0 +1,26 @@
+# Copyright (C) 2026 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+#
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+from pathlib import Path
+import platform
+
+
+def appdata_directory() -> str:
+    if platform.system() == "Windows":
+        return Path(os.environ["APPDATA"]).as_posix()
+    else:
+        return str(Path(os.getenv("XDG_DATA_HOME", "~/.local/share")).expanduser())

ansys/saf/cli/_utilities/solution_modules.py

@@ -0,0 +1,173 @@
+# Copyright (C) 2026 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+#
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import ast
+import os
+from pathlib import Path
+import platform
+
+from ansys.saf.cli._database.manager import SolutionDatabaseManager
+
+
+def find_solution_root_dir(db_manager: SolutionDatabaseManager, solution: str) -> Path:
+    """Find the source directory of the solution given a str that can be:
+    - the name of a valid registered solution
+    - the path to a solution directory
+    - empty string, thus pointing to the current working directory.
+    """
+    if not solution:
+        solution_root_dir = Path.cwd()
+    registered_solutions = db_manager.get_solutions_by_name(solution)
+    if not registered_solutions:
+        solution_root_dir = Path(solution).expanduser().resolve()
+        if not solution_root_dir.is_dir():
+            raise NotADirectoryError(f"Solution not found at {solution_root_dir}")
+    elif len(registered_solutions) > 1:
+        error_message = f"Multiple solutions found with the name {solution}."
+        for registered_solution in registered_solutions:
+            error_message += f"\n- Found {registered_solution.name} at {registered_solution.root_dir}"
+        error_message += (
+            "\nHint: You can specify the correct one by using the full path to the solution as follows:\n"
+            "saf <command> /full/path/to/your-solution/"
+        )
+        raise ValueError(error_message)
+    else:
+        solution_root_dir = registered_solutions[0].root_dir
+
+    return solution_root_dir
+
+
+def resolve_solution_main_file(solution_root_dir: Path) -> Path:
+    """Find the main file of the solution given the solution directory.
+
+    Searches for a main.py file under src/ at any namespace depth.
+    If not found, falls back to searching for main.pyc.
+    Expected structure: src/<namespace_path>/<solution_name>/main.py
+    """
+    solution_src_dir = solution_root_dir / "src"
+    if not solution_src_dir.is_dir():
+        raise NotADirectoryError(f"Solution source directory not found at {solution_src_dir}")
+
+    main_files = sorted(solution_src_dir.glob("**/main.py"))
+    if not main_files:
+        main_files = sorted(solution_src_dir.glob("**/main.pyc"))
+
+    if not main_files:
+        raise FileNotFoundError(
+            f"Solution main file not found under {solution_src_dir}. "
+            f"Expected structure: src/<namespace_path>/<solution_name>/main.py",
+        )
+    if len(main_files) > 1:
+        error_message = "Multiple main files found:\n"
+        for main_file in main_files:
+            error_message += f"- Found {main_file}\n"
+        error_message += "Only one solution is expected in the src directory."
+        raise ValueError(error_message)
+
+    return main_files[0]
+
+
+def _get_solution_module_parts(solution_main_file: Path) -> list[str]:
+    """Return the dotted-module path parts after the src directory."""
+    resolved_path = solution_main_file.resolve()
+
+    try:
+        src_index = resolved_path.parts.index("src")
+    except ValueError:
+        raise RuntimeError(f"Could not find 'src' in path: {resolved_path}") from None
+
+    module_parts = list(resolved_path.parts[src_index + 1 :])
+    if not module_parts:
+        raise RuntimeError(f"Could not build module path from: {resolved_path}")
+
+    module_parts[-1] = Path(module_parts[-1]).stem
+    return module_parts
+
+
+def get_main_module(solution_main_file: Path) -> str:
+    """Get the main module for a Solution and, optionally, validate that it is correct. Raises an exception
+    if a Solution main module is not found.
+
+    Parameters
+    ----------
+    solution_main_file : Path
+        The path of the Solution main file (e.g., <org>/solutions/<solution_name>/main.py).
+
+    Returns
+    -------
+        str
+            The main module str (e.g., my_company.solutions.my_solution.main)
+    """
+    return ".".join(_get_solution_module_parts(solution_main_file))
+
+
+def find_solution_display_name(solution_main_file: Path) -> str | None:
+    # we cannot import the solution, since the CLI env doesn't have the solution dependencies
+    # We fallback then to parsing the definition.py file, which doesn't work for compiled solutions
+    # shouldn't be an issue since src directories are not typically compiled.
+    definition_file = solution_main_file.parent / "solution" / "definition.py"
+    if not definition_file.is_file():
+        return None
+
+    display_name: str | None = None
+    tree = ast.parse(definition_file.read_text())
+    class_definitions = [node for node in tree.body if isinstance(node, ast.ClassDef)]
+    for class_def in class_definitions:
+        if any(base.id == "Solution" for base in class_def.bases):  # pyright: ignore
+            assignments = [node for node in class_def.body if isinstance(node, ast.AnnAssign)]
+            for assignment in assignments:
+                if assignment.target.id == "display_name":  # pyright: ignore
+                    display_name = str(assignment.value.value)  # pyright: ignore
+                    break
+            break
+    return display_name
+
+
+def get_solution_venv_bin_dir(solution_root_dir: Path) -> Path:
+    if platform.system() == "Windows":
+        solution_venv_bin_dir = solution_root_dir / ".venv" / "Scripts"
+    elif platform.system() == "Linux":
+        solution_venv_bin_dir = solution_root_dir / ".venv" / "bin"
+    else:
+        raise ValueError("Unsupported operating system")
+    return solution_venv_bin_dir
+
+
+def get_exec_from_solution_venv(solution_root_dir: Path, exec_name: str) -> Path:
+    solution_venv_bin_dir = get_solution_venv_bin_dir(solution_root_dir)
+    if platform.system() == "Windows":
+        exec_path = solution_venv_bin_dir / f"{exec_name}.exe"
+    elif platform.system() == "Linux":
+        exec_path = solution_venv_bin_dir / exec_name
+    else:
+        raise ValueError("Unsupported operating system")
+    if not exec_path.is_file():
+        raise FileNotFoundError(f"Executable not found at {exec_path}")
+    return exec_path
+
+
+def create_solution_environment(solution_root_dir: Path) -> dict[str, str]:
+    solution_env = os.environ.copy()
+    # Poetry will always pick the active python environment (the environment in variable VIRTUAL_ENV) when managing
+    # dependencies. Removing this environment variable lets poetry use the solution's environment.
+    solution_env.pop("VIRTUAL_ENV", None)
+    # so internal calls to tools (e.g., poetry and sphinx in installer) resolve first to the binaries in the
+    # solution's venv instead of the ones in the SAF-CLI's venv or global ones. This doesn't seem to work with others
+    # such as python/pip. See _get_executable_absolute_path.
+    solution_env["PATH"] = os.pathsep.join(
+        [str(get_solution_venv_bin_dir(solution_root_dir)), solution_env.get("PATH", "")],
+    )
+    return solution_env

ansys/saf/cli/integrations/solutions_manager.py

@@ -0,0 +1,64 @@
+# Copyright (C) 2026 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: Apache-2.0
+#
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+import sys
+
+import click
+
+from ansys.saf.cli._solutions.environment import (
+    set_user_level_environment_variable,
+    validate_credentials,
+)
+
+
+@click.group()
+def main():
+    """Solutions Manager Integration CLI"""
+
+
+@main.command("validate-credentials")
+@click.option("--source", required=True, help="Source configuration as JSON")
+@click.option("--username", required=True, help="The username for authentication")
+@click.option("--password", required=True, help="The password for authentication")
+def validate_credentials_cmd(source: str, username: str, password: str):
+    """Validate credentials by testing PyPI access"""
+    try:
+        source_data = json.loads(source)
+        is_valid = validate_credentials(source_data, username, password)
+        click.echo("Credentials are valid!" if is_valid else "Invalid credentials.")
+        sys.exit(0)
+    except Exception as e:
+        click.echo(f"Error: {e}")
+        sys.exit(1)
+
+
+@main.command("set-env-var")
+@click.option("--key", required=True, help="The name of the environment variable")
+@click.option("--value", required=True, help="The value to set for the environment variable")
+def set_env_var_cmd(key: str, value: str):
+    """Set a user-level environment variable"""
+    try:
+        set_user_level_environment_variable(key, value)
+        click.echo(f"Environment variable '{key}' set successfully!")
+        sys.exit(0)
+    except Exception as e:
+        click.echo(f"Error: {e}")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()