docutils.statemachine.State

class documentation

class State(object):

Known subclasses: docutils.statemachine.StateWS

View In Hierarchy

State superclass. Contains a list of transitions, and transition methods.

Transition methods all have the same signature. They take 3 parameters:

  • An re match object. match.string contains the matched input line, match.start() gives the start index of the match, and match.end() gives the end index.
  • A context object, whose meaning is application-defined (initial value None). It can be used to store any information required by the state machine, and the returned context is passed on to the next transition method unchanged.
  • The name of the next state, a string, taken from the transitions list; normally it is returned unchanged, but it may be altered by the transition method if necessary.

Transition methods all return a 3-tuple:

  • A context object, as (potentially) modified by the transition method.
  • The next state name (a return value of None means no state change).
  • The processing result, a list, which is accumulated by the state machine.

Transition methods may raise an EOFError to cut processing short.

There are two implicit transitions, and corresponding transition methods are defined: bof() handles the beginning-of-file, and eof() handles the end-of-file. These methods have non-standard signatures and return values. bof() returns the initial context and results, and may be used to return a header string, or do any other processing needed. eof() should handle any remaining context and wrap things up; it returns the final processing result.

Typical applications need only subclass State (or a subclass), set the patterns and initial_transitions class attributes, and provide corresponding transition methods. The default object initialization will take care of constructing the list of transitions.

Method __init__ Initialize a State object; make & add initial transitions.
Method add​_initial​_transitions Make and add transitions listed in self.initial_transitions.
Method add​_transition Add a transition to the start of the transition list.
Method add​_transitions Add a list of transitions to the start of the transition list.
Method bof Handle beginning-of-file. Return unchanged context, empty result.
Method eof Handle end-of-file. Return empty result.
Method make​_transition Make & return a transition tuple based on name.
Method make​_transitions Return a list of transition names and a transition mapping.
Method no​_match Called when there is no match from StateMachine.check_line().
Method nop A "do nothing" transition method.
Method remove​_transition Remove a transition by name.
Method runtime​_init Initialize this State before running the state machine; called from self.state_machine.run().
Method unlink Remove circular references to objects no longer required.
Class Variable initial​_transitions A list of transitions to initialize when a State is instantiated. Each entry is either a transition name string, or a (transition name, next state name) pair. See make_transitions(). Override in subclasses.
Class Variable patterns {Name: pattern} mapping, used by make_transition(). Each pattern may be a string or a compiled re pattern. Override in subclasses.
Instance Variable debug Debugging mode on/off.
Instance Variable nested​_sm The StateMachine class for handling nested processing.
Instance Variable nested​_sm​_kwargs Keyword arguments dictionary, passed to the nested_sm constructor.
Instance Variable state​_machine A reference to the controlling StateMachine object.
Instance Variable transition​_order A list of transition names in search order.
Instance Variable transitions No summary
def __init__(self, state_machine, debug=False):
overridden in docutils.statemachine.StateWS

Initialize a State object; make & add initial transitions.

Parameters:

def add_initial_transitions(self):
overridden in docutils.statemachine.StateWS
Make and add transitions listed in self.initial_transitions.
def add_transition(self, name, transition):

Add a transition to the start of the transition list.

Parameter transition: a ready-made transition 3-tuple.

Exception: DuplicateTransitionError.

def add_transitions(self, names, transitions):

Add a list of transitions to the start of the transition list.

Parameters:

  • names: a list of transition names.
  • transitions: a mapping of names to transition tuples.

Exceptions: DuplicateTransitionError, UnknownTransitionError.

def bof(self, context):
overridden in docutils.parsers.rst.states.RSTState

Handle beginning-of-file. Return unchanged context, empty result.

Override in subclasses.

Parameter context: application-defined storage.

def eof(self, context):
overridden in docutils.parsers.rst.states.QuotedLiteralBlock, docutils.parsers.rst.states.Text

Handle end-of-file. Return empty result.

Override in subclasses.

Parameter context: application-defined storage.

def make_transition(self, name, next_state=None):

Make & return a transition tuple based on name.

This is a convenience function to simplify transition creation.

Parameters:

  • name: a string, the name of the transition pattern & method. This State object must have a method called 'name', and a dictionary self.patterns containing a key 'name'.
  • next_state: a string, the name of the next State object for this transition. A value of None (or absent) implies no state change (i.e., continue with the same state).

Exceptions: TransitionPatternNotFound, TransitionMethodNotFound.

def make_transitions(self, name_list):

Return a list of transition names and a transition mapping.

Parameter name_list: a list, where each entry is either a transition name string, or a 1- or 2-tuple (transition name, optional next state name).

def no_match(self, context, transitions):
overridden in docutils.parsers.rst.states.RSTState

Called when there is no match from StateMachine.check_line().

Return the same values returned by transition methods:

  • context: unchanged;
  • next state name: None;
  • empty result list.

Override in subclasses to catch this event.

def nop(self, match, context, next_state):

A "do nothing" transition method.

Return unchanged context & next_state, empty result. Useful for simple state changes (actionless transitions).

def remove_transition(self, name):

Remove a transition by name.

Exception: UnknownTransitionError.

def runtime_init(self):
overridden in docutils.parsers.rst.states.RSTState
Initialize this State before running the state machine; called from self.state_machine.run().
def unlink(self):
Remove circular references to objects no longer required.
initial_transitions =
overridden in docutils.parsers.rst.states.Body, docutils.parsers.rst.states.QuotedLiteralBlock, docutils.parsers.rst.states.Text
A list of transitions to initialize when a State is instantiated. Each entry is either a transition name string, or a (transition name, next state name) pair. See make_transitions(). Override in subclasses.
patterns =
overridden in docutils.statemachine.StateWS
{Name: pattern} mapping, used by make_transition(). Each pattern may be a string or a compiled re pattern. Override in subclasses.
debug =
Debugging mode on/off.
nested_sm =

The StateMachine class for handling nested processing.

If left as None, nested_sm defaults to the class of the state's controlling state machine. Override it in subclasses to avoid the default.

nested_sm_kwargs =
overridden in docutils.parsers.rst.states.RSTState

Keyword arguments dictionary, passed to the nested_sm constructor.

Two keys must have entries in the dictionary:

  • Key 'state_classes' must be set to a list of State classes.
  • Key 'initial_state' must be set to the name of the initial state class.

If nested_sm_kwargs is left as None, 'state_classes' defaults to the class of the current state, and 'initial_state' defaults to the name of the class of the current state. Override in subclasses to avoid the defaults.

state_machine =
A reference to the controlling StateMachine object.
transition_order: list =
A list of transition names in search order.
transitions: dict =
A mapping of transition names to 3-tuples containing (compiled_pattern, transition_method, next_state_name). Initialized as an instance attribute dynamically (instead of as a class attribute) because it may make forward references to patterns and methods in this or other classes.