CLI Framework

To simplify the creation of command-line options and streamline script interfaces, the cli module provides a set of predefined argument definitions as well as accompanying tools utilizing the standard library argparse module.

Available Options

Argument	Option	Type	Description
attributes	--attributes, -a	list	Attribute names to include in processing.
classesData	--classes-data, -C	Request	Path to classes metadata file.
clear	--clear, -x	bool	Erase preexisting objects on execution.
color	--color, -c	list	List of RGBA color values.
colors	--colors, -c	loads()	Keys mapped to RGBA color arrays as JSON string.
exclude	--exclude, -e	list	Objects to exclude from processing.
font	--font, -f	Font	Path to UFO file.
fontData	--font-data, -F	Request	Path to font metadata file.
glyphnamesData	--glyphnames-data, -G	Request	Path to glyphnames metadata file.
include	--include, -i	list	Objects to include in processing.
includeOptionals	--include-optionals, -O	bool	Include optional glyphs.
mark	--mark, -m	bool	Apply defined color values to objects.
overwrite	--overwrite, -o	bool	Overwrite preexisting values.
rangesData	--ranges-data, -r	Request	Path to ranges metadata file.
sourcePath	--source-path, -S	Request	Path to source file or directory.
spaces	--spaces, -s	bool	Set unit of measurement to staff spaces.
targetPath	--target-path, -T	str	Path to target file or directory.
verbose	--verbose, -v	bool	Make output verbose.

Note

Short flags for options may be redefined in the cli.shortFlags configuration section.

commonParser(*args: str, addHelp: bool = True, description: str | None = None, customHelpers: dict[str, str] | None = None, **kwargs: Any) → ArgumentParser

Provide generic command-line arguments and options.

See the Available Options for argument definitions.

Positional arguments defined in CLI_ARGUMENTS with action="store_true" or action="store_false" will be treated as a boolean flag.

Added in version 0.6.2: If a keyword argument is assigned the value REQUIRED, it will be treated as a required argument in the command-line interface. Help output can show or hide this status depending on cli.markRequired.

Parameters:

• *args – Names of positional arguments to include.

• addHelp – Add help message. Should be False when function is parent and otherwise True. Defaults to True.

• description – Program description when used directly. Defaults to None

• customHelpers – Arguments mapped to custom help strings to override the default. Defaults to None

• **kwargs – Flagged options and their default values to include. Use the constant REQUIRED as value to mark the option as mandatory.

Example:

>>> from smufolib import commonParser, REQUIRED
>>> parser = commonParser(
...     "font", "clear", targetPath=REQUIRED, includeOptionals=False,
...     description="My SMuFL utility", addHelp=True
... )

createHelpFormatter(formatters: str | tuple[str, ...]) → type[HelpFormatter]

Create child class of multiple help formatters.

The returned argparse.HelpFormatter class can be passed to the formatter_class parameter of argparse.ArgumentParser to combine different formatters, despite the parameter only taking a single class as argument.

Parameters:

formatters – Name of the formatter class or tuple of class names to be enabled as str corresponding to either RawDescriptionHelpFormatter, RawTextHelpFormatter, ArgumentDefaultsHelpFormatter, RawDescriptionHelpFormatter or MetavarTypeHelpFormatter, or a tuple of class names.

Raises:

• TypeError – If formatters is not an accepted type.

• ValueError – If any formatters item is not recognized.

Example:

>>> import argparse
>>> from smufolib import cli
>>> formatter = cli.createHelpFormatter(
...    ("RawTextHelpFormatter", "ArgumentDefaultsHelpFormatter")
... )
>>> parser = argparse.ArgumentParser(
...     formatter_class=formatter,
...     description="Process SMuFL metadata"
... )

CLI_ARGUMENTS: dict[str, dict[str, Any]] = {'attributes': {'help': 'attribute names to include in processing', 'nargs': '+'}, 'classesData': {'help': 'path to classes metadata file', 'type': <class 'smufolib.request.Request'>}, 'clear': {'action': 'store_true', 'help': 'erase preexisting objects on execution'}, 'color': {'help': 'list of RGBA color values', 'nargs': 4, 'type': <function toNumber>}, 'colors': {'help': 'keys mapped to RGBA color arrays as JSON string', 'type': <function loads>}, 'exclude': {'help': 'objects to exclude from processing', 'nargs': '+'}, 'font': {'help': 'path to UFO file', 'type': <class 'smufolib.objects.font.Font'>}, 'fontData': {'help': 'path to font metadata file', 'type': <class 'smufolib.request.Request'>}, 'glyphnamesData': {'help': 'path to glyphnames metadata file', 'type': <class 'smufolib.request.Request'>}, 'include': {'help': 'objects to include in processing', 'nargs': '+'}, 'includeOptionals': {'action': 'store_true', 'help': 'include optional glyphs'}, 'mark': {'action': 'store_true', 'help': 'apply defined color values to objects'}, 'overwrite': {'action': 'store_true', 'help': 'overwrite preexisting values'}, 'rangesData': {'help': 'path to ranges metadata file', 'type': <class 'smufolib.request.Request'>}, 'sourcePath': {'help': 'path to source file or directory', 'type': <class 'smufolib.request.Request'>}, 'spaces': {'action': 'store_true', 'help': 'set unit of measurement to staff spaces'}, 'targetPath': {'help': 'path to target file or directory'}, 'verbose': {'action': 'store_true', 'help': 'make output verbose'}}

Available arguments and their settings.

REQUIRED = <Required>

Sentinel value for required arguments.

class argparse.HelpFormatter

Formatter for generating usage messages and argument help strings.