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

ansys/saf/cli/_solutions/plugins.py

@@ -0,0 +1,254 @@
+# 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 collections.abc import Generator
+from importlib.metadata import entry_points
+from pathlib import Path
+import sys
+from typing import Any
+
+import click
+from packaging.specifiers import SpecifierSet
+from pydantic import BaseModel, ConfigDict, Field, ValidationError, field_validator, model_validator
+import tomlkit
+
+
+class SafTemplateValidationError:
+    def __init__(self, template_name: str, error: ValidationError):
+        self.template_name = template_name
+        self.error = error
+
+
+class SafTemplate(BaseModel):
+    name: str = Field(min_length=1)
+    type: str = Field(min_length=1)
+    description: str = Field(min_length=1)
+    location: Path
+    dependencies: dict[str, Any] = Field(default_factory=dict)
+    saf_cli_compatibility_range: SpecifierSet | None = None
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    @field_validator("location")
+    @classmethod
+    def validate_location(cls, v: Path) -> Path:
+        if not v.is_dir():
+            raise ValueError(f"Location path '{v}' is not a valid directory")
+        return v
+
+    @field_validator("saf_cli_compatibility_range", mode="before")
+    @classmethod
+    def validate_saf_cli_compatibility_range(cls, value: Any) -> SpecifierSet | None:
+        if value is None:
+            return None
+        try:
+            spec_str: str = str(value).strip()
+            return SpecifierSet(spec_str)
+        except Exception as e:
+            raise ValueError(
+                f"Invalid saf-cli version compatibility range: '{value}'. "
+                f"Make sure you define a range of versions using standard packaging specifier format, "
+                f"e.g. '>=0.1.0,<1.0.0' or '==0.2.5'.",
+            ) from e
+
+
+class SafPluginValidationError:
+    def __init__(self, module_name: str, error: ValidationError):
+        self.module_name = module_name
+        self.error = error
+
+
+class SafPlugin(BaseModel):
+    path: Path
+    module_name: str = Field(min_length=1)
+    templates_config: dict[str, Any] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def load_templates_config(self) -> "SafPlugin":
+        config_path = self.path / "templates.toml"
+        if not config_path.is_file():
+            raise ValueError(
+                f"Config file 'templates.toml' not found for plugin module '{self.module_name}' "
+                f"at expected location {config_path}",
+            )
+        try:
+            templates_config = tomlkit.loads(config_path.read_bytes()).unwrap()
+        except Exception as e:
+            raise ValueError(
+                f"Error loading config file 'templates.toml' for plugin module '{self.module_name}' "
+                f"at location {config_path}: {e}",
+            ) from e
+        if not templates_config.get("templates"):
+            raise ValueError(
+                f"No templates in templates configuration file for plugin module '{self.module_name}'",
+            )
+        self.templates_config = templates_config
+        return self
+
+
+class ClickRenderer:
+    def __init__(self, verbose: bool = False, steps_only: bool = False, solutions_only: bool = False):
+        self._verbose = verbose
+        self._steps_only = steps_only
+        self._solutions_only = solutions_only
+
+    def _render_plugin_information(self, module_name: str) -> None:
+        click_str = (
+            "Step templates" if self._steps_only else "Solution templates" if self._solutions_only else "Templates"
+        )
+        click.secho(f"{click_str} in ", fg="cyan", nl=False)
+        click.secho(f"{module_name}", fg="cyan", bold=True)
+
+    def _render_template_information(self, saf_template: SafTemplate) -> None:
+        click.secho(f"    {saf_template.name} ({saf_template.type}): ", fg="green", nl=False)
+        click.secho(f"{saf_template.description}")
+        if self._verbose:
+            click.secho(f"        location: {saf_template.location}")
+            if saf_template.dependencies:
+                for group_name in saf_template.dependencies:
+                    click.secho(f"        {group_name} dependencies:")
+                    for dependency_name, dependency_specification in saf_template.dependencies[group_name].items():
+                        click.secho(f"          - {dependency_name}: {dependency_specification}")
+        click.echo()
+
+    def render_plugin_and_template_information(self, plugin_templates: dict[str, list[SafTemplate]]) -> None:
+        for module_name, templates in plugin_templates.items():
+            self._render_plugin_information(module_name)
+            for template in templates:
+                if self._steps_only and template.type != "step" or self._solutions_only and template.type != "solution":
+                    continue
+                self._render_template_information(template)
+
+    def render_plugin_errors(self, plugin_errors: list[SafPluginValidationError]) -> None:
+        if self._verbose and plugin_errors:
+            for error in plugin_errors:
+                click.secho(f"Error in plugin module '{error.module_name}':", err=True, fg="red")
+                click.secho(f"{error.error}", err=True, fg="red")
+                click.echo()
+        elif plugin_errors:
+            click.secho(
+                f"Warning: {len(plugin_errors)} template plugin(s) could not be loaded. "
+                f"Use --verbose flag for more details.",
+                err=True,
+                fg="yellow",
+            )
+
+    def render_template_errors(self, template_errors: list[SafTemplateValidationError]) -> None:
+        if self._verbose and template_errors:
+            for error in template_errors:
+                click.secho(f"Error in template '{error.template_name}':", err=True, fg="red")
+                click.secho(f"{error.error}", err=True, fg="red")
+                click.echo()
+        elif template_errors:
+            click.secho(
+                f"Warning: {len(template_errors)} template(s) could not be loaded. "
+                f"Use --verbose flag for more details.",
+                err=True,
+                fg="yellow",
+            )
+
+
+def _iterate_plugins() -> Generator[SafPlugin | SafPluginValidationError, None, None]:
+    plugins = entry_points(group="ansys_saf_templates")
+    if not plugins:
+        click.secho("No template plugins found.", fg="yellow")
+        sys.exit(1)
+    for plugin in sorted(plugins, key=lambda p: p.value.split(":")[0]):
+        module_name = plugin.value.split(":")[0]
+        try:
+            yield SafPlugin.model_validate(
+                {
+                    "path": plugin.load()(),
+                    "module_name": module_name,
+                },
+            )
+        except ValidationError as e:
+            yield SafPluginValidationError(module_name, e)
+
+
+def _find_template_in_plugin(template_name: str, plugin: SafPlugin) -> SafTemplate | None:
+    if template_name not in plugin.templates_config["templates"]:
+        return None
+    template = plugin.templates_config["templates"][template_name]
+    try:
+        return SafTemplate.model_validate(
+            {
+                "name": template_name,
+                "type": template["type"],
+                "description": template["description"],
+                "location": plugin.path / template["location"],
+                "dependencies": template.get("dependencies", {}),
+                "saf_cli_compatibility_range": template.get("saf_cli_compatibility_range"),
+            },
+        )
+    except Exception as e:
+        raise ValueError(f"Template '{template_name}' in plugin module '{plugin.module_name}' is invalid.") from e
+
+
+def resolve_template(template_name: str) -> SafTemplate:
+    plugin_errors: list[SafPluginValidationError] = []
+    for plugin in _iterate_plugins():
+        if isinstance(plugin, SafPluginValidationError):
+            plugin_errors.append(plugin)
+            continue
+        if not (saf_template := _find_template_in_plugin(template_name, plugin)):
+            continue
+        return saf_template
+
+    raise ValueError(
+        f"Could not find a valid template for template name '{template_name}'.\n"
+        f" - Run `saf templates` to list the available templates.\n"
+        f" - Run `saf templates --verbose` to include more details on plugin and template errors.",
+    )
+
+
+def _scan_plugin_templates(plugin: SafPlugin) -> Generator[SafTemplate | SafTemplateValidationError, None, None]:
+    for template_name, template in plugin.templates_config["templates"].items():
+        try:
+            yield SafTemplate.model_validate(
+                {
+                    "name": template_name,
+                    "type": template.get("type", ""),
+                    "description": template.get("description"),
+                    "location": plugin.path / template.get("location", ""),
+                    "dependencies": template.get("dependencies", {}),
+                    "saf_cli_compatibility_range": template.get("saf_cli_compatibility_range"),
+                },
+            )
+        except ValidationError as e:
+            yield SafTemplateValidationError(template_name, e)
+
+
+def list_available_templates(steps_only: bool = False, solutions_only: bool = False, verbose: bool = False) -> None:
+    renderer = ClickRenderer(verbose, steps_only, solutions_only)
+    plugin_templates: dict[str, list[SafTemplate]] = {}
+    plugin_errors: list[SafPluginValidationError] = []
+    template_errors: list[SafTemplateValidationError] = []
+    for plugin in _iterate_plugins():
+        if isinstance(plugin, SafPluginValidationError):
+            plugin_errors.append(plugin)
+            continue
+        for saf_template in _scan_plugin_templates(plugin):
+            if isinstance(saf_template, SafTemplateValidationError):
+                template_errors.append(saf_template)
+                continue
+            if plugin.module_name not in plugin_templates:
+                plugin_templates[plugin.module_name] = []
+            plugin_templates[plugin.module_name].append(saf_template)
+
+    renderer.render_plugin_and_template_information(plugin_templates)
+    renderer.render_plugin_errors(plugin_errors)
+    renderer.render_template_errors(template_errors)

ansys/saf/cli/_solutions/scaffolding.py

@@ -0,0 +1,73 @@
+# 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 importlib.metadata
+from pathlib import Path
+import sys
+
+from cookiecutter.main import cookiecutter  # pyright: ignore[reportUnknownVariableType, reportMissingTypeStubs]
+
+from ansys.saf.cli._config.const import DEFAULT_SOLUTION_NAMESPACE, SOLUTION_TEMPLATE_PATH
+from ansys.saf.cli._utilities.conversion import (
+    namespace_to_path,
+    namespace_to_pkg_name,
+    to_class_name,
+    to_docker_name,
+    to_module_name,
+    to_package_name,
+)
+from ansys.saf.cli._utilities.platform import appdata_directory
+
+
+def create_solution(
+    solution_name: str,
+    solution_display_name: str,
+    ui_framework: str,
+    namespace: str = DEFAULT_SOLUTION_NAMESPACE,
+) -> None:
+    # see docs' glossary for a detailed explanation of every term used in the cookiecutter_kwargs
+    solution_module_name = to_module_name(solution_name)
+    solution_definition_class_name = to_class_name(solution_name, "Solution")
+    solution_package_name = to_package_name(solution_name)
+    version = "0.0.0"
+    docker_name = to_docker_name(solution_name, version)
+    saf_cli_version = importlib.metadata.version("ansys-saf-cli")
+
+    cookiecutter(
+        SOLUTION_TEMPLATE_PATH.as_posix(),
+        output_dir=Path.cwd().as_posix(),
+        no_input=True,
+        # overwrite all cookiecutter.json's terms
+        extra_context={
+            "__solution_name": solution_name,
+            "__solution_display_name": solution_display_name,
+            "__ui_framework": ui_framework,
+            "__solution_module_name": solution_module_name,
+            "__solution_definition_class_name": solution_definition_class_name,
+            "__solution_package_name": solution_package_name,
+            "__solution_namespace": namespace,
+            "__solution_namespace_path": namespace_to_path(namespace),
+            "__version": version,
+            "__docker_name": docker_name,
+            "__pkg_name": f"{namespace_to_pkg_name(namespace)}-{solution_package_name}",
+            "__pkg_namespace": f"{namespace}.{solution_module_name}",
+            "__pkg_path": f"{namespace_to_path(namespace)}/{solution_module_name}",
+            "__repository_url": "",
+            "__appdata_directory": appdata_directory(),
+            "__python_version": f"{sys.version_info.major}.{sys.version_info.minor}",
+            "__saf_cli_version": saf_cli_version,
+        },
+    )

ansys/saf/cli/_solutions/templates/__init__.py

@@ -0,0 +1,15 @@
+# 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.

ansys/saf/cli/_solutions/templates/solution/cookiecutter.json

@@ -0,0 +1,18 @@
+{
+  "__solution_name": "my_solution",
+  "__solution_display_name": "My Solution",
+  "__ui_framework": "dash",
+  "__solution_module_name": "my_solution",
+  "__solution_package_name": "my-solution",
+  "__solution_definition_class_name": "MySolution",
+  "__solution_namespace": "saf.solutions",
+  "__solution_namespace_path": "saf/solutions",
+  "__version": "0.0.0",
+  "__docker_name": "my-solution_0-0-0",
+  "__pkg_name": "saf-solutions-my-solution",
+  "__pkg_namespace": "saf.solutions.my_solution",
+  "__repository_url": "",
+  "__appdata_directory": "",
+  "__python_version": "3.10",
+  "__saf_cli_version": ""
+}

ansys/saf/cli/_solutions/templates/solution/hooks/post_gen_project.py

@@ -0,0 +1,54 @@
+# 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 os
+
+SOLUTION_UI_PATH = Path.cwd() / "src" / f"{{ cookiecutter.__solution_namespace_path }}" / f"{{ cookiecutter.__solution_module_name }}" / "ui"
+SOLUTION_UI_TESTS_PATH = Path.cwd() / "tests" / "unit" / "test_solution_ui.py"
+
+
+def _remove_ui_files() -> None:
+    if "{{ cookiecutter.__ui_framework }}" != "dash":  # pyright: ignore[reportUnnecessaryComparison]
+        shutil.rmtree(SOLUTION_UI_PATH)
+
+
+def _remove_ui_tests() -> None:
+    if "{{ cookiecutter.__ui_framework }}" != "dash":  # pyright: ignore[reportUnnecessaryComparison]
+        SOLUTION_UI_TESTS_PATH.unlink()
+
+
+def _copy_poetry_lock():
+    if "{{ cookiecutter.__ui_framework }}" == "dash":  # pyright: ignore[reportUnnecessaryComparison]
+        shutil.copy(os.path.join("lock_files", "dash", "poetry.lock"), ".")
+    else:
+        shutil.copy(os.path.join("lock_files", "no_ui", "poetry.lock"), ".")
+    shutil.rmtree("lock_files")
+
+
+def main():
+    _remove_ui_files()
+    _copy_poetry_lock()
+    _remove_ui_tests()
+
+
+if __name__ == "__main__":
+    main()

ansys/saf/cli/_solutions/templates/solution/{{cookiecutter.__solution_name}}/.codespell.ignore

@@ -0,0 +1,2 @@
+SME
+THIRDPARTY

ansys/saf/cli/_solutions/templates/solution/{{cookiecutter.__solution_name}}/.devcontainer/devcontainer.json

@@ -0,0 +1,26 @@
+{
+    "image": "mcr.microsoft.com/devcontainers/python:3.10",
+    "features": {
+    },
+    "onCreateCommand": "pip install packaging toml && python setup_environment.py -d all -f",
+    "postCreateCommand": "chmod +x /workspaces/{{ cookiecutter.__solution_name }}/.venv/bin/activate && sed -i '$a source /workspaces/{{ cookiecutter.__solution_name }}/.venv/bin/activate' ~/.bashrc && sed -i '$a source /workspaces/{{ cookiecutter.__solution_name }}/.venv/bin/activate' ~/.zshrc",
+    "postAttachCommand": "tox -e style",
+    "customizations": {
+      "vscode": {
+        "extensions": [
+          "davidanson.vscode-markdownlint",
+          "donjayamanne.python-environment-manager",
+          "donjayamanne.python-extension-pack",
+          "github.vscode-github-actions",
+          "github.vscode-pull-request-github",
+          "kevinrose.vsc-python-indent",
+          "mhutchie.git-graph",
+          "ms-python.debugpy",
+          "ms-python.python",
+          "ms-python.vscode-pylance",
+          "shd101wyy.markdown-preview-enhanced",
+          "vscode-icons-team.vscode-icons"
+        ]
+      }
+    }
+  }

ansys/saf/cli/_solutions/templates/solution/{{cookiecutter.__solution_name}}/.env

@@ -0,0 +1,5 @@
+DATABASE_LOCATION={{ cookiecutter.__appdata_directory }}/ansys/portal/{{ cookiecutter.__solution_name }}
+PORTAL_DATABASE_TYPE=sqlite
+PORTAL_PROJECT_DATABASE_LOCATION=${DATABASE_LOCATION}/projects.db
+GLOW_SOLUTION_DEFINITION={{ cookiecutter.__solution_namespace }}.{{ cookiecutter.__solution_module_name }}.solution.definition
+GLOW_UI_MODULE={{ cookiecutter.__solution_namespace }}.{{ cookiecutter.__solution_module_name }}.ui.app

ansys/saf/cli/_solutions/templates/solution/{{cookiecutter.__solution_name}}/.flake8

@@ -0,0 +1,8 @@
+[flake8]
+exclude = venv, __init__.py, doc/_build, .venv, tests/**
+select = W191, W291, W293, W391, E115, E117, E122, E124, E125, E225, E231, E301, E303, E501, F401, F403
+count = True
+max-complexity = 10
+max-line-length = 120
+statistics = True
+per-file-ignores = preprocessing.py:F401

ansys/saf/cli/_solutions/templates/solution/{{cookiecutter.__solution_name}}/.github/labeler.yml

@@ -0,0 +1,9 @@
+documentation:
+  - changed-files:
+      - any-glob-to-any-file: ['doc/source/**/*']
+maintenance:
+  - changed-files:
+      - any-glob-to-any-file: ['.github/**/*', '.flake8', 'pyproject.toml']
+dependencies:
+  - changed-files:
+      - any-glob-to-any-file: ['pyproject.toml']

ansys/saf/cli/_solutions/templates/solution/{{cookiecutter.__solution_name}}/.github/labels.yml

@@ -0,0 +1,27 @@
+- name: bug
+  description: Something isn't working
+  color: d42a34
+
+- name: dependencies
+  description: Related with project dependencies
+  color: ffc0cb
+
+- name: documentation
+  description: Improvements or additions to documentation
+  color: 0677ba
+
+- name: enhancement
+  description: New features or code improvements
+  color: FFD827
+
+- name: good first issue
+  description: Easy to solve for newcomers
+  color: 62ca50
+
+- name: maintenance
+  description: Package and maintenance related
+  color: f78c37
+
+- name: release
+  description: Anything related to an incoming release
+  color: ffffff