State machine model¶

class besser.BUML.metamodel.state_machine.state_machine.ConfigProperty(section: str, name: str, value: Any)[source]¶

Bases: object

A configuration property of a state machine.

Parameters:¶

section (str) – The section the configuration property belongs to
name (str) – The name of the configuration property
value (Any) – Te value of the configuration property

Attributes:¶

section (str) – The section the configuration property belongs to
name (str) – The name of the configuration property
value (Any) – Te value of the configuration property

class besser.BUML.metamodel.state_machine.state_machine.Action[source]¶

Bases: ABC

Base class for actions composing a Body.

Actions represent discrete operations that can be performed in a state body, enabling programmatic manipulation and model transformation.

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.state_machine.state_machine.CustomCodeAction(source: str = None, callable: Callable = None)[source]¶

Bases: Action

Arbitrary code action from a callable or raw source string.

Parameters:¶

source (str, optional) – Raw Python source code
callable (Callable, optional) – A callable whose source will be extracted

Attributes:¶

source (str) – The Python source code

to_code() → str[source]¶

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.state_machine.state_machine.Body(name: str, callable: Callable = None, actions: list[Action] | None = None)[source]¶

Bases: Method

The body of the state of a state machine.

Each state has a Body, which defines the sequence of actions to be executed when an event causes the transition to a state (and a secondary body, i.e., a fallback body, that defines the actions to be executed in case of error in the machine).

Parameters:¶

name (str) – The name of the body.
callable (Callable) – The function containing the body’s code.
actions (Optional[List[Action]]) – List of actions composing the body

Attributes:¶

name (str) – Inherited from Method, represents the name of the body.
visibility (str) – Inherited from Method, represents the visibility of the body.
type (Type) – Inherited from Method, represents the type of the body.
is_abstract (bool) – Inherited from Method, indicates if the body is abstract.
parameters (set[structural.Parameter]) – Inherited from Method, the set of parameters for the body.
owner (Type) – Inherited from Method, the type that owns the property.
code (str) – Inherited from Method, code of the body (contains source of CustomCodeAction if present, otherwise “”).
actions (List[Action]) – List of actions composing the body

_extract_code() → str[source]¶: Extract code from CustomCodeAction if present, otherwise return empty string.

add_action(action: Action) → Body[source]¶

Add an action to the body.

Parameters:¶: action (Action) – The action to add
Returns:¶: Returns self for method chaining
Return type:¶: Body

add_custom_code(source: str) → Body[source]¶

Add custom Python code as an action.

Parameters:¶: source (str) – The Python source code
Returns:¶: Returns self for method chaining
Return type:¶: Body

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.state_machine.state_machine.Event(name: str)[source]¶

Bases: NamedElement

The representation of an event (i.e., external or internal stimuli or input) that may cause the transition of state in a state machine.

Parameters:¶: name (str) – The name of the event.
Attributes:¶: name (str) – Inherited from NamedElement, represents the name of the event.

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.state_machine.state_machine.Condition(name: str, callable: Callable = None, source: str = None)[source]¶

Bases: Method

The representation of a condition (i.e., a boolean function) that may cause the transition of state in a state machine.

A Condition can be created from either a callable (whose source will be extracted via inspect.getsource) or a raw source-code string. Providing a source string is useful when the condition originates from serialised data (e.g. JSON round-trip through the web editor) where no live callable is available.

Parameters:¶

name (str) – The name of the condition.
callable (Callable, optional) – The function containing the condition’s code.
source (str, optional) – Raw Python source code for the condition. If both callable and source are given, callable takes precedence.

Attributes:¶

name (str) – Inherited from Method, represents the name of the condition.
visibility (str) – Inherited from Method, represents the visibility of the condition.
type (Type) – Inherited from Method, represents the type of the condition.
is_abstract (bool) – Inherited from Method, indicates if the condition is abstract.
parameters (set[structural.Parameter]) – Inherited from Method, the set of parameters for the condition.
owner (Type) – Inherited from Method, the type that owns the property.
code (str) – Inherited from Method, code of the condition.

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.state_machine.state_machine.TransitionBuilder(source: State, event: Event = None, conditions: list[Condition] = None)[source]¶

Bases: object

A transition builder.

This class is used to build transitions, allowing for a “fluent api” syntax where consecutive calls can be made on the same object.

Parameters:¶

source (State) – the source state of the transition
event (Event) – the event linked to the transition (can be None)
conditions (list[Condition]) – the conditions associated to the transition (can be None)

Attributes:¶

source (State) – The source state of the transition
event (Event) – The event linked to the transition (can be None)
condition (list[Condition]) – The conditions associated to the transition (can be None)

with_condition(condition: Condition) → TransitionBuilder[source]¶

go_to(dest: State) → None[source]¶

Set the destination state of the transition.

Completes the transition builder and effectively adds the source state.

Parameters:¶: dest (State) – the destination state

class besser.BUML.metamodel.state_machine.state_machine.Transition(name: str, source: State, dest: State, event: Event, conditions: list[Condition])[source]¶

Bases: NamedElement

A state machine transition from one state (source) to another (destination).

A transition is triggered when an event and/or condition/s occurs.

Parameters:¶

name (str) – Inherited from NamedElement, the transition name
source (State) – the source state of the transition (from where it is triggered)
dest (State) – the destination state of the transition (where the machine moves to)
event (Callable[[Session, dict], bool]) – the event that triggers the transition
conditions (list[Condition]) – the conditions that trigger the transition

Attributes:¶

name (str) – Inherited from NamedElement, the transition name
visibility (str) – Inherited from NamedElement, determines the kind of visibility of the named element (public as default).
source (State) – The source state of the transition (from where it is triggered)
dest (State) – The destination state of the transition (where the machine moves to)
event (Event) – The event that triggers the transition
conditions (list[Condition]) – The conditions that trigger the transition

is_auto() → bool[source]¶

Check if the transition is auto (i.e. no event nor condition linked to it).

Returns:¶: true if the transition is auto, false otherwise
Return type:¶: bool

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.state_machine.state_machine.State(sm: StateMachine, name: str, initial: bool = False, final: bool = False)[source]¶

Bases: NamedElement

A state of a state machine.

Parameters:¶

sm (StateMachine) – the state machine the state belongs to
name (str) – the state name
initial (bool) – whether the state is initial or not
final (bool) – whether the state is final or not

Attributes:¶

name (str) – Inherited from NamedElement, the state name
visibility (str) – Inherited from NamedElement, determines the kind of visibility of the state (public as default).
sm (StateMachine) – the state machine the state belongs to
initial (bool) – whether the state is initial or not
final (bool) – whether the state is final or not
transitions (list[Transition]) – The state’s transitions to other states
body (Body) – the body of the state
fallback_body (Body) – the fallback body of the state
_transition_counter (int) – Count the number of transitions of this state. Used to name the transitions.

_t_name() → str[source]¶

Name generator for transitions. Transition names are generic and enumerated. On each call, a new name is generated and the transition counter is incremented for the next name.

Returns:¶: a name for the next transition
Return type:¶: str

set_body(body: Body) → None[source]¶

Set the state body.

Parameters:¶: body (Body) – the body

set_fallback_body(body: Body) → None[source]¶

Set the state fallback body.

Parameters:¶: body (Body) – the body

when_event(event: Event) → TransitionBuilder[source]¶

when_condition(condition: Condition) → TransitionBuilder[source]¶

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.state_machine.state_machine.StateMachine(name: str)[source]¶

Bases: Model

A state machine model.

Parameters:¶

name (str) – the state machine name

Attributes:¶

name (str) – Inherited from Model, represents the name of the state machine.
visibility (str) – Inherited from Model, determines the kind of visibility of the state machine (public as default).
states (list[State]) – the states of the state machine
properties (list[ConfigProperty]) – the configuration properties of the state machine.

add_property(property: ConfigProperty) → ConfigProperty[source]¶

Add a configuration property to the state machine.

Parameters:¶: property (ConfigProperty) – the property to add
Returns:¶: the configuration property
Return type:¶: ConfigProperty

new_property(section: str, name: str, value: Any) → ConfigProperty[source]¶

Create a new configuration property on the state machine.

Parameters:¶

section (str) – The section the configuration property belongs to
name (str) – The name of the configuration property
value (Any) – Te value of the configuration property

Returns:¶

the configuration property

Return type:¶

ConfigProperty

new_state(name: str, initial: bool = False, final: bool = False) → State[source]¶

Create a new state in the state machine.

Parameters:¶

name (str) – the state name. It must be unique in the state machine.
initial (bool) – whether the state is initial or not. A state machine must have 1 initial state.
final (bool) – whether the state is final or not. A state machine can have multiple final states.

Returns:¶

the state

Return type:¶

State

initial_state() → State[source]¶

Get the state machine’s initial state. It can be None if it has not been set.

Returns:¶: the initial state of the machine, if exists
Return type:¶: State or None

set_global_fallback_body(body: Body) → None[source]¶

Set the global fallback body for all states in the state machine.

Parameters:¶: body (Body) – The fallback body to be set for all states.

validate(raise_exception: bool = True) → dict[source]¶

Validate the state machine according to structural constraints.

Parameters:¶: raise_exception (bool) – If True, raise ValueError when validation fails.
Returns:¶: Validation result with success flag, errors, and warnings.
Return type:¶: dict

_validate_unreachable_states(warnings: list[str])[source]¶: Validate that all non-initial states have at least one incoming transition.

_validate_final_states_with_transitions(errors: list[str])[source]¶: Validate that final states have no outgoing transitions.

_abc_impl = <_abc._abc_data object>¶

class besser.BUML.metamodel.state_machine.state_machine.Session[source]¶

Bases: object

A user session in a state machine execution.

When a user starts interacting with a state machine, a session is assigned to him/her to store user related information, such as the current state or any custom variable. A session can be accessed from the body of the states to read/write user information. If a state machine does not have the concept of ‘users’ (i.e., there are no concurrent executions of the state machine, but a single one) then it could simply have 1 unique session.

Attributes:¶

id (str) – The session id, which must unique among all state machine sessions
current_state (str) – The current state in the state machine for this session

set(key: str, value: Any) → None[source]¶

Set an entry to the session private data storage.

Parameters:¶

key (str) – the entry key
value (Any) – the entry value

get(key: str) → Any[source]¶

Get an entry of the session private data storage.

Parameters:¶: key (str) – the entry key
Returns:¶: the entry value, or None if the key does not exist
Return type:¶: Any

delete(key: str) → None[source]¶

Delete an entry of the session private data storage.

Parameters:¶: key (str) – the entry key

move(transition: Transition) → None[source]¶

Move to another state of the state machine.

Parameters:¶: transition (Transition) – the transition that points to the state to move