Command Line

Concourse Tools uses a custom CLI tool for easier management of command line functions.

class concoursetools.cli.parser.CLI[source]

Represents a command line interface.

invoke(args)[source]

Invoke the CLI.

Parameters:

args (list[str]) – Arguments to be parsed.

Return type:

None

register(allow_short=None)[source]

Decorate a function.

The decorated function will be registered as a command. Positional-only parameters will become arguments and keyword-only parameters will become options. All parameters must be one or the other.

Parameters:

allow_short (set[str] | None) – A set of function parameters that are allowed a one-letter alias. By default, the parameter my_parameter becomes --my-parameter, but by including my_parameter in this set, -m will also be valid on the command line.

Return type:

Callable[[Callable[..., None]], Callable[..., None]]

register_function(func, allow_short=None)[source]

Manually register a function.

Parameters:

  • func (Callable[..., None]) – A function to be registered as a command. Positional-only parameters will become arguments and keyword-only parameters will become options. All parameters must be one or the other.

  • allow_short (set[str] | None) – A set of function parameters that are allowed a one-letter alias. By default, the parameter my_parameter becomes --my-parameter, but by including my_parameter in this set, -m will also be valid on the command line.

Return type:

None

print_help(spacing=2, separation=1)[source]

Print the help page.

Parameters:

  • spacing (int) – The size of the indent for the keys and values, as well as the minimum spacing between keys and values.

  • separation (int) – The number of new lines between help sections.

Return type:

None

print_version()[source]

Print the version of Concourse Tools.

Return type:

None

class concoursetools.cli.parser.CLICommand(name, description, inner_function, inner_parser, positional_arguments, options)[source]

Represents a command in a CLI.

Parameters:

  • name (str) – The name of the command.

  • description (str | None) – An optional description of the command.

  • inner_function (Callable[..., None]) – The function on which the command is based.

  • inner_parser (ArgumentParser) – Used to parse the arguments for the command.

  • positional_arguments (list[PositionalArgument[Any]]) – A list of positional arguments.

  • options (list[Option[Any]]) – A list of options.

invoke(args)[source]

Invoke the CLI.

Parameters:

args (list[str]) – Arguments to be parsed.

Return type:

None

parse_args(args)[source]

Parse the arguments for a function.

Parameters:

args (list[str]) – Arguments to be parsed.

Return type:

tuple[list[Any], dict[str, Any]]

Returns:

The args and kwargs to be passed to the inner function.

print_help(spacing=2, separation=1)[source]

Print the help page for the command.

Parameters:

  • spacing (int) – The size of the indent for the keys and values, as well as the minimum spacing between keys and values.

  • separation (int) – The number of new lines between help sections.

Return type:

None

usage_string()[source]

Return the usage string for the command.

Return type:

str

classmethod from_function(func, allow_short=None)[source]

Create a new parser from a function.

Parameters:

  • func (Callable[..., None]) – A function to be registered as a command. Positional-only parameters will become arguments and keyword-only parameters will become options. All parameters must be one or the other.

  • allow_short (set[str] | None) – A set of function parameters that are allowed a one-letter alias. By default, the parameter my_parameter becomes --my-parameter, but by including my_parameter in this set, -m will also be valid on the command line.

Return type:

CLICommand

class concoursetools.cli.docstring.Docstring(first_line, description, parameters)[source]

Represents a function docstring.

Parameters:

  • first_line (str) – The first line of the docstring (separated by double whitespace).

  • description (str) – The remaining description before any parameters.

  • parameters (dict[str, str]) – A mapping of parameter name to description, with newlines replaced with whitespace.

classmethod from_object(obj)[source]

Parse an object with a docstring.

Parameters:

obj (object) – An object which may have a docstring, such as a function or module.

Return type:

Docstring

classmethod from_string(raw_docstring)[source]

Parse a docstring.

Parameters:

raw_docstring (str) – The raw docstring of an object.

Return type:

Docstring

Parameters

class concoursetools.cli.parser.PositionalArgument(name, param_type, description=None)[source]

Represents a positional function/CLI parameter.

Parameters:

  • name (str) – The name of the argument.

  • param_type (type[TypeVar(T)]) – The Python type of the argument.

  • description (str | None) – An optional description of the argument.

class concoursetools.cli.parser.Option(name, param_type, description=None, default=None, allow_short=False)[source]

Represents a generic function/CLI option.

Parameters:

  • name (str) – The name of the option.

  • param_type (type[TypeVar(T)]) – The Python type of the option.

  • description (str | None) – An optional description of the option.

  • default (Optional[TypeVar(T)]) – The option default, if set.

  • allow_short (bool) – Set to True to allow a short option, i.e. -o as well as --option.

class concoursetools.cli.parser.FlagOption(name, description, default)[source]

Represents a generic function/CLI flag.

Parameters:

  • name (str) – The name of the flag.

  • description (str | None) – An optional description of the flag.

  • default (bool) – The option default, if set. Should be either True or False.

class concoursetools.cli.parser.Parameter(name, param_type, description=None)[source]

Represents a generic function/CLI parameter.

Parameters:

  • name (str) – The name of the parameter.

  • param_type (type[TypeVar(T)]) – The Python type of the parameter.

  • description (str | None) – An optional description of the parameter.

property long_alias: str

The long alias for the parameter.

Example:
>>> Option("my_option", str).long_alias
'--my-option'
property short_alias: str

The short alias for the parameter.

Example:
>>> Option("my_option", str).short_alias
'-m'
abstract property aliases: tuple[str, ...]

The aliases for the option.

abstractmethod add_to_parser(parser)[source]

Add the parameter to a parser.

Parameters:

parser (ArgumentParser) – The parser in question.

Seealso:

This is done using argparse.ArgumentParser.add_argument().

Return type:

None

classmethod yield_from_function(func, allow_short)[source]

Yield parameters from a function.

Parameters are parsed from the docstring using a combination of inspect.signature() and concoursetools.cli.docstring.Docstring.from_object().

Parameters:

  • func (Callable[..., None]) – The function to parse.

  • allow_short (set[str]) – A set of function parameters that are allowed a one-letter alias. By default, the parameter my_parameter becomes --my-parameter, but by including my_parameter in this set, -m will also be valid on the command line.

Return type:

Generator[Parameter[Any]]