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.

Any(*args, **kwargs)

Special type indicating an unconstrained type.

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 preloaded 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:
Return type:

int