Utilities API Reference¶

API documentation for RHAPSODY utility functions and helpers.

Backend Registry¶

`rhapsody.backends.discovery.BackendRegistry` ¶

Registry for managing available execution backends.

`get_backend_class(backend_name)` `classmethod` ¶

Get backend class by name.

Parameters:

Name	Type	Description	Default
`backend_name`	`str`	Name of the backend to retrieve	required

Returns:

Type	Description
`type[BaseExecutionBackend]`	Backend class type

Raises:

Type	Description
`ValueError`	If backend is not registered
`ImportError`	If backend module cannot be imported

`list_backends()` `classmethod` ¶

List all registered backend names.

`register_backend(name, import_path)` `classmethod` ¶

Register a new backend.

Parameters:

Name	Type	Description	Default
`name`	`str`	Name of the backend	required
`import_path`	`str`	Full import path to the backend class	required

Task State Constants¶

`rhapsody.backends.constants.TasksMainStates` ¶

Bases: Enum

Enumeration of standard task states used across all backends.

This enum defines the canonical task states that are common to all execution backends, providing a unified interface for task state management.

Attributes:

Name	Type	Description
`DONE`		Task completed successfully.
`FAILED`		Task execution failed.
`CANCELED`		Task was canceled before completion.
`RUNNING`		Task is currently executing.

`rhapsody.backends.constants.StateMapper(backend)` ¶

Unified interface for mapping task states between main workflow and backend systems.

StateMapper provides a centralized mechanism for translating task states between the main workflow system and various backend execution systems (e.g., 'radical', 'dask'). It supports dynamic registration of backend-specific state mappings and bidirectional conversion between main states and backend-specific states.

The class maintains a registry of backend state mappings and provides methods for state conversion, backend detection, and direct state access through attribute notation.

Attributes:

Name	Type	Description
`_backend_registry`	`dict[str, dict[TasksMainStates, Any]]`	Class-level registry mapping backend identifiers to their state mappings.
`backend_name`	`str`	Name of the current backend.
`backend_module`	`Optional[Any]`	Reference to the backend module/object.
`_state_map`	`dict[TasksMainStates, Any]`	Current backend's state mappings.
`_reverse_map`	`dict[Any, TasksMainStates]`	Reverse mapping from backend states to main states.

Parameters:

Name	Type	Description	Default
`backend`	`Union[str, Any]`	The backend identifier, either as a string (e.g., 'radical', 'dask') or as a backend module/object instance.	required

Raises:

Type	Description
`ValueError`	If the specified backend is not registered or cannot be detected.

Example

::

# Register a backend with custom states
StateMapper.register_backend_states(
    backend='my_backend',
    done_state='COMPLETED',
    failed_state='ERROR',
    canceled_state='ABORTED',
    running_state='ACTIVE'
)

# Use the mapper
mapper = StateMapper('my_backend')
backend_state = mapper.DONE  # Returns 'COMPLETED'
# Returns TasksMainStates.DONE
main_state = mapper.to_main_state('COMPLETED')

Initialize StateMapper with a specific backend.

Creates a StateMapper instance configured for the specified backend. The backend can be provided as either a string identifier or a module/object instance.

Parameters:

Name	Type	Description	Default
`backend`	`Union[str, Any]`	Backend identifier. Can be: - String: Backend name like 'radical', 'dask', etc. - Object: Backend module or instance from which name is detected.	required

Raises:

Type	Description
`ValueError`	If the backend is not registered in the registry or if backend name cannot be detected from the provided object.

Note

The backend must be registered using register_backend_states() or register_backend_states_with_defaults() before initialization.

`terminal_states` `property` ¶

Get all terminal states for the current backend.

Returns a tuple containing the backend-specific representations of all terminal states (DONE, FAILED, CANCELED). These are states that indicate a task has finished execution and will not transition further.

Returns:

Name	Type	Description
`tuple`	`tuple`	Backend-specific terminal state values (DONE, FAILED, CANCELED).

Example

::

mapper = StateMapper('my_backend')
terminals = mapper.terminal_states
# Returns ('COMPLETED', 'ERROR', 'ABORTED') for example backend

`getattr(name)` ¶

Access backend-specific states directly via attribute notation.

Enables direct access to backend states using the main state names as attributes (e.g., mapper.DONE, mapper.FAILED).

Parameters:

Name	Type	Description	Default
`name`	`str`	The main state name to access (DONE, FAILED, CANCELED, RUNNING).	required

Returns:

Name	Type	Description
`Any`	`Any`	The backend-specific state value corresponding to the main state.

Raises:

Type	Description
`AttributeError`	If the specified state name is not valid.

Example

::

mapper = StateMapper('my_backend')
done_state = mapper.DONE  # Returns backend's DONE state
running_state = mapper.RUNNING  # Returns backend's RUNNING state

`get_backend_state(main_state)` ¶

Get backend-specific state for a main state.

Retrieves the backend-specific state value that corresponds to the given main state. Accepts both TasksMainStates enum values and string representations.

Parameters:

Name	Type	Description	Default
`main_state`	`Union[TasksMainStates, str]`	The main state to convert. Can be a TasksMainStates enum value or its string representation.	required

Returns:

Name	Type	Description
`Any`	`Any`	The backend-specific state value.

Raises:

Type	Description
`KeyError`	If the main state is not found in the mapping.

Example

::

mapper = StateMapper('my_backend')
backend_state = mapper.get_backend_state(TasksMainStates.DONE)
# Or using string
backend_state = mapper.get_backend_state('DONE')

`register_backend_states(backend, done_state, failed_state, canceled_state, running_state, **additional_states)` `classmethod` ¶

Register state mappings for a new backend.

Associates a backend identifier with its corresponding task state values, mapping the standard task states to backend-specific representations. Supports additional custom state mappings beyond the four core states.

Parameters:

Name	Type	Description	Default
`backend`	`Union[str, Any]`	The identifier for the backend to register. Can be a string, module, or any hashable object.	required
`done_state`	`Any`	Backend's representation of the DONE state.	required
`failed_state`	`Any`	Backend's representation of the FAILED state.	required
`canceled_state`	`Any`	Backend's representation of the CANCELED state.	required
`running_state`	`Any`	Backend's representation of the RUNNING state.	required
`**additional_states`	`Any`	Additional state mappings where the key is the state name (str) and the value is the backend's representation. Keys will be converted to uppercase and matched against TasksMainStates.	`{}`

Returns:

Type	Description
`None`	None

Example

::

StateMapper.register_backend_states(
    backend='slurm',
    done_state='COMPLETED',
    failed_state='FAILED',
    canceled_state='CANCELLED',
    running_state='RUNNING',
    pending='PENDING',
    timeout='TIMEOUT'
)

`register_backend_states_with_defaults(backend)` `classmethod` ¶

Register a backend using default main state values.

Convenience method that registers a backend where the backend-specific states are identical to the main state values (i.e., the string values of the TasksMainStates enum).

Parameters:

Name	Type	Description	Default
`backend`	`Union[str, Any]`	The backend identifier to register.	required

Returns:

Type	Description
`None`	The result of register_backend_states() with default values.

Example

::

# This registers backend states as:
# DONE -> "DONE", FAILED -> "FAILED", etc.
StateMapper.register_backend_states_with_defaults('thread_backend')

`to_main_state(backend_state)` ¶

Convert backend-specific state to main state.

Translates a backend-specific state value back to the corresponding TasksMainStates enum value.

Parameters:

Name	Type	Description	Default
`backend_state`	`Any`	The backend-specific state value to convert.	required

Returns:

Name	Type	Description
`TasksMainStates`	`TasksMainStates`	The corresponding main state enum value.

Raises:

Type	Description
`ValueError`	If the backend state is not recognized.

Example

::

mapper = StateMapper('slurm')
main_state = mapper.to_main_state('COMPLETED')  # TasksMainStates.DONE

Other Utilities¶

Find utility functions in these API modules:

Core API for main functions
Backends API for backend utilities
Task API for task state utilities

Utilities API Reference¶

Backend Registry¶

rhapsody.backends.discovery.BackendRegistry ¶

get_backend_class(backend_name) classmethod ¶

list_backends() classmethod ¶

register_backend(name, import_path) classmethod ¶

Task State Constants¶

rhapsody.backends.constants.TasksMainStates ¶

rhapsody.backends.constants.StateMapper(backend) ¶

terminal_states property ¶

__getattr__(name) ¶

get_backend_state(main_state) ¶

register_backend_states(backend, done_state, failed_state, canceled_state, running_state, **additional_states) classmethod ¶

register_backend_states_with_defaults(backend) classmethod ¶

to_main_state(backend_state) ¶

Other Utilities¶

`rhapsody.backends.discovery.BackendRegistry` ¶

`get_backend_class(backend_name)` `classmethod` ¶

`list_backends()` `classmethod` ¶

`register_backend(name, import_path)` `classmethod` ¶

`rhapsody.backends.constants.TasksMainStates` ¶

`rhapsody.backends.constants.StateMapper(backend)` ¶

`terminal_states` `property` ¶

`getattr(name)` ¶

`get_backend_state(main_state)` ¶

`register_backend_states(backend, done_state, failed_state, canceled_state, running_state, **additional_states)` `classmethod` ¶

`register_backend_states_with_defaults(backend)` `classmethod` ¶

`to_main_state(backend_state)` ¶