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

ansys/saf/cli/_solutions/templates/solution/{{cookiecutter.__solution_name}}/src/{{ cookiecutter.__solution_namespace_path }}/{{cookiecutter.__solution_module_name}}/ui/pages/page.py

@@ -0,0 +1,367 @@
+# Copyright (C) 2023 - 2026 ANSYS, Inc. and/or its affiliates.
+
+"""Initialization of the frontend layout across all the steps."""
+
+
+import importlib
+import inspect
+import logging
+from pathlib import Path
+from typing import Any, Literal
+import webbrowser
+
+from ansys.saf.glow.client import DashClient, Deployment, NotFoundException, callback
+from ansys.solutions.dash_super_components import Tree
+import dash
+import dash_bootstrap_components as dbc
+from dash_extensions.enrich import Input, Output, State, clientside_callback, dcc, html, no_update
+import dash_mantine_components as dmc
+
+from {{ cookiecutter.__solution_namespace }}.{{ cookiecutter.__solution_module_name }}.solution.definition import {{ cookiecutter.__solution_definition_class_name }}
+
+logger = logging.getLogger(__name__)
+
+
+def get_asset(asset_name: str, relative_path: str = "", theme: str = "dark") -> str:
+    """Return asset URL based on the current theme."""
+    path = f"{relative_path.strip('/')}/{theme}/{asset_name}"
+    return dash.get_asset_url(path)
+
+
+def get_page_list(theme: str) -> list[dict[str, str | bool]]:
+    """Return the page list with icons based on the current theme and registered pages."""
+    pages = []
+    for i, page in enumerate(dash.page_registry.values()):
+        if page["module"].split(".")[-1] == "not_found_404":
+            continue
+        page_id = str(i)
+        page_name = page["name"]
+        icon_name = page.get("icon_asset_name", "carbon--ibm-engineering-workflow-mgmt.svg")
+        icon_path = page.get("icon_asset_path", "icons")
+        icon_url = get_asset(icon_name, icon_path, theme)
+        pages.append({"id": page_id, "text": page_name, "icon": icon_url, "expanded": True})
+    return pages
+
+
+theme_toggle = dmc.Switch(
+    offLabel=html.Img(src=get_asset("radix-icons--sun.svg", "icons", "light")),
+    onLabel=html.Img(src=get_asset("radix-icons--moon.svg", "icons", "light")),
+    id="color-scheme-switch",
+    persistence=True,
+    color="grey",
+    checked=False,
+)
+
+
+header = dmc.AppShellHeader(
+    dmc.Flex(
+        [
+            html.Img(id="logo-image", src=get_asset("placeholder_logo.png", "logos", "light"), height="36px"),
+            dmc.Group(
+                [
+                    dmc.Text(
+                        "Project name:",
+                        id="project-name",
+                        size="sm",
+                        style={"font-size": "16px", "color": "var(--mantine-color-text)"},
+                    ),
+                    theme_toggle,
+                    dmc.ActionIcon(
+                        html.Img(src=get_asset("teenyicons--doc-solid.svg", "icons", "light")),
+                        id="access-solution-doc",
+                        variant="transparent",
+                        style={"color": "var(--mantine-color-text)"},
+                    ),
+                    dbc.Popover(
+                        "Get access to the Solution's Documentation.",
+                        target="access-solution-doc",
+                        body=True,
+                        trigger="hover",
+                    ),
+                    html.Div(id="return-to-portal"),
+                ],
+                gap=10,
+            ),
+        ],
+        justify="space-between",
+        align="center",
+        direction="row",
+        wrap="wrap",
+        h="100%",
+        px="md",
+    )
+)
+
+
+navbar = dmc.AppShellNavbar(
+    html.Div(),
+    id="navbar-content",
+    p="md",
+)
+
+
+main_layout = dmc.AppShellMain(
+    html.Div(
+        id="page-content",
+        style={
+            "padding-right": "0.7%",
+            "padding-left": "0.7%",
+            "backgroundColor": "var(--mantine-color-body)",
+            "color": "var(--mantine-color-text)",
+            "minHeight": "100vh",
+        },
+    )
+)
+
+
+layout = dmc.MantineProvider(
+    [
+        dmc.NotificationContainer(
+            id="notification-container",
+            position="bottom-left",
+            notificationMaxHeight=400,
+        ),
+        dmc.AppShell(
+            [
+                header,
+                navbar,
+                main_layout,
+            ],
+            header={"height": 70},
+            navbar={
+                "width": 300,
+                "breakpoint": "sm",
+                "collapsed": {"mobile": True},
+            },
+        ),
+        dcc.Location(id="url", refresh="callback-nav"),
+        html.Div(
+            id="alerts-container", style={"position": "fixed", "top": 90, "right": 10, "width": 350, "zIndex": 1000}
+        ),
+        dcc.Store(id="active-page-index", data=None),
+        dcc.Store(id="active-project-id", data=None),
+    ],
+    id="mantine-provider",
+    defaultColorScheme="light",
+)
+
+
+def _get_alert_toast(message: str, level: Literal["success", "info", "warning", "danger"]) -> dbc.Toast:
+    """Create a toast with the alert message."""
+    content = html.Div([message], style={"font-size": "small"})
+    toast = dbc.Toast(
+        content,
+        header=level.upper(),
+        is_open=True,
+        dismissable=True,
+        icon=level,
+        color=level,
+        duration=20000,
+    )
+
+    return toast
+
+
+@callback(
+    Output("return-to-portal", "children"),
+    Input("url", "pathname"),
+    Input("color-scheme-switch", "checked"),
+)
+def return_to_portal(pathname: str, switch_on: bool) -> list[html.A]:
+    """Display Solution Portal when back-to-portal button gets selected."""
+    theme = "dark" if switch_on else "light"
+
+    portal_ui_url = DashClient.get_portal_ui_url()
+
+    if portal_ui_url is None:
+        return []
+
+    popover_text = "Back to Projects" if DashClient.get_deployment_type() == Deployment.Desktop else "Back to Portal"
+
+    return [
+        html.A(
+            [
+                dmc.ActionIcon(
+                    html.Img(src=get_asset("carbon--return.svg", "icons", theme)),
+                    id="back-to-projects-icon",
+                    variant="transparent",
+                ),
+                dbc.Popover(
+                    popover_text,
+                    target="back-to-projects-icon",
+                    body=True,
+                    trigger="hover",
+                ),
+            ],
+            href=portal_ui_url,
+        )
+    ]
+
+
+@callback(
+    Output("project-name", "children"),
+    Input("url", "pathname"),
+)
+def display_project_name(project: {{ cookiecutter.__solution_definition_class_name }}) -> str:
+    """Display current project name."""
+    return f"Project Name: {project.project_display_name}"
+
+
+@callback(
+    Output("alerts-container", "children"),
+    Input("access-solution-doc", "n_clicks"),
+    prevent_initial_call=True,
+)
+def access_solution_documentation(n_clicks: int) -> list[dbc.Toast] | None:
+    """Open the Solution's Documentation home page in the web browser."""
+    solution_module = importlib.import_module("{{ cookiecutter.__solution_namespace }}.{{ cookiecutter.__solution_module_name }}")
+    doc_index_path = Path(solution_module.__path__[0]) / "html-doc" / "index.html"
+    if not doc_index_path.is_file():
+        doc_index_path = Path.cwd() / "doc" / "build" / "html" / "index.html"
+    if not doc_index_path.is_file():
+        return _get_alert_toast("Solution documentation is not available.", "warning")
+    logger.info(f"Opening documentation at {doc_index_path}")
+    webbrowser.open_new(doc_index_path.as_posix())
+    return no_update
+
+
+@callback(
+    Output("active-page-index", "data"),
+    Output("active-project-id", "data"),
+    Input("url", "pathname"),
+)
+def resolve_active_page_and_project_information(pathname: str) -> tuple[str | None, str | None]:
+    """Resolve the active page index and project ID based on the current URL."""
+    path_parts = pathname.strip("/").split("/")
+    for i, page in enumerate(dash.page_registry.values()):
+        if page["module"].split(".")[-1] == "not_found_404":
+            continue
+        template_parts = page["path_template"].strip("/").split("/")
+        # look for same parts, excluding <project_id> variable
+        if len(path_parts) != len(template_parts):
+            continue
+        project_id = None
+        matched = True
+        for tp, pp in zip(template_parts, path_parts, strict=True):
+            if tp == "<project_id>":
+                project_id = pp
+            elif tp != pp:
+                matched = False
+                break
+        if matched:
+            return str(i), project_id
+    return None, None
+
+
+@callback(
+    Output("navbar-content", "children"),
+    Input("active-page-index", "data"),
+    Input("color-scheme-switch", "checked"),
+    prevent_initial_call=True,
+)
+def render_nav_tree(active_index: str | None, switch_on: bool):
+    """Sync the active tree item based on the active page index."""
+    theme = "dark" if switch_on else "light"
+    return Tree(aio_id="navigation_tree", items=get_page_list(theme), active_item_id=active_index)
+
+
+def _display_404_page() -> Any:
+    for module, page in dash.page_registry.items():
+        if module.split(".")[-1] == "not_found_404":
+            return page["layout"]
+    return html.H1("404 - Page not found")
+
+
+@callback(
+    Output("page-content", "children"),
+    Input("url", "pathname"),
+    Input("active-page-index", "data"),
+    prevent_initial_call=True,
+)
+def display_page(project: {{ cookiecutter.__solution_definition_class_name }}, active_page_index: str | None):
+    """Return the page layout, passing the project instance.
+
+    Using dash.page_container does not allow to inject the project instance as argument to the layout function,
+    only supports passing path variables, query parameters or other Inputs/States.
+    """
+    if active_page_index is None:
+        # triggered if pathname with correct project information but incorrect sub-path.
+        # anyway, the 404 page will be rendered by another callback
+        return no_update
+    try:
+        # verify that the project information is valid, otherwise return 404.
+        # Cannot be done in display_404_page callback because we need that one to succeed if project injection fails.
+        _ = project.project_display_name
+    except NotFoundException:
+        return _display_404_page()
+
+    pages = list(dash.page_registry.values())  # page_registry is an ordered dict
+    index = int(active_page_index)
+    page = pages[index]
+    # support layout module attribute and layout function (with or without project argument)
+    layout_func = page["layout"]
+    if callable(layout_func):
+        params = inspect.signature(layout_func).parameters
+        if "project" in params:
+            return layout_func(project=project)
+        return layout_func()
+    return layout_func
+
+
+@callback(
+    Output("page-content", "children"),
+    Input("active-page-index", "data"),
+    prevent_initial_call=True,
+)
+def display_404_page(active_page_index: str | None):
+    """Return the 404 page layout when the active page index is None."""
+    if active_page_index is None:
+        return _display_404_page()
+    return no_update
+
+
+@callback(
+    Output("url", "href"),
+    Input(Tree.ids.selected_item("navigation_tree"), "data"),
+    State("active-project-id", "data"),
+    State("url", "pathname"),
+    prevent_initial_call=True,
+)
+def open_new_page(value, project_id: str | None, pathname: str):
+    """Navigate to the selected page."""
+    if project_id is None or not value:
+        return no_update
+    item_index = int(Tree.ids.get_index_from_navlink_item_id(value))
+    pages = list(dash.page_registry.values())
+    if item_index >= len(pages):
+        return no_update
+    page = pages[item_index]
+    target_path = page["path_template"].replace("<project_id>", project_id)
+    if target_path == pathname:
+        return no_update
+    return target_path
+
+
+@callback(
+    Output("access-solution-doc", "children"),
+    Output("logo-image", "src"),
+    Input("color-scheme-switch", "checked"),
+)
+def update_nav_icons(switch_on: bool) -> tuple[html.Img, str]:
+    """Update navigation tree icons based on the current theme."""
+    theme = "dark" if switch_on else "light"
+    return (
+        html.Img(src=get_asset("teenyicons--doc-solid.svg", "icons", theme)),
+        get_asset("placeholder_logo.png", "logos", theme),
+    )
+
+
+clientside_callback(
+    """
+    (switchOn) => {
+        return switchOn ? 'dark' : 'light';
+    }
+    """,
+    Output("mantine-provider", "forceColorScheme"),
+    Input("color-scheme-switch", "checked"),
+)

ansys/saf/cli/_solutions/templates/solution/{{cookiecutter.__solution_name}}/src/{{ cookiecutter.__solution_namespace_path }}/{{cookiecutter.__solution_module_name}}/ui/pages/second_page.py

@@ -0,0 +1,32 @@
+# Copyright (C) 2023 - 2026 ANSYS, Inc. and/or its affiliates.
+
+"""Frontend of the second step."""
+
+
+import dash
+from dash_extensions.enrich import html
+
+from {{ cookiecutter.__solution_namespace }}.{{ cookiecutter.__solution_module_name }}.solution.definition import {{cookiecutter.__solution_definition_class_name}}
+
+dash.register_page(
+    __name__,
+    name="Second Step",
+    path_template="/projects/<project_id>/second-step",
+    icon_asset_name="carbon--ibm-engineering-workflow-mgmt.svg",
+    icon_asset_path="icons",
+)
+
+
+def layout(project: {{cookiecutter.__solution_definition_class_name}}):
+    """Layout of the second step page."""
+    return html.Div(
+        [
+            html.H1("Second Step", className="display-3", style={"font-size": "48px", "fontWeight": "bold"}),
+            html.P(
+                "This page is empty for now.",
+                className="lead",
+                style={"font-size": "20px"},
+            ),
+            html.Br(),
+        ]
+    )

ansys/saf/cli/_solutions/templates/solution/{{cookiecutter.__solution_name}}/tests/common_test_files/README.md

@@ -0,0 +1 @@
+# Common test files

ansys/saf/cli/_solutions/templates/solution/{{cookiecutter.__solution_name}}/tests/conftest.py

@@ -0,0 +1,37 @@
+# Copyright (C) 2023 - 2026 ANSYS, Inc. and/or its affiliates.
+
+# ==================================================== [Imports] ==================================================== #
+
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+# =================================================== [Variables] =================================================== #
+
+# Get absolute path to tests directory
+tests_directory = Path(__file__).parent.absolute()
+
+# Get absolute path to project directory
+project_directory = Path(__file__).parent.parent.absolute()
+
+# =================================================== [Functions] =================================================== #
+
+
+def _set_default_glow_env(project_directory: Path) -> None:
+    env_file = project_directory / ".env"
+    if env_file.is_file():
+        load_dotenv(env_file, override=False)
+
+    os.environ.setdefault(
+        "GLOW_SOLUTION_DEFINITION",
+        "{{cookiecutter.__solution_namespace}}.{{cookiecutter.__solution_module_name}}.solution.definition",
+    )
+    os.environ.setdefault(
+        "GLOW_UI_MODULE",
+        "{{cookiecutter.__solution_namespace}}.{{cookiecutter.__solution_module_name}}.ui.app",
+    )
+
+
+def pytest_configure(config) -> None:
+    _set_default_glow_env(project_directory)

ansys/saf/cli/_solutions/templates/solution/{{cookiecutter.__solution_name}}/tests/unit/test_solution_api.py

@@ -0,0 +1,42 @@
+# Copyright (C) 2023 - 2026 ANSYS, Inc. and/or its affiliates.
+
+from {{ cookiecutter.__solution_namespace }}.{{ cookiecutter.__solution_module_name }}.solution.definition import {{ cookiecutter.__solution_definition_class_name }}
+
+
+def test_set_and_retrieve_basic_step_fields(client_project: {{ cookiecutter.__solution_definition_class_name }}):
+    first_step = client_project.steps.first_step
+    # retrieve step field
+    assert first_step.first_arg == 0
+    # set step field
+    first_step.first_arg = 1.0
+    # retrieve updated value
+    assert first_step.first_arg == 1.0
+    # set multiple fields
+    first_step.set_fields({"first_arg": 2.0, "second_arg": 3.0})
+    # retrieve updated values
+    assert first_step.first_arg == 2.0
+    assert first_step.second_arg == 3.0
+
+
+def test_calculate(client_project: {{ cookiecutter.__solution_definition_class_name }}):
+    first_step = client_project.steps.first_step
+    first_step.first_arg = 10.0
+    first_step.second_arg = 20.0
+    first_step.calculate()
+    assert first_step.result == 30.0
+
+
+def test_save_result(client_project: {{ cookiecutter.__solution_definition_class_name }}):
+    first_step = client_project.steps.first_step
+    first_step.result = 7.0
+    first_step.save_result()
+    assert client_project.storage_scope.get_text(first_step.result_file) == "7.0"
+
+
+def test_load_result(client_project: {{ cookiecutter.__solution_definition_class_name }}):
+    result_file = client_project.storage_scope.get_storage_root() / "result_file.txt"
+    result_file.write_text("29.5")
+    first_step = client_project.steps.first_step
+    first_step.result_file = client_project.storage_scope.store(result_file)
+    result = first_step.load_result()
+    assert result == 29.5

ansys/saf/cli/_solutions/templates/solution/{{cookiecutter.__solution_name}}/tests/unit/test_solution_ui.py

@@ -0,0 +1,30 @@
+# Copyright (C) 2023 - 2026 ANSYS, Inc. and/or its affiliates.
+
+from dash.testing import ignore_register_page
+import pytest
+
+from {{ cookiecutter.__solution_namespace }}.{{ cookiecutter.__solution_module_name }}.solution.definition import {{ cookiecutter.__solution_definition_class_name }}
+
+with ignore_register_page():
+    from {{ cookiecutter.__solution_namespace }}.{{ cookiecutter.__solution_module_name }}.ui.pages.first_page import calculate, load_result, save_result
+
+pytestmark = [pytest.mark.usefixtures("init_dashclient")]
+
+
+def test_calculate_callback(project_name: str):
+    assert calculate(1, 1, 2, project_name) == (3.0, True)
+
+
+def test_save_result_callback(client_project: {{ cookiecutter.__solution_definition_class_name }}, project_name: str):
+    first_step = client_project.steps.first_step
+    first_step.result = 7.0
+    assert save_result(1, project_name) == True
+    assert client_project.storage_scope.get_text(first_step.result_file) == "7.0"
+
+
+def test_load_result_callback(client_project: {{ cookiecutter.__solution_definition_class_name }}, project_name: str):
+    result_file = client_project.storage_scope.get_storage_root() / "result_file.txt"
+    result_file.write_text("29.5")
+    first_step = client_project.steps.first_step
+    first_step.result_file = client_project.storage_scope.store(result_file)
+    assert load_result(1, project_name) == (29.5, True)

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

@@ -0,0 +1,56 @@
+[tox]
+description = Default tox environments list
+envlist =
+    style,{py39,py310}{,-coverage},doc,build
+skip_missing_interpreters = true
+isolated_build = true
+
+[gh-actions]
+description = The tox environment to be executed in gh-actions for a given python version
+python =
+    3.9: style,py39-coverage,doc,build
+    3.10: style,py310-coverage,doc,build
+
+[testenv]
+description = Perform functional testing
+basepython =
+    py39: python3.9
+    py310: python3.10
+    py: python3
+    {style,reformat,doc,build}: python3
+skip_install = true
+passenv = *
+allowlist_externals = poetry
+commands =
+    poetry config virtualenvs.create false
+    poetry install --only main,tests -vv
+    poetry run pytest -p no:faulthandler --cov={{ cookiecutter.__solution_namespace }} --cov-report=term --cov-report=xml --cov-report=html -vv
+    poetry run coverage lcov
+
+[testenv:style]
+description = Checks project code style
+skip_install = true
+deps =
+    pre-commit
+setenv =
+    SKIP = poetry-check
+commands =
+    pre-commit install
+    pre-commit run --all-files --show-diff-on-failure
+
+[testenv:doc]
+description = Check if documentation generates properly
+skip_install = true
+commands =
+    poetry config virtualenvs.create false
+    poetry install --only doc -vv
+    poetry run sphinx-build doc/source doc/build/html --color -vW -bhtml
+
+[testenv:build]
+description = Check source code build
+skip_install = true
+commands =
+    poetry config virtualenvs.create false
+    poetry install --only build -vv
+    poetry run python -m build
+

ansys/saf/cli/_utilities/__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/_utilities/archiver.py

@@ -0,0 +1,67 @@
+# 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 zipfile
+
+SOLUTION_EXT = ".saf"
+DEFAULT_EXCLUDED_DIRS = [".venv", ".poetry", ".git", "glow", "portal", ".github"]
+
+
+def archive_solution(
+    solution_root_dir: Path,
+    archive_name: str,
+    archive_path: Path | None = None,
+    archive_extension: str | None = None,
+) -> None:
+    """Archive a solution directory into a zip file.
+
+    This function takes a solution directory, compresses its contents into a zip file, and saves
+    it to the specified archive path or the current working directory if no path is provided.
+
+    Parameters
+    ----------
+    solution_root_dir : Path
+        The path to the solution's root directory (which contains src/) to be archived.
+    archive_name : str
+        The name of the archive file (without extension).
+    archive_path : Path, optional
+        The path where the archive file will be saved. Default path: current working directory.
+    archive_extension : str, optional
+        The extension for the archive file, including the initial dot. Default extension: ".saf".
+    """
+    if archive_path and not archive_path.is_dir():
+        raise NotADirectoryError(f"{archive_path} is not a valid directory.")
+
+    extension = f"{archive_extension}" if archive_extension is not None else SOLUTION_EXT
+
+    archive_path = (archive_path if archive_path else Path.cwd()) / f"{archive_name}{extension}"
+
+    with zipfile.ZipFile(archive_path, "w", zipfile.ZIP_DEFLATED) as zip_file:
+        stack = [solution_root_dir]
+        while stack:
+            current_path = stack.pop()
+            with os.scandir(current_path) as entries:
+                for entry in entries:
+                    entry_path = current_path / entry.name
+                    # Makes sure that the created .saf file is not part of the archive itself!
+                    # (This typically happens when running "saf archive .").
+                    if entry.is_file() and str(entry_path.resolve()) != zip_file.filename:
+                        parent_path = os.path.relpath(entry_path, solution_root_dir)
+                        zip_file.write(entry_path, parent_path)
+                    elif entry.is_dir() and entry.name not in DEFAULT_EXCLUDED_DIRS:
+                        stack.append(entry_path)