State of Things

state_of_things.state_of_things

Base classes used to implement complex state machines. Each Thing starts in an initial State, and then updates to the thing’s state execute logic and determine whether or not to change to another state.

See examples directory for ideas on usage.

  • Author(s): Aaron Silinskas

class state_of_things.state_of_things.State

Represents a state that a Thing can enter and exit. The state can transition a Thing into another state when it is updated.

enter(thing: Thing)

Called when a Thing enters this state. Typically used for one-time setup where state-specific context is added to the Thing.

Parameters:

thing (Thing) – the Thing that entered this state.

exit(thing: Thing)

Called when a Thing exists this state. Typically used to clean up resources initialized when the state is entered.

Parameters:

thing (Thing) – the Thing that exited this state.

property name

The state’s name, defaulting to the class name.

update(thing: Thing) → State

Called periodically while a Thing is in this state. This function determines whether the Thing should remain in this state or change to another state.

Often Thing.time_elapsed and Thing.time_active are referenced when a Thing should transition to another state after a given amount of time.

Parameters:

thing (Thing) – the Thing to update in this state.

Returns:

the next state for the Thing, or this state if the Thing should remain unchanged.

Return type:

State

class state_of_things.state_of_things.Thing(initial_state: State, name: str = None)

Represents an object that can only be in one State at a time. It holds all global and state-specific context needed by State implementations to update and transition between states.

Constructor that stores the initial State but does not change to it until update is called.

Parameters:

  • initial_state (State) – the initial State for this thing

  • name (str, optional) – the name of this thing, usually for

  • name. (logging. Defaults to the class)

property current_state: State

The current State of this thing.

Returns:

the current State, or None if it does not have one.

Return type:

State

property name: str

Name of this thing, defaulting to class name but can be manually set via the constructor.

Returns:

the name of this thing.

Return type:

str

property observers: Observers

The observers that will be notified by this Thing. For instance, all observers that implement ThingObserver will be notified when this Thing changes State.

Things can have custom observers that it’s State implementations can notify as needed. For instance, a button Thing may have an observer that is notified when the button is pressed or released.

Returns:

this Thing’s observers.

Return type:

Observers

property previous_state: State

The previous State of this thing.

Returns:

the previous State, or None if it has not changed States.

Return type:

State

property time_active: float

The total amount of time that this thing has been in the current State.

Returns:

the amount of time active in the current State, in seconds.

Return type:

float

property time_elapsed: float

The amount of time that has elapsed since this thing’s last update call.

Returns:

the amount of elapsed time, in seconds.

Return type:

float

update()

Updates time_elapsed and time_active of this thing, and then updates the State by calling State.update of current_state. If State.update returns a different State than the current one, then this thing will transition to the returned State.

class state_of_things.state_of_things.ThingObserver

Implement the state_changed function of this class to receive notifications when a Thing changes state. All Thing observers should inherited from this class.

Logging state changes to stdout is common for debugging purposes.

state_changed(thing: Thing, old_state: State, new_state: State)

Notified when a Thing changes from one State to another.

Parameters: