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: None | Sequence[AccountAPI] | type[AccountAPI] | Callable[[AccountAPI], bool] = None, **kwargs)

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.

  • **kwargs – click.argument overrides.

ape.cli.arguments.non_existing_alias_argument(**kwargs)

A click.argument for an account alias that does not yet exist in ape.

Parameters:

**kwargs – click.argument overrides.

Choices

class ape.cli.choices.AccountAliasPromptChoice(key: None | Sequence[AccountAPI] | type[AccountAPI] | Callable[[AccountAPI], bool] = 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.

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.

print_choices()

Echo the choices to the terminal.

select_account() → AccountAPI

Returns the selected account.

Returns:

AccountAPI

class ape.cli.choices.Alias(key: None | Sequence[AccountAPI] | type[AccountAPI] | Callable[[AccountAPI], bool] = 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().

name: str = 'alias'

the descriptive name of this type

class ape.cli.choices.LazyChoice(get_choices: Callable[[], Sequence[str]], case_sensitive: bool = False)

Bases: Choice

A simple lazy-choice where choices are evaluated lazily.

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, base_type: type | None = None, callback: Callable | 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: Sequence[str], 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.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

ape.cli.choices.select_account(prompt_message: str | None = None, key: None | Sequence[AccountAPI] | type[AccountAPI] | Callable[[AccountAPI], bool] = 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.

  • key (Union[None, type[AccountAPI], Callable[[AccountAPI], bool]]) – If given, the user may only select a matching account. You can provide a list of accounts, an account class type, or a callable for filtering the accounts.

Returns:

AccountAPI

Commands

class ape.cli.commands.ConnectedProviderCommand(*args, **kwargs)

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.

parse_args(ctx: Context, args: list[str]) → list[str]

Given a context and a list of arguments this creates the parser and parses the arguments, then modifies the context as necessary. This is automatically invoked by make_context().

Options

class ape.cli.options.ApeCliContextObject

Bases: dict

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.

class ape.cli.options.NetworkOption(*args, **kwargs)

Bases: Option

The class used in :meth:~ape.cli.options.network_option.

ape.cli.options.account_option(account_type: None | Sequence[AccountAPI] | type[AccountAPI] | Callable[[AccountAPI], bool] = None) → Callable

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 | int | ~ape.logging.LogLevel | None = None, obj_type: type = <class 'ape.cli.options.ApeCliContextObject'>) → Callable

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 | int | LogLevel | None) – The log-level value to pass to verbosity_option().

  • obj_type (Type) – The context object type. Defaults to ApeCliContextObject. Sub-class the context to extend its functionality in your CLIs, such as if you want to add additional manager classes to the context.

Returns:

click option

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

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

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

ape.cli.options.incompatible_with(incompatible_opts) → type[Option]

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: str | Callable | None = 'auto', ecosystem: list[str] | str | None = None, network: list[str] | str | None = None, provider: list[str] | str | None = None, required: bool = False, **kwargs) → Callable

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) → Callable

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='') → Callable

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 | int | LogLevel | None = None, callback: Callable | None = None, **kwargs) → Callable

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

Parameters:

  • cli_logger (ApeLogger | None) – Optionally pass a custom logger object.

  • default (str | int | LogLevel) – The default log-level for this command.

  • callback (Callable | None) – A callback handler for passed-in verbosity values.

  • **kwargs – Additional click overrides.

Returns:

click option

Parameter Types

class ape.cli.paramtype.JSON

Bases: ParamType

A type that accepts a raw-JSON str and loads it into a dictionary.

convert(value, param, ctx)

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

Bases: ParamType

A param-type for ignoring param-types. Good to use when the multi-type handling happens already in a callback or in the command itself.

convert(value: Any, param, ctx) → 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.

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

Bases: Path

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