cly package

Create configured argparse’s parser.

Submodules

cly.colors module

Shell output formatters functions, like coloring and underlining.

cly.colors.color_text(text: str, color: str) → str

Color text with one of the available colors.

Parameters

• text (str) – Text to color.

• color (str) – One of the available colors’ name.

Returns

Colored text.

Return type

str

cly.colors.format_options(options: List[str]) → str

Format a list of options separating them with comma and ‘or’.

Parameters

options (List[str]) – List of options.

Returns

Formatted options.

Return type

str

cly.colors.get_color(color: str) → str

Get available color by name.

Parameters

color (str) – One of the available colors’ name.

Returns

Unicode character of color.

Return type

str

Raises

SystemExit – If color is not available.

cly.colors.get_print_length(message: str) → int

Get the length user sees in shell of message.

Parameters

message (str) – Message to disregard length of characters user do not see in shell.

Returns

Length user sees in shell.

Return type

int

cly.colors.print_flashy(message: str) → None

Print centralized message by “>” and “<” with width equal to user shell.

Parameters

message (str) – Message to centralize.

cly.colors.underline_text(text: str, color: Optional[str] = None) → str

Underline text.

Parameters

• text (str) – Text to underline.

• color (Optional[str]) – One of the available colors’ name for end character of text, by default None

Returns

Underlined text.

Return type

str

cly.config module

argparse’s parser custom configuration.

class cly.config.ConfiguredParser(config: Dict[str, str], add_help: bool = True)

Bases: object

Configured argparse’s argument parser.

add_help: bool

commands: Optional[Dict[str, Callable[[...], Any]]]

create_command(command: Callable[[...], Any], alias: Optional[str] = None, help_message: Optional[str] = None) → ArgumentParser

Create configured command to script.

Parameters

• command (Callable[..., Any]) – Function that represents the command.

• alias (Optional[str]) – Alias to call command, by default None

• help_message (Optional[str]) – Help message of the command, by default None

Returns

Configured argparse’s parser command.

Return type

argparse.ArgumentParser

create_parser() → ArgumentParser

Create configured parser to create script.

Returns

Configured argparse’s parser.

Return type

argparse.ArgumentParser

create_subparser() → argparse._SubParsersAction[argparse.ArgumentParser]

Create configured subparser to add commands.

Returns

Configured argparse’s subparser.

Return type

argparse._SubParsersAction

description: str

epilog: str

get_arguments() → Namespace

Get arguments the script was called with.

Returns

Arguments in argparse’s namespace.

Return type

argparse.Namespace

name: str

parser: ArgumentParser

populate_commands_param_help(commands: Dict[str, Callable[[...], Any]]) → None

Populate commands’ parameters help with docstrings content.

Parameters

commands (Dict[str, Callable[..., Any]]) – Narrowed type self.commands.

subparser: Optional[_SubParsersAction]

version: str

class cly.config.CustomFormatter(*args: Any, **kwargs: Any)

Bases: HelpFormatter

Custom formatter for argparse’s argument parser.

_fill_text(text: str, width: int, indent: str) → str

Format text to fit desired width.

Breaks text in paragraphs so it does not exceed the width limit, respecting indentation.

Parameters

• text (str) – Text to be formatted.

• width (int) – Width limit.

• indent (str) – Indentation.

Returns

Formatted text.

Return type

str

_format_action(action: Action) → str

Remove subparser’s metavar when listing its parsers.

Parameters

action (argparse.Action) – argparse action.

Returns

subparser’s section without metavar.

Return type

str

_format_action_invocation(action: Action) → str

Add metavar only once to arguments.

Parameters

action (argparse.Action) – argparse action.

Returns

How to use option with only one metavar.

Return type

str

_format_usage(usage: Optional[str], actions: Iterable[Action], groups: Iterable[_ArgumentGroup], prefix: Optional[str]) → str

Format prefix of usage section.

Parameters

• usage (Optional[str]) – usage.

• actions (Iterable[argparse.Action]) – argparse actions.

• groups (Iterable[argparse._ArgumentGroup]) – argparse groups.

• prefix (Optional[str]) – usage prefix.

Returns

Formatted usage section.

Return type

str

cly.config.check_python_minimum_version() → None

Check if user Python’s version is valid to running the template.

Raises

SystemExit – If user Python’s version is invalid.

cly.config.decorate_kwargs(func: Callable[[...], Any]) → Callable[[...], Any]

Call decorated function only with it’s key words arguments.

Parameters

func (Callable[..., Any]) – Function to be decorated.

Returns

Decorated function.

Return type

Callable[…, Any]

cly.config.iterate_through_params(commands: Dict[str, Callable[[...], Any]], choices: Dict[str, ArgumentParser]) → None

Iterate through commands’ parameters help with docstrings content.

Parameters

• commands (Dict[str, Callable[..., Any]]) – Narrowed type ConfiguredParser’ commands.

• choices (Dict[str, argparse.ArgumentParser]) – Narrowed type argparse’s choices.

cly.docstring module

Docstring parser.

cly.docstring.get_help_from_docstring(command: Callable[[...], Any]) → str

Get help message from callable object.

Parameters

command (Callable[..., Any]) – Callable object (command, callback, …).

Returns

Docstring summary, if exists.

Return type

str

cly.docstring.get_index_of_sphinx_param_section(docstring_lines: List[str]) → Tuple[int, str]

Get list index of Sphinx parameters section in docstring lines.

Parameters

docstring_lines (List[str]) – Lines of the docstring.

Returns

Index and docstring style.

Return type

Tuple[int, str]

cly.docstring.get_param_help_from_docstring(param_name: str, command: Callable[[...], Any]) → str

Get parameter help message from from callable object’s docstring.

Parameters

• param_name (str) – Parameter name of the command.

• command (Callable[..., Any]) – Callable object (command, callback, …).

Returns

Parameter help message, if any.

Return type

str

cly.docstring.get_param_help_from_google_docstring(docstring_lines: List[str], index_param_section: int, param_name: str) → str

Get parameter help message from Google style docstring.

Parameters

• docstring_lines (List[str]) – Lines of the docstring.

• index_param_section (int) – List index of the parameters section in the lines of the docstring.

• param_name (str) – Name of the parameter.

Returns

Parameter help message, if any.

Return type

str

cly.docstring.get_param_help_from_numpy_docstring(docstring_lines: List[str], index_param_section: int, param_name: str) → str

Get parameter help message from Numpy style docstring.

Parameters

• docstring_lines (List[str]) – Lines of the docstring.

• index_param_section (int) – List index of the parameters section in the lines of the docstring.

• param_name (str) – Name of the parameter.

Returns

Parameter help message, if any.

Return type

str

cly.docstring.get_param_help_from_sphinx_docstring(docstring_lines: List[str], index_param_section: int, param_name: str) → str

Get parameter help message from Sphinx style docstring.

Parameters

• docstring_lines (List[str]) – Lines of the docstring.

• index_param_section (int) – List index of the parameters section in the lines of the docstring.

• param_name (str) – Name of the parameter.

Returns

Parameter help message, if any.

Return type

str

cly.testing module

Testing environment for CLY?! object.

cly.testing.run_cli(cli: ConfiguredParser, arguments: List[str]) → Tuple[int, str, str]

Run CLY?! object with desired arguments and capturing output.

Parameters

• cli (ConfiguredParser) – CLY?! object.

• arguments (List[str]) – Arguments to pass to CLY?! object.

Returns

Tuple with the following elements, in this order

• Exit code

• Standard output (stdout)

• Standard error (stderr)

from CLI?! object execution

Return type

Tuple[int, str, str]

cly.utils module

Utils functions for calling shell.

cly.utils.get_output(arguments: Union[str, List[str]], directory: Optional[Path] = None) → CompletedProcess[str]

Get the output information of the shell command.

Be careful about security implications when manipulating the shell!

Parameters

• arguments (Union[str, List[str]]) – A string, or list of strings, containing the commands and arguments.

• directory (Optional[pathlib.Path]) – Directory to run shell command, by default runs in current directory.

Returns

Command’s output information.

Return type

subprocess.CompletedProcess

cly.utils.get_returncode(arguments: Union[str, List[str]], directory: Optional[Path] = None) → int

Get the returncode of the shell command.

Be careful about security implications when manipulating the shell!

Parameters

• arguments (Union[str, List[str]]) – A string, or list of strings, containing the commands and arguments.

• directory (Optional[pathlib.Path]) – Directory to run shell command, by default runs in current directory.

Returns

Command’s returncode.

Return type

int

cly.utils.get_standard_output(arguments: Union[str, List[str]], lines: bool = False, directory: Optional[Path] = None) → Optional[List[str]]

Get the standard output of the shell command.

Be careful about security implications when manipulating the shell!

Parameters

• arguments (Union[str, List[str]]) – A string, or list of strings, containing the commands and arguments.

• lines (bool) – Separate output in lines instead of separating in words, by default False.

• directory (Optional[pathlib.Path]) – Directory to run shell command, by default runs in current directory.

Returns

output – A list of strings containing the output’s words or lines; else, None.

Return type

Optional[List[str]]

cly.utils.parse_arguments(arguments: Union[str, List[str]]) → str

Parse arguments into a string.

Parameters

arguments (Union[str, List[str]]) – A string, or list of strings, containing the commands and arguments.

Returns

Parsed arguments.

Return type

str

cly.utils.print_error_message(error: CalledProcessError) → None

Print error message from a command.

Parameters

error (subprocess.CalledProcessError) – Error from command.

cly.utils.run_command(arguments: Union[str, List[str]], directory: Optional[Path] = None) → None

Run the shell command.

Be careful about security implications when manipulating the shell!

Parameters

• arguments (Union[str, List[str]]) – A string, or list of strings, containing the commands and arguments.

• directory (Optional[pathlib.Path]) – Directory to run shell command, by default runs in current directory.

Raises

SystemExit – If command fails.

cly.utils.run_multiple_commands(commands: Sequence[Tuple[Union[str, List[str]], Optional[Path]]]) → None

Run multiple shell commands.

Be careful about security implications when manipulating the shell!

Parameters

commands (Sequence[Tuple[Union[str, List[str]], Optional[pathlib.Path]]]) – List of commands, where each command is a tuple of commands and arguments and directory, to be executed.

Raises

SystemExit – If one of the command fails.