ape.cli

The ape.cli namespace is a collection of click extensions and reusable implementations, such as common arguments / options for accounts, project file-paths, and generic utilities. Use these resources in plugins as well as in CLI-based scripts.

Arguments

ape.cli.arguments.contract_file_paths_argument()

A click.argument representing contract source file paths. This argument takes 0-to-many values.

The return type from the callback is a flattened list of source file-paths.

ape.cli.arguments.existing_alias_argument(account_type: Type[AccountAPI] | None = None)

A click.argument for an existing account alias.

Parameters:: account_type (Type[AccountAPI], optional) – If given, limits the type of account the user may choose from.

ape.cli.arguments.non_existing_alias_argument(): A click.argument for an account alias that does not yet exist in ape.

Choices

class ape.cli.choices.AccountAliasPromptChoice(account_type: Type[AccountAPI] | None = None, prompt_message: str | None = None, name: str = 'account')

Bases: PromptChoice

Prompts the user to select an alias from their accounts. Useful for adhoc scripts to lessen the need to hard-code aliases.

property choices: List[str]

All the account aliases.

Returns:: A list of all the account aliases.
Return type:: List[str]

convert(value: Any, param: Parameter | None, ctx: Context | None) → AccountAPI | None

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters:

value – The value to convert.
param – The parameter that is using this type to convert its value. May be None.
ctx – The current context that arrived at this value. May be None.

get_user_selected_account() → AccountAPI

Returns the selected account.

Returns:: AccountAPI

print_choices(): Echo the choices to the terminal.

class ape.cli.choices.Alias(account_type: Type[AccountAPI] | None = None)

Bases: Choice

A click.Choice for loading account aliases for the active project at runtime.

Provide an account_type to limit the type of account to choose from. Defaults to all account types in choices().

property choices: List[str]

The aliases available to choose from.

Returns:: A list of account aliases the user may choose from.
Return type:: List[str]

name: str = 'alias': the descriptive name of this type

class ape.cli.choices.NetworkChoice(case_sensitive=True, ecosystem: List[str] | str | None = None, network: List[str] | str | None = None, provider: List[str] | str | None = None)

Bases: Choice

A click.Choice to provide network choice defaults for the active project.

Optionally provide a list of ecosystem names, network names, or provider names to filter the results by.

This is used in network_option().

convert(value: Any, param: Parameter | None, ctx: Context | None) → Any

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters:

value – The value to convert.
param – The parameter that is using this type to convert its value. May be None.
ctx – The current context that arrived at this value. May be None.

get_metavar(param): Returns the metavar default for this param if it provides one.

class ape.cli.choices.OutputFormat(value)

Bases: Enum

An enum representing output formats, such as TREE or YAML. Use this to select a subset of common output formats to use when creating a output_format_choice().

TREE = 'TREE': A rich text tree view of the data.

YAML = 'YAML': A standard .yaml format of the data.

class ape.cli.choices.PromptChoice(choices, name: str | None = None)

Bases: ParamType

A choice option or argument from user selection.

Usage example:

def choice_callback(ctx, param, value):
    return param.type.get_user_selected_choice()

@click.command()
@click.option(
    "--choice",
    type=PromptChoice(["foo", "bar"]),
    callback=choice_callback,
)
def cmd(choice):
    click.echo(f"__expected_{choice}")

convert(value: Any, param: Parameter | None, ctx: Context | None) → Any | None

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters:

value – The value to convert.
param – The parameter that is using this type to convert its value. May be None.
ctx – The current context that arrived at this value. May be None.

print_choices(): Echo the choices to the terminal.

ape.cli.choices.get_user_selected_account(prompt_message: str | None = None, account_type: Type[AccountAPI] | None = None) → AccountAPI

Prompt the user to pick from their accounts and return that account. Use this method if you want to prompt users to select accounts _outside_ of CLI options. For CLI options, use account_option().

Parameters:

prompt_message (Optional[str]) – Customize the prompt message.
account_type (Optional[Type[AccountAPI]]]) – If given, the user may only select an account of this type.

Returns:

AccountAPI

ape.cli.choices.output_format_choice(options: List[OutputFormat] | None = None) → Choice

Returns a click.Choice() type for the given options.

Parameters:: options (List[OutputFormat], optional) – Limit the formats to accept. Defaults to allowing all formats.
Returns:: click.Choice

Commands

class ape.cli.commands.NetworkBoundCommand(name: str | None, context_settings: MutableMapping[str, Any] | None = None, callback: Callable[[...], Any] | None = None, params: List[Parameter] | None = None, help: str | None = None, epilog: str | None = None, short_help: str | None = None, options_metavar: str | None = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False)

Bases: Command

A command that uses the network_option(). It will automatically set the network for the duration of the command execution.

invoke(ctx: Context) → Any: Given a context, this invokes the attached callback (if it exists) in the right way.

Options

class ape.cli.options.ApeCliContextObject

Bases: ManagerAccessMixin

A click context object class. Use via ape_cli_context(). It provides common CLI utilities for ape, such as logging or access to the managers.

static abort(msg: str, base_error: Exception | None = None) → NoReturn

End execution of the current command invocation.

Parameters:

msg (str) – A message to output to the terminal.
base_error (Exception, optional) – Optionally provide an error to preserve the exception stack.

ape.cli.options.account_option(): A CLI option that accepts either the account alias or the account number. If not given anything, it will prompt the user to select an account.

ape.cli.options.ape_cli_context(default_log_level: str = 'INFO')

A click context object with helpful utilities. Use in your commands to get access to common utility features, such as logging or accessing managers.

Parameters:: default_log_level (str) – The log-level value to pass to verbosity_option().

ape.cli.options.contract_option(help=None, required=False, multiple=False)

Contract(s) from the current project. If you pass multiple=True, you will get a list of contract types from the callback.

Raises:: ContractError – In the callback when it fails to load the contracts.

ape.cli.options.incompatible_with(incompatible_opts)

Factory for creating custom click.Option subclasses that enforce incompatibility with the option strings passed to this function.

Usage example:

import click

@click.command()
@click.option("--option", cls=incompatible_with(["other_option"]))
def cmd(option, other_option):
    ....

A click.option for specifying a network.

Parameters:

default (Optional[str]) – Optionally, change which network to use as the default. Defaults to how ape normally selects a default network unless required=True, then defaults to None.
ecosystem (Optional[Union[List[str], str]]) – Filter the options by ecosystem. Defaults to getting all ecosystems.
network (Optional[Union[List[str], str]]) – Filter the options by network. Defaults to getting all networks in ecosystems.
provider (Optional[Union[List[str], str]]) – Filter the options by provider. Defaults to getting all providers in networks.
required (bool) – Whether the option is required. Defaults to False. When set to True, the default value is None.
kwargs – Additional overrides to click.option.

ape.cli.options.output_format_option(default: OutputFormat = OutputFormat.TREE)

A click.option for specifying a format to use when outputting data.

Parameters:: default (OutputFormat) – Defaults to TREE format.

ape.cli.options.skip_confirmation_option(help='')

A click.option for skipping confirmation (--yes).

Parameters:: help (str) – CLI option help text. Defaults to "".

ape.cli.options.verbosity_option(cli_logger: ApeLogger | None = None, default: str = 'INFO'): A decorator that adds a –verbosity, -v option to the decorated command.

Parameter Types

class ape.cli.paramtype.AllFilePaths(*args, **kwargs)

Bases: Path

Either all the file paths in the given directory, or a list containing only the given file.

convert(value: Any, param: Parameter | None, ctx: Context | None) → List[Path]

Convert the value to the correct type. This is not called if the value is None (the missing value).

This must accept string values from the command line, as well as values that are already the correct type. It may also convert other compatible types.

The param and ctx arguments may be None in certain situations, such as when converting prompt input.

If the value cannot be converted, call fail() with a descriptive message.

Parameters:

value – The value to convert.
param – The parameter that is using this type to convert its value. May be None.
ctx – The current context that arrived at this value. May be None.

class ape.cli.paramtype.Path(*args, **kwargs)

Bases: Path

This class exists to encourage the consistent usage of pathlib.Path for path_type.

Utilities

exception ape.cli.utils.Abort(message: str | None = None)

Bases: ClickException

A wrapper around a CLI exception. When you raise this error, the error is nicely printed to the terminal. This is useful for all user-facing errors.

show(file=None): Override default show to print CLI errors in red text.