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: List[str]

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: List[str]

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, ecosystem: Optional[Union[List[str], str]] = None, network: Optional[Union[List[str], str]] = None, provider: Optional[Union[List[str], str]] = None)

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

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

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: ape.utils.basemodel.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: 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.

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

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.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):
    ....
ape.cli.options.network_option(default: Optional[str] = None, ecosystem: Optional[Union[List[str], str]] = None, network: Optional[Union[List[str], str]] = None, provider: Optional[Union[List[str], str]] = None)

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.

  • 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.

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

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

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.