ansys-saf-templates 0.2.dev0

Collection of templates to develop in SAF solutions.

Overview

SAF Templates is a collection of Cookiecutter-based templates that help developers quickly scaffold common components for SAF-based solution applications. Instead of writing boilerplate code from scratch, developers can generate ready-to-use solution steps, pages, and supporting files through the SAF CLI, then customize them to fit their specific use case.

The package currently ships the following built-in step templates:

Template	Description
calculator-step	A step that performs basic calculator operations.
hps-simple-job-step	A step that submits a simple job to HPS.
hps-parametric-study-step	A step that runs a parametric study on HPS.
instance-mgmt-geometry-step	A step for basic Geometry instance management.

Beyond the built-in templates, SAF Templates supports a plugin architecture that allows developers and teams to create, package, and share their own template repositories. This means you can build reusable templates tailored to your organization’s patterns and distribute them across projects or to the wider community.

Contributions are welcomed. If you have a useful template that could benefit other SAF developers, consider contributing it back to the project or publishing your own template plugin repository.

Installation

Ensure you have all the necessary prerequisites. Then, refer to the installation guidelines for detailed instructions on how to install the project in your system.

Documentation

The official documentation of SAF Templates contains the following chapters:

• Getting started. This section provides a brief overview and instructions on how to get started with the project. It typically includes information on how to install the project, set up any necessary dependencies, and run a basic example or test to ensure everything is functioning correctly.

• User guide. The user guide section offers detailed documentation and instructions on how to use the project. It provides comprehensive explanations of the project’s features, functionalities, and configuration options. The user guide aims to help users understand the project’s concepts, best practices, and recommended workflows.

• Contribute. This section provides guidelines and instructions on how to contribute to the project. It includes information on how to set up the development environment, run tests, submit pull requests, and follow contribution guidelines.

Troubleshooting

For troubleshooting or reporting issues, open an issue in the project repository.

Follow these steps to report an issue:

• Go to the project repository.

• Click on the Issues tab.

• Click on the New Issue button.

• Provide a clear and detailed description of the issue you are facing.

• Include any relevant error messages, code snippets, or screenshots.

Additionally, you can refer to the official documentation for additional resources and troubleshooting guides.

License

This project is licensed under the Apache 2.0 License - see the LICENSE file for details.

Changelog

The changelog section provides a summary of notable changes for each version of SAF Product Configuration for Python. It helps you keep track of updates, bug fixes, new features, and improvements made to the project over time.

To view the complete changelog, visit the project repository and navigate to the CHANGELOG file. It provides a comprehensive list of changes categorized by version, along with brief descriptions of each change.

How it works?

Adding templates to the repository

Note: currently only step templates can be added to the repository. Support for other types of templates (e.g., solution templates) is going to be added in the future.

To add a new step template, create a new directory under src/ansys/saf/templates/steps and add the template files to that directory. The template files should adhere to the following structure:

my_step/
|
├── {{cookiecutter.__solution_module_name}}/
|   |
|   ├── solution/
|   |   |
|   |   └── {{cookiecutter.__step_module_name}}.py  # definition of StepModel subclass
|   |
|   └── ui/pages/
|       |
|       └── {{cookiecutter.__ui_page_file_name}}.py  # definition of the step's UI
|
├── hooks
|   |
|   ├── pre_gen_project.py  # Not required, only if pre-generation hooks are needed
|   |
|   └── post_gen_project.py
|
└── cookiecutter.json

An entry for the new template has to be added to templates.toml.

[templates.my-step]
location = "steps/my_step"
type = "step"
description = "a step that performs some action"

[templates.my-step.dependencies]
pendulum = ">=3.2.0"

This example assumes that the template was added under src/ansys/saf/templates/steps/my_step. This is not a requirement as the step templates can be added anywhere under src/ansys/saf/templates/steps. The only requirement is that the location field in the templates.toml entry must be a relative path under src/ansys/saf/templates that points to the template’s root.

The template name is defined inside the square brackets ([templates.<template-name>]) and must be unique across all templates in the repository, as it is used to identify the template to be generated from SAF CLI. Kebab-case should be used for template names.

The type field indicates the type of the template, which currently can only be step.

The description field provides a brief description of the template that is going to be displayed in SAF CLI when listing the available templates.

Any new dependencies required by the template should be added to the dependencies section of the template entry in a format that is valid for the pyproject.toml. These dependencies are going to be automatically installed in the generated project’s virtual environment when the template is generated.

All fields are mandatory except for dependencies. Any template that is not included in the templates.toml file won’t be discoverable.

Creating a new template plugin repository

To create a repository that can be used as a template plugin it needs:

1. to adhere to a certain structure

2. to be declared as a plugin in its pyproject.toml,

3. to have a __init__.py file that includes a function returning the path to the plugin, and

4. to include the configuration of the defined templates in a templates.toml file.

Structure of a template plugin repository

The structure of a template plugin repository should be as follows:

my_template_plugin/
|
├── pyproject.toml  # includes the declaration of the plugin entry-point
|
└── src/package/templates_module
    |
    ├── __init__.py  # includes the get_plugin_path function
    |
    ├── templates.toml  # includes the configuration of the templates defined in this plugin
    |
    └── <template_structure>  # one or more directories containing the templates defined in this plugin

Declare an entry-point in pyproject.toml

The template plugin repository needs to declare itself as a plugin in its pyproject.toml. The entry-point group "ansys_saf_templates" is mandatory. The important part of the entry-point is its value "package.templates_module:get_plugin_path". Its name plugin_path is not relevant and can be modified.

[project.entry-points."ansys_saf_templates"]
plugin_path = "package.templates_module:get_plugin_path"

The first part of the entry-point value must match the installation path of the repository, so the pyproject.toml should also include:

[[tool.poetry.packages]]
include = "package/templates_module"
from = "src"

The second part points to the function get_plugin_path that we must define in the __init__.py file.

Add the function get_plugin_path to __init__.py

The content of the __init__.py should be:

from pathlib import Path


def get_plugin_path() -> Path:
    """Return the path to the cookiecutter template."""
    return Path(__file__).parent.resolve()

Add the template’s configuration file templates.toml

The configuration of all the templates is defined in a single templates.toml file under src/package/templates_module. This file must contain an entry for every template containing the fields described in the previous section.