docutils.statemachine.StateWS

class documentation

class StateWS(State): (source)

Known subclasses: docutils.parsers.rst.states.RSTState

State superclass specialized for whitespace (blank lines & indents). Use this class with `StateMachineWS`. The transitions 'blank' (for blank lines) and 'indent' (for indented text blocks) are added automatically, before any other transitions. The transition method `blank()` handles blank lines and `indent()` handles nested indented blocks. Indented blocks trigger a new state machine to be created by `indent()` and run. The class of the state machine to be created is in `indent_sm`, and the constructor keyword arguments are in the dictionary `indent_sm_kwargs`. The methods `known_indent()` and `firstknown_indent()` are provided for indented blocks where the indent (all lines' and first line's only, respectively) is known to the transition method, along with the attributes `known_indent_sm` and `known_indent_sm_kwargs`. Neither transition method is triggered automatically.

Method	`__init__`	Initialize a `StateSM` object; extends `State.__init__()`.
Method	`add_initial_transitions`	Add whitespace-specific transitions before those defined in subclass.
Method	`blank`	Handle blank lines. Does nothing. Override in subclasses.
Method	`first_known_indent`	Handle an indented text block (first line's indent known).
Method	`indent`	Handle an indented text block. Extend or override in subclasses.
Method	`known_indent`	Handle a known-indent text block. Extend or override in subclasses.
Class Variable	`ws_initial_transitions`	Default initial whitespace transitions, added before those listed in `State.initial_transitions`. May be overridden in subclasses.
Class Variable	`ws_patterns`	Patterns for default whitespace transitions. May be overridden in subclasses.
Instance Variable	`indent_sm`	The `StateMachine` class handling indented text blocks.
Instance Variable	`indent_sm_kwargs`	Keyword arguments dictionary, passed to the `indent_sm` constructor.
Instance Variable	`known_indent_sm`	The `StateMachine` class handling known-indented text blocks.
Instance Variable	`known_indent_sm_kwargs`	Keyword arguments dictionary, passed to the `known_indent_sm` constructor.
Instance Variable	`patterns`	{Name: pattern} mapping, used by `make_transition()`. Each pattern may be a string or a compiled `re` pattern. Override in subclasses.

Inherited from State:

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

def __init__(self, state_machine, debug=False): (source)

overrides docutils.statemachine.State.__init__

overridden in docutils.parsers.rst.states.RSTState

Initialize a `StateSM` object; extends `State.__init__()`. Check for indent state machine attributes, set defaults if not set.

def add_initial_transitions(self): (source)

overrides docutils.statemachine.State.add_initial_transitions

Add whitespace-specific transitions before those defined in subclass. Extends `State.add_initial_transitions()`.

def blank(self, match, context, next_state): (source)

overridden in docutils.parsers.rst.states.QuotedLiteralBlock, docutils.parsers.rst.states.Text

Handle blank lines. Does nothing. Override in subclasses.

def first_known_indent(self, match, context, next_state): (source)

Handle an indented text block (first line's indent known). Extend or override in subclasses. Recursively run the registered state machine for known-indent indented blocks (`self.known_indent_sm`). The indent is the length of the match, ``match.end()``.

def indent(self, match, context, next_state): (source)

overridden in docutils.parsers.rst.states.Body, docutils.parsers.rst.states.QuotedLiteralBlock, docutils.parsers.rst.states.Text

Handle an indented text block. Extend or override in subclasses. Recursively run the registered state machine for indented blocks (`self.indent_sm`).

def known_indent(self, match, context, next_state): (source)

Handle a known-indent text block. Extend or override in subclasses. Recursively run the registered state machine for known-indent indented blocks (`self.known_indent_sm`). The indent is the length of the match, ``match.end()``.

ws_initial_transitions: tuple[str, ...] = (source)

Default initial whitespace transitions, added before those listed in `State.initial_transitions`. May be overridden in subclasses.

ws_patterns = (source)

Patterns for default whitespace transitions. May be overridden in subclasses.

indent_sm = (source)

The `StateMachine` class handling indented text blocks. If left as ``None``, `indent_sm` defaults to the value of `State.nested_sm`. Override it in subclasses to avoid the default.

indent_sm_kwargs = (source)

Keyword arguments dictionary, passed to the `indent_sm` constructor. If left as ``None``, `indent_sm_kwargs` defaults to the value of `State.nested_sm_kwargs`. Override it in subclasses to avoid the default.

known_indent_sm = (source)

The `StateMachine` class handling known-indented text blocks. If left as ``None``, `known_indent_sm` defaults to the value of `indent_sm`. Override it in subclasses to avoid the default.

known_indent_sm_kwargs = (source)

Keyword arguments dictionary, passed to the `known_indent_sm` constructor. If left as ``None``, `known_indent_sm_kwargs` defaults to the value of `indent_sm_kwargs`. Override it in subclasses to avoid the default.

patterns: dict = (source)

overrides docutils.statemachine.State.patterns

overridden in docutils.parsers.rst.states.Body, docutils.parsers.rst.states.QuotedLiteralBlock, docutils.parsers.rst.states.Text

{Name: pattern} mapping, used by `make_transition()`. Each pattern may be a string or a compiled `re` pattern. Override in subclasses.