vpype_cli#
This module implements vpype’s CLI interface and the execute()
function.
Functions
Decorator to define a block processor command. |
|
Execute a vpype pipeline. |
|
Execute a sequence of processors to generate a Document structure. |
|
Decorator to define a generator command. |
|
Decorator to define a global processor command. |
|
Decorator to define a layer processor command. |
|
Convert multiple-layer CLI argument to list of layer IDs. |
|
Marks a command as wanting to receive the current state. |
|
Convert single-layer CLI argument to layer ID, accounting for the existence of a current a current target layer and dealing with default behavior. |
Classes
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Interpret values of --layer options. |
|
|
|
|
|
|
|
Encapsulates the current state of the vpype pipeline processing. |
|
|
|
Abstract base-class for deferred evaluation of command parameters. |
Functions#
- block_processor(f)#
Decorator to define a block processor command.
Block processor function take a
State
instance and a processor list as their first two argument. The processor list consists of the commands enclosed within the block. The block processor implementation should call theexecute_processors()
function to run the processor list, possibly temporarily changing the content of theState
instance content.Example:
@click.command() @vpype_cli.block_processor def my_block_processor(state: vpype_cli.State, processors) -> vpype_cli.State: '''Example block processor''' # block implementation # should include call(s) to vpype_cli.execute_processors(processors, state) return state my_block_processor.help_group = "My Plugins"
- execute(pipeline: str, document: Optional[Document] = None, global_opt: str = '') Document #
Execute a vpype pipeline.
This function serves as a Python API to vpype’s pipeline. It can be used from a regular Python script (as opposed to the
vpype
CLI which must be used from a console or viaos.system()
.If a
vpype.Document
instance is provided, it will be preloaded in the pipeline before the first command executes. The pipeline’s content after the last command is returned as avpype.Document
instance.Examples
Read a SVG file, optimize it and return the result as a
vpype.Document
instance:>>> doc = execute("read input.svg linemerge linesimplify linesort")
Optimize and save a
vpype.Document
instance:>>> doc = vp.Document() >>> # populate `doc` with some graphics >>> execute("linemerge linesimplify linesort write output.svg", doc)
- Parameters
- Returns
pipeline’s content after the last command executes
- Return type
- execute_processors(processors: Iterable[Union[Callable, BeginBlock, EndBlock]], state: State) None #
Execute a sequence of processors to generate a Document structure. For block handling, we use a recursive approach. Only top-level blocks are extracted and processed by block processors, which, in turn, recursively call this function.
- generator(f)#
Decorator to define a generator command.
Generator do not have input, have automatically a “-l, --layer” option added to them, and must return a LineCollection structure, which will be added to a new layer or an existing one depending the option.
- global_processor(f)#
Decorator to define a global processor command.
This type of command implement a global, multi-layer processing and should be used for processors which cannot be applied layer-by-layer independently (in which case, using a
layer_processor()
is advised.No option is automatically added to global processors. In cases where the user should be able to control on which layer(s) the processing must be applied, it is advised to add a
--layer
option (with typeLayerType
) and use themultiple_to_layer_ids()
companion function (see example below)A global processor receives a
Document
as input and must return one.Example:
@click.command() @click.option( "-l", "--layer", type=vpype.LayerType(accept_multiple=True), default="all", help="Target layer(s).", ) @global_processor def my_global_processor( document: vpype.Document, layer: Union[int, List[int]] ) -> vpype.Document: '''Example global processor''' layer_ids = multiple_to_layer_ids(layer, document) for lines in document.layers_from_ids(layer_ids): # [apply some modification to lines] return document my_global_processor.help_group = "My Plugins"
- layer_processor(f)#
Decorator to define a layer processor command.
Layer processors implements “intra-layer” processing, i.e. they are independently called for every layer in the pipeline. A
--layer
option is automatically appended to the option to let the user control on which layer(s) the processor should be applied (by default,all
is used).Layer processors receive a
LineCollection
as input and must return one.Example:
@click.command() @layer_processor def my_processor(lines: vpype.LineCollection) -> vpype.LineCollection: '''Example layer processor''' new_lines = vpype.LineCollection() for line in lines: # [do something with line] new_lines.append(line) return lines my_processor.help_group = "My Plugins"
- multiple_to_layer_ids(layers: int | list[int] | None, document: Document) list[int] #
Convert multiple-layer CLI argument to list of layer IDs.
- pass_state(f)#
Marks a command as wanting to receive the current state.
Note:
pass_state()
must always be placed after the command type decorator (e.g.generator()
and friends).Example:
@click.command() @generator @pass_state def my_generator(state: State) -> vpype.Document: lc = vpype.LineCollection() current_layer_id = state.current_layer_id # ... return lc
- single_to_layer_id(layer: int | None, document: Document, must_exist: bool = False) int #
Convert single-layer CLI argument to layer ID, accounting for the existence of a current a current target layer and dealing with default behavior.
- Arg:
layer: value from a
LayerType
argument document: targetDocument
instance (for new layer ID) must_exists: if True, the function raises aclick.BadParameter
exception