vpype_cli.State¶

class State(document: Document | None = 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.

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

Attributes¶

State.document: 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.