Types

Note

Even though these types are made for public consumption and usage should be encouraged/easily possible it should be noted that these may be moved out to new libraries at various points in the future (for example the FSM code may move to its own oslo supported automaton library at some point in the future [1]). If you are using these types without using the rest of this library it is strongly encouraged that you be a vocal proponent of getting these made into isolated libraries (as using these types in this manner is not the expected and/or desired usage).

Cache

Failure

FSM

exception taskflow.types.fsm.FrozenMachine[source]

Bases: exceptions.Exception

Exception raised when a frozen machine is modified.

exception taskflow.types.fsm.NotInitialized(message, cause=None)[source]

Bases: taskflow.exceptions.TaskFlowException

Error raised when an action is attempted on a not inited machine.

class taskflow.types.fsm.FSM(start_state)[source]

Bases: object

A finite state machine.

This state machine can be used to automatically run a given set of transitions and states in response to events (either from callbacks or from generator/iterator send() values, see PEP 342). On each triggered event, a on_enter and on_exit callback can also be provided which will be called to perform some type of action on leaving a prior state and before entering a new state.

NOTE(harlowja): reactions will only be called when the generator/iterator from run_iter() does not send back a new event (they will always be called if the run() method is used). This allows for two unique ways (these ways can also be intermixed) to use this state machine when using run_iter(); one where external events trigger the next state transition and one where internal reaction callbacks trigger the next state transition. The other way to use this state machine is to skip using run() or run_iter() completely and use the process_event() method explicitly and trigger the events via some external functionality.

current_state[source]

Return the current state name.

Returns:current state name
Return type:string
terminated[source]

Returns whether the state machine is in a terminal state.

Returns:whether the state machine is in terminal state or not
Return type:boolean
add_state(state, terminal=False, on_enter=None, on_exit=None)[source]

Adds a given state to the state machine.

Parameters:
  • on_enter – callback, if provided will be expected to take two positional parameters, these being state being entered and the second parameter is the event that is being processed that caused the state transition
  • on_exit – callback, if provided will be expected to take two positional parameters, these being state being entered and the second parameter is the event that is being processed that caused the state transition
  • state (string) – state being entered or exited
add_reaction(state, event, reaction, *args, **kwargs)[source]

Adds a reaction that may get triggered by the given event & state.

Parameters:
  • state (string) – the last stable state expressed
  • event – event that caused the transition
  • args (list) – non-keyworded arguments
  • kwargs (dictionary) – key-value pair arguments

Reaction callbacks may (depending on how the state machine is ran) be used after an event is processed (and a transition occurs) to cause the machine to react to the newly arrived at stable state. The expected result of a callback is expected to be a new event that the callback wants the state machine to react to. This new event may (depending on how the state machine is ran) get processed (and this process typically repeats) until the state machine reaches a terminal state.

add_transition(start, end, event)[source]

Adds an allowed transition from start -> end for the given event.

Parameters:
  • start – start of the transition
  • end – end of the transition
  • event – event that caused the transition
process_event(event)[source]

Trigger a state change in response to the provided event.

Parameters:event – event to be processed to cause a potential transition
initialize()[source]

Sets up the state machine (sets current state to start state...).

run(event, initialize=True)[source]

Runs the state machine, using reactions only.

copy()[source]

Copies the current state machine.

NOTE(harlowja): the copy will be left in an uninitialized state.

run_iter(event, initialize=True)[source]

Returns a iterator/generator that will run the state machine.

NOTE(harlowja): only one runner iterator/generator should be active for a machine, if this is not observed then it is possible for initialization and other local state to be corrupted and cause issues when running...

freeze()[source]

Freezes & stops addition of states, transitions, reactions...

states[source]

Returns the state names.

events[source]

Returns how many events exist.

Returns:how many events exist
Return type:number
pformat(sort=True)[source]

Pretty formats the state + transition table into a string.

NOTE(harlowja): the sort parameter can be provided to sort the states and transitions by sort order; with it being provided as false the rows will be iterated in addition order instead.

Example:

>>> from taskflow.types import fsm
>>> f = fsm.FSM("sits")
>>> f.add_state("sits")
>>> f.add_state("barks")
>>> f.add_state("wags tail")
>>> f.add_transition("sits", "barks", "squirrel!")
>>> f.add_transition("barks", "wags tail", "gets petted")
>>> f.add_transition("wags tail", "sits", "gets petted")
>>> f.add_transition("wags tail", "barks", "squirrel!")
>>> print(f.pformat())
+-----------+-------------+-----------+----------+---------+
    Start   |    Event    |    End    | On Enter | On Exit
+-----------+-------------+-----------+----------+---------+
    barks   | gets petted | wags tail |          |
   sits[^]  |  squirrel!  |   barks   |          |
  wags tail | gets petted |   sits    |          |
  wags tail |  squirrel!  |   barks   |          |
+-----------+-------------+-----------+----------+---------+

Futures

Graph

Notifier

Periodic

Table

class taskflow.types.table.PleasantTable(columns)[source]

Bases: object

A tiny pretty printing table (like prettytable/tabulate but smaller).

Creates simply formatted tables (with no special sauce):

>>> from taskflow.types import table
>>> tbl = table.PleasantTable(['Name', 'City', 'State', 'Country'])
>>> tbl.add_row(["Josh", "San Jose", "CA", "USA"])
>>> print(tbl.pformat())
+------+----------+-------+---------+
  Name |   City   | State | Country
+------+----------+-------+---------+
  Josh | San Jose |  CA   |   USA
+------+----------+-------+---------+

Timing

Tree

exception taskflow.types.tree.FrozenNode[source]

Bases: exceptions.Exception

Exception raised when a frozen node is modified.

class taskflow.types.tree.Node(item, **kwargs)[source]

Bases: object

A n-ary node class that can be used to create tree structures.

empty()[source]

Returns if the node is a leaf node.

path_iter(include_self=True)[source]

Yields back the path from this node to the root node.

find(item)[source]

Returns the node for an item if it exists in this node.

This will search not only this node but also any children nodes and finally if nothing is found then None is returned instead of a node object.

Parameters:item – item to lookup.
Returns:the node for an item if it exists in this node
pformat()[source]

Recursively formats a node into a nice string representation.

Example:

>>> from taskflow.types import tree
>>> yahoo = tree.Node("CEO")
>>> yahoo.add(tree.Node("Infra"))
>>> yahoo[0].add(tree.Node("Boss"))
>>> yahoo[0][0].add(tree.Node("Me"))
>>> yahoo.add(tree.Node("Mobile"))
>>> yahoo.add(tree.Node("Mail"))
>>> print(yahoo.pformat())
CEO
|__Infra
|  |__Boss
|     |__Me
|__Mobile
|__Mail
child_count(only_direct=True)[source]

Returns how many children this node has.

This can be either only the direct children of this node or inclusive of all children nodes of this node (children of children and so-on).

NOTE(harlowja): it does not account for the current node in this count.

reverse_iter()[source]

Iterates over the direct children of this node (left->right).

index(item)[source]

Finds the child index of a given item, searches in added order.

dfs_iter(include_self=False)[source]

Depth first iteration (non-recursive) over the child nodes.

bfs_iter(include_self=False)[source]

Breadth first iteration (non-recursive) over the child nodes.

[1]See: https://review.openstack.org/#/c/141961 for a proposal to do this.

Table Of Contents

Navigation

This Page