State machine model¶

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.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

name¶

Inherited from Method, represents the name of the body.

Type:: str

visibility¶

Inherited from Method, represents the visibility of the body.

Type:: str

type¶

Inherited from Method, represents the type of the body.

Type:: Type

is_abstract¶

Inherited from Method, indicates if the body is abstract.

Type:: bool

parameters¶

Inherited from Method, the set of parameters for the body.

Type:: set[structural.Parameter]

owner¶

Inherited from Method, the type that owns the property.

Type:: Type

code¶

Inherited from Method, code of the body (contains source of CustomCodeAction if present, otherwise “”).

Type:: str

actions¶

List of actions composing the body

Type:: List[Action]

_abc_impl = <_abc._abc_data object>¶

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

actions: List[Action]¶

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

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.

name¶

Inherited from Method, represents the name of the condition.

Type:: str

visibility¶

Inherited from Method, represents the visibility of the condition.

Type:: str

type¶

Inherited from Method, represents the type of the condition.

Type:: Type

is_abstract¶

Inherited from Method, indicates if the condition is abstract.

Type:: bool

parameters¶

Inherited from Method, the set of parameters for the condition.

Type:: set[structural.Parameter]

owner¶

Inherited from Method, the type that owns the property.

Type:: Type

code¶

Inherited from Method, code of the condition.

Type:: str

_abc_impl = <_abc._abc_data object>¶

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

section¶

The section the configuration property belongs to

Type:: str

name¶

The name of the configuration property

Type:: str

value¶

Te value of the configuration property

Type:: Any

name: str¶

section: str¶

value: Any¶

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

source¶

The Python source code

Type:: str

_abc_impl = <_abc._abc_data object>¶

to_code() → str[source]¶

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.

name¶

Inherited from NamedElement, represents the name of the event.

Type:: str

_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.

id¶

The session id, which must unique among all state machine sessions

Type:: str

current_state¶

The current state in the state machine for this session

Type:: str

current_state: State¶

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

Delete an entry of the session private data storage.

Parameters:: key (str) – the entry key

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

id: str¶

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

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

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

name¶

Inherited from NamedElement, the state name

Type:: str

visibility¶

Inherited from NamedElement, determines the kind of visibility of the state (public as default).

Type:: str

sm¶

the state machine the state belongs to

Type:: StateMachine

initial¶

whether the state is initial or not

Type:: bool

final¶

whether the state is final or not

Type:: bool

transitions¶

The state’s transitions to other states

Type:: list[Transition]

body¶

the body of the state

Type:: Body

fallback_body¶

the fallback body of the state

Type:: Body

_transition_counter¶

Count the number of transitions of this state. Used to name the transitions.

Type:: int

_abc_impl = <_abc._abc_data object>¶

_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

_transition_counter: int¶

body: Body¶

fallback_body: Body¶

final: bool¶

initial: bool¶

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

sm: StateMachine¶

transitions: list[Transition]¶

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

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

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

name¶

Inherited from Model, represents the name of the state machine.

Type:: str

visibility¶

Inherited from Model, determines the kind of visibility of the state machine (public as default).

Type:: str

states¶

the states of the state machine

Type:: list[State]

properties¶

the configuration properties of the state machine.

Type:: list[ConfigProperty]

_abc_impl = <_abc._abc_data object>¶

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

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

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

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

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

properties: list[ConfigProperty]¶

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.

states: list[State]¶

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

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

name¶

Inherited from NamedElement, the transition name

Type:: str

visibility¶

Inherited from NamedElement, determines the kind of visibility of the named element (public as default).

Type:: str

source¶

The source state of the transition (from where it is triggered)

Type:: State

dest¶

The destination state of the transition (where the machine moves to)

Type:: State

event¶

The event that triggers the transition

Type:: Event

conditions¶

The conditions that trigger the transition

Type:: list[Condition]

_abc_impl = <_abc._abc_data object>¶

conditions: list[Condition]¶

dest: State¶

event: Event¶

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

source: State¶

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)