Client API#

This section documents GLOW’s Client API which enable programs, including a Dash UI server, to access a remote GLOW server that provides the guided workflow service for a given GLOW solution (a guided workflow application).

class ansys.saf.glow.client.AbstractStoragePath#

Bases: object

A base class for representing paths to folders, directories, files or blobs in a hierarchical storage scheme, such as an OS Filesystem or cloud storage.

as_uri() → str#

Return a URI that refers to the entity referenced by the path.

Returns:
str

A URI that refers to the entity referenced by the path.

copy(destination: AbstractStoragePath) → None#

Copy the referenced entity to the given destination directory or folder. The destination directory and any missing parents will be created if they do not exist.

Parameters:
destinationAbstractStoragePath

The directory or folder where the referenced entity will be copied.

copyfileobj(fileobj) → None#

Create or replace of the referenced entity with the contents of the file-like object fileobj.

Parameters:
fileobjfile like object

The object that is the source of data to become the content of the referenced entity.

property exists: bool#

Whether the entity referenced by the path exists.

Returns:
bool

Whether the entity referenced by the path exists.

glob(pattern: str) → list[AbstractStoragePath]#

Return the paths of entities with in the referenced fdirectory or folder that match the given pattern.

Parameters:
patternstr

The pattern that is used to match entities within the referenced directory. The pattern can include * as a wild match and ** which matches directories recursively.

Returns:
list of AbstractStoragePath

The paths of entities with in the referenced directory or folder that match the given pattern.

is_dir() → bool#

Return whether the path refers to a directory or folder.

Returns:
bool

Whether the path refers to a directory or folder.

is_file() → bool#

Return whether the path refers to a file or blob.

Returns:
bool

Whether the path refers to a file or blob.

iterdir() → Iterator[AbstractStoragePath]#

Return an iterator over the entities that exist on the directory or folder referenced by the path.

Returns:
Iterator over AbstractStoragePath

The entities that exist on the directory or folder referenced by the path.

mkdir() → None#

Create the directory referenced by the path including all the parent directories.

property name: str#

The name of the entity referenced by the path.

Returns:
str

The name of the entity referenced by the path.

property parent: AbstractStoragePath#

The directory or folder that contains the entity referenced by the path.

Returns:
AbstractStoragePath

The directory or folder that contains the entity referenced by the path.

read_text() → str#

Return the text content of the file or blob that the path refers to.

Returns:
str

The text content of the file or blob that the path refers to.

remove() → None#

Remove recursively the entire directory, folder, file or blob referenced by the path.

resolve() → AbstractStoragePath#

Make the path absolute, resolving any symbolic links or .. components. A new path object is returned.

Returns:
AbstractStoragePath

A new reference to the same entity but removing symbolic links and .. components.

property stem: str#

The name of the entity referenced by the path with its suffix (file extension).

Returns:
str

The name of the entity referenced by the path with its suffix (file extension).

property suffix: str#

The suffix for file extension of the entity referenced by the path.

Returns:
str

The suffix for file extension of the entity referenced by the path.

write_bytes(data: bytes) → None#

Replace the content of the file or blob that the path refers to or creates a new file or blob.

Parameters:
databytes

The new content of the file or blob referenced by the path.

write_text(text: str) → None#

Replace the content of the file or blob that the path refers to or creates a new file or blob.

Parameters:
textstr

The new content of the file or blob referenced by the path.

write_text_with_new_dir(text: str) → None#

Replace the content of the file or blob that the path refers to or creates a new file or blob. Creates the parent directory if it does not already exist.

Parameters:
textstr

The new content of the file or blob referenced by the path.

class ansys.saf.glow.client.AnalysisResultModel(*, valid: bool, error: str = '', stack_trace: str = '', uses_shared_product_instances: bool = False, solution_name: str = '', ui_module: str = '', solution_module: str = '')#

Bases: BaseModel

Represents the result of a solution analysis.

model_config = {}#

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

exception ansys.saf.glow.client.BadRequestException#

Bases: SolutionClientError

Exception raised when the GLOW client API is used incorrectly.

class ansys.saf.glow.client.Client(solution_type: type[T], url: str, external_url: str | None = None, access_token: str | None = None, api_key: str | None = None)#

Bases: Generic[T]

Client for enabling access to a remote GLOW Solution.

Parameters:
solution_type: type[Solution]

The Solution that is being implemented remotely. Must be a class that has been derived from Solution.

url: str

The URL of the remote Solution GLOW REST API

external_url: optional[str]

The URL of the remote Solution GLOW REST API from outside the UI container (e.g. a browser) in on-premises deployments.

access_token: optional[str]

An optional access token containing the security credentials for a login session.

api_key: optional[str]

An optional API key sent via the x-api-key header. Takes precedence over access_token.

close()#

Close the transport and proxies.

create_project(display_name: str, description: str = '') → T#

Create a new project with the specified display_name. Return a Solution instance with the same fields and methods as the Solution specified in the Client constructor.

Parameters:
display_namestr

The project name displayed to the user.

descriptionstr, optional

The project description. Defaults to an empty string.

Returns:
T derived from ansys.saf.glow.solution.Solution

A Solution instance with the same fields and methods as the Solution specified in the Client constructor.

delete_project(name: str) → None#

Delete a project specified by its resource name (projects/<project_id>).

Parameters:
namestr

Resource name of an existing project.

Has the form projects/<project_id>.

property deployment_type: Deployment#

Return the deployment type derived from the value of the GLOW_DEPLOYMENT environment variable which corresponds to how the server in which the client is running is deployed.

Returns:
Deployment

The deployment type derived from the value of the GLOW_DEPLOYMENT environment variable which corresponds to how the server in which the client is running is deployed.

get_project(name: str) → T#

Return the Solution instance for a project specified by its resource name (projects/<project_id>).

Parameters:
namestr

Resource name of an existing project.

Has the form projects/<project_id>.

Returns:
T derived from ansys.saf.glow.solution.Solution

Solution instance for the project referred to by name with the same fields and methods as the Solution specified in the Client constructor.

get_schema() → Any#

Return the JSON schema structure (dictionary) for the Solution passed to the constructor.

Returns:
Any

JSON schema structure (dictionary) for the Solution passed to the constructor.

property http_client#

The http client used to communicate with the GLOW REST API.

import_project(safx_path: Path, display_name: str) → T#

Import the given .safx project archive with the specified display_name and open it.

Parameters:
safx_pathPath

The path of to the safx project file.

(A .safx project file is an archive of a .sap project with its associated project directory.)

display_namestr

The project name displayed to the user.

Returns:
T derived from ansys.saf.glow.solution.Solution

A Solution instance for the imported file with the same fields and methods as the Solution specified in the Client constructor.

list_projects(page_size: int | None = None, page: int | None = None, order_by: str | None = None, filter: str | None = None) → Any#

List projects with pagination, ordering, and optional filtering. By default, returns the first page of results with a maximum of 100 projects per page.

Parameters:
page_sizeoptional, int

The maximum number of projects to return in the response. If not specified, defaults to returning at most 100 projects. Values above 100 will be coerced to 100.

pageoptional, int

The page number to return (1-indexed). If not specified, defaults to returning the first page.

order_byoptional, str

Comma-separated list of fields to order by. The default sorting order is ascending. To specify descending order for a field, append a “ desc” suffix; for example: "date_modified desc, name".

Supported fields are display_name, description, date_created, date_modified, and name.

filteroptional, str

A filter expression to narrow down the listed projects. Follows the syntax: <field> <operator> <value> [AND <field> <operator> <value>]...

Supported fields:
  • display_name: Only supports = (case-insensitive, contains match).

  • description: Only supports = (case-insensitive, contains match).

  • date_created: Supports =, !=, <, >, <=, >=.

  • date_modified: Supports =, !=, <, >, <=, >=.

Date values must be ISO 8601 strings (e.g., 2024-01-15T00:00:00, 2024-01-15).

Examples:
  • "display_name = Motor"

  • "description = benchmark"

  • "date_created >= 2024-01-01T00:00:00"

  • "display_name = Motor AND date_created >= 2024-01-01T00:00:00"

Returns:
dict[str, Any]

JSON response with project information and pagination metadata.

Example response:

{
    "projects": [{"name": "projects/<id>", "display_name": "my project"}],
    "current_page": 1,
    "total_pages": 20,
    "page_size": 100,
    "total_projects": 2000
}
upgrade_project(name: str) → T#

Upgrade the version of the Solution instance for a project specified by its resource name (projects/<project_id>).

Parameters:
namestr

Resource name of an existing project.

Has the form projects/<project_id>.

Returns:
T derived from ansys.saf.glow.solution.Solution

Solution instance for the project referred to by name with the same fields and methods as the Solution specified in the Client constructor.

exception ansys.saf.glow.client.ConflictException#

Bases: SolutionClientError

Exception raised when the GLOW client API is invoked making a request inconsistent with a given project state.

class ansys.saf.glow.client.DashClient#

Bases: Generic[T]

Client for use in the Dash UI framework that enables access to remote GLOW Solution.

static create_event_listener(step: StepModel, stream_name: str, id: str) → WebSocket#

Return a WebSocket configured to receive data from transaction events on the stream_name channel.

Parameters:
step: StepModel

The instance of the step used on the UI layout.

stream_name: str

The name of the stream that the WebSocket will try to connect to. A step may have multiple streams.

idstr

The identifier used on the HTML element that contains the WebSocket.

Returns:
WebSocket

A WebSocket configured to receive events data on the stream_name channel.

Examples

>>> layout = html.Div([
>>>    html.Button("Trigger Event", id="trigger_event", n_clicks=0),
>>>    html.Div(id="event_message", children="Not triggered yet"),
>>>    html.Div(id="ws_container"),
>>> ])
>>>
>>> @callback(
>>>   Input("trigger_event", "n_clicks"),
>>>   State("url", "pathname"),
>>>   prevent_initial_call=True,
>>> )
>>> def trigger_transaction_event(n_clicks, project: MySolution):
>>>    if n_clicks > 0:
>>>        step = project.steps.my_step
>>>        step.trigger_event()
>>>
>>> @callback(
>>>     Output("event_message", "children"),
>>>     Input("my_ws", "message"),
>>>     prevent_initial_call=True,
>>> )
>>> def message(message):
>>>     if message:
>>>         return f"Received message: {message['data']}"
>>>     else:
>>>         return "No message received yet."
static get_deployment_type() → Deployment#

Return the deployment type derived from the value of the GLOW_DEPLOYMENT environment variable which corresponds to how the server in which the client is running is deployed. Normally this will be the UI server of the solution.

Returns:
Deployment

The deployment type derived from the value of the GLOW_DEPLOYMENT environment variable which corresponds to how the server in which the client is running is deployed. Normally this will be the UI server of the solution.

static get_portal_ui_url() → str | None#

Return the URL of the SAF Portal UI. This URL is typically exposed as a link that enables the user to return to the Portal UI after using the Solution UI for a specific project.

Returns:
str

The URL of the SAF Portal UI.

class ansys.saf.glow.client.Deployment(*values)#

Bases: Enum

Categories of deployments for the GLOW server.

exception ansys.saf.glow.client.InternalSolutionException#

Bases: SolutionClientError

Exception raised when the solution experienced a problem server-side.

class ansys.saf.glow.client.LongRunning(step_model_type: type[StepModel], step_name: str, method_name: str, method_url: str, http_client: Client, return_type: T)#

Bases: Generic[T]

An object that monitors the execution of a call to a long-running transaction method.

A method that is decorated with long_running() will return a LongRunning object when called from a Solution instance returned by the GLOW client. The calling environment can use the LongRunning object to monitor the method execution.

It is not expected that the constructor will be called directly by a Solution client.

Parameters:
step_model_typetype of StepModel

The step class that contains the method to be monitored.

step_namestr

The name of the step that contains the method to be monitored. The name of a step is the name of a field on a StepsModel derived class. The StepsModel derived class is the type of the steps field which defines the set of steps in a Solution derived class.

method_namestr

The name of the method that contains the method to be monitored.

method_urlstr

The URL of the method to be monitored.

Notes

For more detailed information on the concept of long-running methods, see the corresponding section of the User Guide.

get_state() → MethodState#

Get the state of the long running method.

Returns:
MethodState

The current state of the method execution

Notes

For instructions and an example on using this method, see the corresponding section in the User Guide.

is_complete(raise_for_error: bool = True) → bool#

Specify whether the long-running method is complete or not.

Parameters:
raise_for_errorbool

If specified, then an exception is raised if the method has failed.

Returns:
bool

Whether the long-running method is complete or not.

Notes

For instructions and an example of using this method, see the corresponding section in the User Guide.

wait(timeout: int | None = None) → T#

Wait for the long running method to terminate.

If the process does not terminate after timeout seconds, then raise a TimeoutError exception. It is safe to catch this exception and retry the wait.

Parameters:
timeoutint

If specified, then the parameter can be used to control the maximum number of seconds to wait before returning.

Notes

For a description of this method with an example of its use, see the corresponding section in the User Guide.

exception ansys.saf.glow.client.NotFoundException#

Bases: SolutionClientError

Exception raised when the GLOW client API is invoked to access an object that does not exist.

class ansys.saf.glow.client.OperatingSystemPath(path: str | Path)#

Bases: AbstractStoragePath

A path to a directory or file in a OS Filesystem which may or may not actually exist.

Parameters:
pathstr or pathlib.Path

A path to a directory or file in a OS Filesystem.

as_uri() → str#

Return a URI that refers to the entity referenced by the path.

Returns:
str

A URI that refers to the entity referenced by the path.

copy(destination: AbstractStoragePath) → None#

Copy the referenced entity to the given destination directory or folder. The destination directory and any missing parents will be created if they do not exist.

Parameters:
destinationAbstractStoragePath

The directory or folder where the referenced entity will be copied.

copyfileobj(fileobj) → None#

Create or replace of the referenced entity with the contents of the file-like object fileobj.

Parameters:
fileobjfile like object

The object that is the source of data to become the content of the referenced entity.

property exists#

Whether the entity referenced by the path exists.

Returns:
bool

Whether the entity referenced by the path exists.

glob(pattern: str) → list[AbstractStoragePath]#

Return the paths of entities with in the referenced fdirectory or folder that match the given pattern.

Parameters:
patternstr

The pattern that is used to match entities within the referenced directory. The pattern can include * as a wild match and ** which matches directories recursively.

Returns:
list of AbstractStoragePath

The paths of entities with in the referenced directory or folder that match the given pattern.

is_dir() → bool#

Return whether the path refers to a directory or folder.

Returns:
bool

Whether the path refers to a directory or folder.

is_file() → bool#

Return whether the path refers to a file or blob.

Returns:
bool

Whether the path refers to a file or blob.

iterdir() → Iterator[AbstractStoragePath]#

Return an iterator over the entities that exist on the directory or folder referenced by the path.

Returns:
Iterator over AbstractStoragePath

The entities that exist on the directory or folder referenced by the path.

mkdir() → None#

Create the directory referenced by the path including all the parent directories.

property name: str#

The name of the entity referenced by the path.

Returns:
str

The name of the entity referenced by the path.

property parent: AbstractStoragePath#

The directory or folder that contains the entity referenced by the path.

Returns:
AbstractStoragePath

The directory or folder that contains the entity referenced by the path.

read_text() → str#

Return the text content of the file or blob that the path refers to.

Returns:
str

The text content of the file or blob that the path refers to.

remove() → None#

Remove recursively the entire directory, folder, file or blob referenced by the path.

resolve() → AbstractStoragePath#

Make the path absolute, resolving any symbolic links or .. components. A new path object is returned.

Returns:
AbstractStoragePath

A new reference to the same entity but removing symbolic links and .. components.

property stem: str#

The name of the entity referenced by the path with its suffix (file extension).

Returns:
str

The name of the entity referenced by the path with its suffix (file extension).

property suffix: str#

The suffix for file extension of the entity referenced by the path.

Returns:
str

The suffix for file extension of the entity referenced by the path.

write_bytes(data: bytes) → None#

Replace the content of the file or blob that the path refers to or creates a new file or blob.

Parameters:
databytes

The new content of the file or blob referenced by the path.

write_text(text: str) → None#

Replace the content of the file or blob that the path refers to or creates a new file or blob.

Parameters:
textstr

The new content of the file or blob referenced by the path.

write_text_with_new_dir(text: str) → None#

Replace the content of the file or blob that the path refers to or creates a new file or blob. Creates the parent directory if doesn’t exist.

Parameters:
textstr

The new content of the file or blob referenced by the path.

class ansys.saf.glow.client.OperatingSystemStorage#

Bases: AbstractStorage

A factory for OperatingSystemPath objects.

create_path_from_reference(reference: str) → AbstractStoragePath#

Create a OperatingSystemPath object given a URL.

Parameters:
referencestr

The URL of a file or directory.

Returns:
AbstractStoragePath

A object for accessing the file or directory.

exception ansys.saf.glow.client.PermissionException#

Bases: SolutionClientError

Exception raised when the GLOW client API is invoked to trigger an operation that the user does not have permission to perform.

exception ansys.saf.glow.client.SolutionLoadException(errors: str | list[str])#

Bases: Exception

Exception raised when errors are detected during validation of a Solution derived class prior to creating an API server.

Parameters:
errorsstr, list of str

Errors detected in the a Solution derived class.

property errors: str#

Errors detected in a Solution derived class.

Returns:
str

Errors detected in a Solution derived class.

exception ansys.saf.glow.client.UnauthorizedException#

Bases: SolutionClientError

Exception raised when the GLOW client API is invoked to trigger an operation that the user does not have authorization to perform.

class ansys.saf.glow.client.callback(*args: Any, **kwargs: Any)#

Bases: object

A decorator of Dash callback functions that replaces the Dash callback decorator.

This decorator ensures that: - project can be injected into a callback argument.

  • Open Telemetry trace spans are generated for callback executions;

  • The start and end of callback executions are logged ensuring that the module name, callback name, trace id and span id are visible in the log; and

  • The DashClient class is initialized also in the new process that is spawn when a callback is run in the background.

This class expects the dash_extensions.enrich package to be installed.

The parameters of this decorator are identical to the Dash callback decorator.