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: Optional[Type[ape.api.accounts.AccountAPI]] = 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: Optional[Type[ape.api.accounts.AccountAPI]] = None, prompt_message: Optional[str] = None)

Bases: ape.cli.choices.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

All the account aliases.

Returns

A list of all the account aliases.

Return type

List[str]

convert(value: Any, param: Optional[click.core.Parameter], ctx: Optional[click.core.Context])Optional[ape.api.accounts.AccountAPI]

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()ape.api.accounts.AccountAPI

Returns the selected account.

Returns

AccountAPI

class ape.cli.choices.Alias(account_type: Optional[Type[ape.api.accounts.AccountAPI]] = None)

Bases: click.types.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

The aliases available to choose from.

Returns

A list of account aliases the user may choose from.

Return type

List[str]

class ape.cli.choices.NetworkChoice(case_sensitive=True)

Bases: click.types.Choice

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

get_metavar(param)

Returns the metavar default for this param if it provides one.

class ape.cli.choices.OutputFormat(value)

Bases: enum.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)

Bases: click.types.ParamType

A choice option or argument from user selection.

convert(value: Any, param: Optional[click.core.Parameter], ctx: Optional[click.core.Context])Optional[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.

print_choices()

Echo the choices to the terminal.

ape.cli.choices.get_user_selected_account(account_type: Optional[Type[ape.api.accounts.AccountAPI]] = None, prompt_message: Optional[str] = None)ape.api.accounts.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_that_prompts_when_not_given().

Parameters
  • account_type (type[AccountAPI], optional) – If given, the user may only select an account of this type.

  • prompt_message (str, optional) – Customize the prompt message.

Returns

AccountAPI

ape.cli.choices.output_format_choice(options: Optional[List[ape.cli.choices.OutputFormat]] = None)click.types.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: Optional[str], context_settings: Optional[Dict[str, Any]] = None, callback: Optional[Callable[[], Any]] = None, params: Optional[List[click.core.Parameter]] = None, help: Optional[str] = None, epilog: Optional[str] = None, short_help: Optional[str] = None, options_metavar: Optional[str] = '[OPTIONS]', add_help_option: bool = True, no_args_is_help: bool = False, hidden: bool = False, deprecated: bool = False)

Bases: click.core.Command

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

invoke(ctx: click.core.Context)Any

Given a context, this invokes the attached callback (if it exists) in the right way.

Options

class ape.cli.options.ApeCliContextObject

Bases: object

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: Optional[Exception] = None)

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.

property project

A class representing the project that is active at runtime. (This is the same object as from from ape import project).

Returns

ProjectManager

ape.cli.options.account_option_that_prompts_when_not_given()

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()

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

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.network_option(default: Optional[str] = None)

A click.option for specifying a network.

Parameters

default (str) – Optionally, change which network to use as the default. Defaults to how ape normally selects a default network.

ape.cli.options.output_format_option(default: ape.cli.choices.OutputFormat = <OutputFormat.TREE: '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)

A decorator that adds a –verbosity, -v option to the decorated command.

Parameter Types

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

Bases: ape.cli.paramtype.Path

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

convert(value: Any, param: Optional[click.core.Parameter], ctx: Optional[click.core.Context])List[pathlib.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: click.types.Path

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

Utilities

exception ape.cli.utils.Abort(message)

Bases: click.exceptions.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.