vpype_cli.State#

class State(document: Optional[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.

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