vpype_cli#

This module implements vpype’s CLI interface and the execute() function.

Functions

`block_processor`	Decorator to define a block processor command.
`execute`	Execute a vpype pipeline.
`execute_processors`	Execute a sequence of processors to generate a Document structure.
`generator`	Decorator to define a generator command.
`global_processor`	Decorator to define a global processor command.
`layer_processor`	Decorator to define a layer processor command.
`multiple_to_layer_ids`	Convert multiple-layer CLI argument to list of layer IDs.
`pass_state`	Marks a command as wanting to receive the current state.
`single_to_layer_id`	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

`AngleType`(args, *kwargs)	`click.ParamType` sub-class to automatically converts a user-provided angle.
`ChoiceType`(args, *kwargs)
`FileType`(args, *kwargs)	`click.File` clone which performs substitution on input.
`FloatRangeType`(args, *kwargs)	`click.FloatRange` clone which performs substitution on input.
`FloatType`(args, *kwargs)	`click.ParamType` sub-class to automatically perform property substitution on user input.
`IntRangeType`(args, *kwargs)	`click.IntRange` clone which performs substitution on input.
`IntegerType`(args, *kwargs)	`click.ParamType` sub-class to automatically perform property substitution on user input.
`LayerType`([accept_multiple, accept_new])	Interpret values of --layer options.
`LengthType`(args, *kwargs)	`click.ParamType` sub-class to automatically converts a user-provided lengths into CSS pixel units.
`PageSizeType`(args, *kwargs)	`click.ParamType` sub-class to automatically converts a user-provided page size.
`PathType`(args, *kwargs)	`click.Path` clone which performs substitution on input.
`State`([document])	Encapsulates the current state of the vpype pipeline processing.
`TextType`(args, *kwargs)	`click.ParamType` sub-class to automatically perform property substitution on user input.
`_DeferredEvaluator`(text, param_name, *args, ...)	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 the execute_processors() function to run the processor list, possibly temporarily changing the content of the State 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 via os.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 a vpype.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:

pipeline (str) -- vpype pipeline as would be used with vpype CLI
document (Document | None) -- if provided, is perloaded in the pipeline before the first command executes
global_opt (str) -- global CLI option (e.g. “--verbose”)

Returns:

pipeline’s content after the last command executes

Return type:

Document

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.

Parameters:

processors (Iterable[Callable | BeginBlock | EndBlock]) -- iterable of processors
state (State) -- state structure

Returns:

generated geometries

Return type:

None

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 type LayerType) and use the multiple_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.

Parameters:

layers (int | list[int] | None) -- value from a LayerType argument with accept_multiple=True
document (Document) -- target Document instance

Returns:

List of layer IDs

Return type:

list[int]

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: target Document instance (for new layer ID) must_exists: if True, the function raises a click.BadParameter exception

Returns:

Target layer ID

Parameters:

layer (int | None) --
document (Document) --
must_exist (bool) --

Return type:

int