docutils.statemachine.State Class Reference

Inheritance diagram for docutils.statemachine.State:

Public Member Functions
	__init__ (self, state_machine, debug=False)
	runtime_init (self)
	unlink (self)
	add_initial_transitions (self)
	add_transitions (self, names, transitions)
	add_transition (self, name, transition)
	remove_transition (self, name)
	make_transition (self, name, next_state=None)
	make_transitions (self, name_list)
	no_match (self, context, transitions)
	bof (self, context)
	eof (self, context)
	nop (self, match, context, next_state)

Public Attributes
	transition_order
	transitions
	state_machine
	debug

Static Public Attributes
	patterns = None
	initial_transitions = None
	nested_sm = None
	nested_sm_kwargs = None

Detailed Description

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.

Constructor & Destructor Documentation

__init__()

docutils.statemachine.State.__init__	(		self,
			state_machine,
			debug = False
	)

Initialize a `State` object; make & add initial transitions.

Parameters:

- `statemachine`: the controlling `StateMachine` object.
- `debug`: a boolean; produce verbose output if true.

Reimplemented in docutils.parsers.rst.states.RSTState, docutils.parsers.rst.states.QuotedLiteralBlock, and docutils.statemachine.StateWS.

Member Function Documentation

add_initial_transitions()

docutils.statemachine.State.add_initial_transitions

(

self

)

Make and add transitions listed in `self.initial_transitions`.

Reimplemented in docutils.statemachine.StateWS.

add_transition()

docutils.statemachine.State.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`.

add_transitions()

docutils.statemachine.State.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`.

bof()

docutils.statemachine.State.bof	(		self,
			context
	)

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

Override in subclasses.

Parameter `context`: application-defined storage.

Reimplemented in docutils.parsers.rst.states.RSTState.

eof()

docutils.statemachine.State.eof	(		self,
			context
	)

Handle end-of-file. Return empty result.

Override in subclasses.

Parameter `context`: application-defined storage.

Reimplemented in docutils.parsers.rst.states.Text, docutils.parsers.rst.states.SpecializedText, docutils.parsers.rst.states.Definition, docutils.parsers.rst.states.Line, and docutils.parsers.rst.states.QuotedLiteralBlock.

make_transition()

docutils.statemachine.State.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`.

make_transitions()

docutils.statemachine.State.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).

no_match()

docutils.statemachine.State.no_match	(		self,
			context,
			transitions
	)

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.

Reimplemented in docutils.parsers.rst.states.RSTState.

nop()

docutils.statemachine.State.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).

remove_transition()

docutils.statemachine.State.remove_transition	(		self,
			name
	)

Remove a transition by `name`.

Exception: `UnknownTransitionError`.

runtime_init()

docutils.statemachine.State.runtime_init

(

self

)

Initialize this `State` before running the state machine; called from
`self.state_machine.run()`.

Reimplemented in docutils.parsers.rst.states.RSTState.

unlink()

docutils.statemachine.State.unlink

(

self

)

Remove circular references to objects no longer required.

---

The documentation for this class was generated from the following file:

• docs/help/help-venv/lib/python3.12/site-packages/docutils/statemachine.py