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
andctx
arguments may beNone
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:
- 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 inchoices()
.- 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
andctx
arguments may beNone
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
orYAML
. Use this to select a subset of common output formats to use when creating aoutput_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
andctx
arguments may beNone
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:
- 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 viaape_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): ....
- ape.cli.options.network_option(default: str | None = 'auto', ecosystem: List[str] | str | None = None, network: List[str] | str | None = None, provider: List[str] | str | None = None, required: bool = False, **kwargs)
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 unlessrequired=True
, then defaults toNone
.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 toTrue
, the default value isNone
.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 toTREE
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
andctx
arguments may beNone
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.