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 |
Make and add transitions listed in `self.initial_transitions`. |
| Method | add |
Add a transition to the start of the transition list. |
| Method | add |
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 |
Make & return a transition tuple based on `name`. |
| Method | make |
Return a list of transition names and a transition mapping. |
| Method | no |
Called when there is no match from `StateMachine.check_line()`. |
| Method | nop |
A "do nothing" transition method. |
| Method | remove |
Remove a transition by `name`. |
| Method | runtime |
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 |
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 |
The `StateMachine` class for handling nested processing. |
| Instance Variable | nested |
Keyword arguments dictionary, passed to the `nested_sm` constructor. |
| Instance Variable | state |
A reference to the controlling `StateMachine` object. |
| Instance Variable | transition |
A list of transition names in search order. |
| Instance Variable | transitions |
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. |
docutils.statemachine.StateWSInitialize a `State` object; make & add initial transitions. Parameters: - `statemachine`: the controlling `StateMachine` object. - `debug`: a boolean; produce verbose output if true.
docutils.statemachine.StateWSMake and add transitions listed in `self.initial_transitions`.
Add a transition to the start of the transition list. Parameter `transition`: a ready-made transition 3-tuple. Exception: `DuplicateTransitionError`.
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`.
docutils.parsers.rst.states.RSTStateHandle beginning-of-file. Return unchanged `context`, empty result. Override in subclasses. Parameter `context`: application-defined storage.
Handle end-of-file. Return empty result. Override in subclasses. Parameter `context`: application-defined storage.
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`.
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).
docutils.parsers.rst.states.RSTStateCalled 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.
A "do nothing" transition method. Return unchanged `context` & `next_state`, empty result. Useful for simple state changes (actionless transitions).
docutils.parsers.rst.states.RSTStateInitialize this `State` before running the state machine; called from `self.state_machine.run()`.
docutils.parsers.rst.states.Body, docutils.parsers.rst.states.QuotedLiteralBlock, docutils.parsers.rst.states.TextA 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.
docutils.statemachine.StateWS{Name: pattern} mapping, used by `make_transition()`. Each pattern may be a string or a compiled `re` pattern. Override in subclasses.
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.
docutils.parsers.rst.states.RSTStateKeyword 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.