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
|
|
|
Special type indicating an unconstrained type. |
|
|
|
|
|
|
|
|
|
|
|
|
|
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: Document | None = 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 an 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[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 on 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