vpype_cli.State#

class State(document: Optional[vpype.model.Document] = None)#

Encapsulates the current state of the vpype pipeline processing.

This class encapsulates the current state of the pipeline and provides services to commands. To access the current state instance, a command must use the pass_state() decorator.

Parameters: document (vp.Document | None) -- if provided, use this document

Methods

`current`	Context manager to set the current state (used internally).
`expression_variables`	Context manager to temporarily set expression variables.
`get_current`	Returns the current `State` instance.
`preprocess_argument`	Evaluate an argument.
`preprocess_arguments`	Evaluate any instance of `_DeferredEvaluator` and replace them with the converted value.
`substitute`	Apply property and expression substitution on user input.
`temp_document`	Context manager to temporarily clear the state's document.

Attributes

`document`	Content of the current pipeline.
`target_layer_id`	Default layer ID used by `generator()` and `layer_processor()` commands when `--layer` is not provided.
`current_layer_id`	Layer ID being populated by a `generator()` or processed by a `layer_processor()` command.

Methods#

State.current()#: Context manager to set the current state (used internally).

State.expression_variables(variables: dict[str, Any]) → Generator[None, None, None]#

Context manager to temporarily set expression variables.

This context manager is typically used by block processors to temporarily set relevant expression variables. These variables are deleted or, if pre-existing, restored upon exiting the context.

Parameters: variables (dict[str, Any]) -- variables to set
Return type: Generator[None, None, None]

Example:

>>> import vpype_cli
>>> @vpype_cli.cli.command()
... @vpype_cli.block_processor
... def run_twice(state, processors):
...     with state.expression_variables({"_first": True}):
...         vpype_cli.execute_processors(processors, state)
...     with state.expression_variables({"_first": False}):
...         vpype_cli.execute_processors(processors, state)

classmethod State.get_current()#

Returns the current State instance.

Commands should use the pass_state() decorator instead of using this function.

State.preprocess_argument(arg: Any) → Any#

Evaluate an argument.

If arg is a _DeferredEvaluator instance, evaluate it a return its value instead.

Parameters: arg (Any) -- argument to evaluate
Returns: returns the fully evaluated arg
Return type: Any

State.preprocess_arguments(args: tuple[Any, ...], kwargs: dict[str, Any]) → tuple[tuple[Any, ...], dict[str, Any]]#

Evaluate any instance of _DeferredEvaluator and replace them with the converted value.

Parameters

args (tuple[Any, ...]) --
kwargs (dict[str, Any]) --

Return type

tuple[tuple[Any, …], dict[str, Any]]

State.substitute(text: str) → str#

Apply property and expression substitution on user input.

Parameters: text (str) -- user input on which to perform the substitution
Returns: fully substituted text
Return type: str

State.temp_document(keep_layer: bool = True) → Generator[vpype.model.Document, None, None]#

Context manager to temporarily clear the state’s document.

This context manager is typically used by block processor to temporarily clear the document of line data while retaining its structure when executing nested processors. The context manager returns the temporary document instance. It is typically used by block processors to extend the original document after running the nested commands.

Parameters: keep_layer (bool) -- keep the layer structure
Returns: the temporary document instance
Return type: Generator[vpype.model.Document, None, None]

Example:

>>> import vpype_cli
>>> @vpype_cli.cli.command()
... @vpype_cli.block_processor
... def clean_block(state, processors):
...     with state.temp_document() as temp_doc:
...         # state.document is now empty but has the same structure as the
...         # original document
...         vpype_cli.execute_processors(processors, state)
...     # update the original document with the temporary one
...     state.document.extend(temp_doc)

Attributes#

State.document: vpype.model.Document#: Content of the current pipeline.

State.target_layer_id: int | None#: Default layer ID used by generator() and layer_processor() commands when --layer is not provided.

State.current_layer_id: int | None#: Layer ID being populated by a generator() or processed by a layer_processor() command.