class ape.utils.AbstractDataClassMeta(name, bases, dict_, **kwargs)

Bases: dataclassy.dataclass.DataClassMeta, abc.ABCMeta

A data class that is also abstract (meaning it has methods that must be implemented in a sub-class or else errors will occur). This class cannot be instantiated on its own.

class ape.utils.GeneratedDevAccount(address, private_key)

Bases: tuple

An account key-pair generated from the test mnemonic. Set the test mnemonic in your ape-config.yaml file under the test section. Access your test accounts using the test_accounts property.

Config example:

  mnemonic: test test test test test test test test test test test junk
  number_of_accounts: 10

Alias for field number 0


Alias for field number 1

ape.utils.abstractdataclass(cls: Optional[type] = None, *, meta=<class 'ape.utils.AbstractDataClassMeta'>, **options)Type[Any]

A data class that is also abstract (meaning it has methods that must be implemented or else errors will occur. This class cannot be instantiated on its own.

ape.utils.deep_merge(dict1, dict2)Dict

Merge two dictionaries recursively.


The result of the merge as a new dictionary.

Return type


ape.utils.expand_environment_variables(contents: str)str

Replace substrings of the form $name or ${name} in the given path with the value of environment variable name.


contents (str) – A path-like object representing a file system. A path-like object is either a string or bytes object representing a path.


The given content with all environment variables replaced with their values.

Return type


ape.utils.extract_nested_value(root: Mapping, *args: str)Optional[Dict]

Dig through a nested dict using the given keys and return the last-found object.

Usage example:

>>> extract_nested_value({"foo": {"bar": {"test": "VALUE"}}}, "foo", "bar", "test")

root (dict) – Nested keys to form arguments.


The final value if it exists else None if the tree ends at any point.

Return type

dict, optional

ape.utils.gas_estimation_error_message(tx_error: Exception)str

Get an error message containing the given error and an explanation of how the gas estimation failed, as in ape.api.providers.ProviderAPI implementations.


tx_error (Exception) – The error that occurred when trying to estimate gas.


An error message explaining that the gas failed and that the transaction will likely revert.

Return type


ape.utils.generate_dev_accounts(mnemonic: str, number_of_accounts: int = 10, hd_path_format="m/44'/60'/0'/{}")List[ape.utils.GeneratedDevAccount]

Create accounts from the given test mnemonic. Use these accounts (or the mnemonic) in chain-genesis for testing providers.

  • mnemonic (str) – mnemonic phrase or seed words.

  • number_of_accounts (int) – Number of accounts. Defaults to 10.

  • hd_path_format (str) – Hard Wallets/HD Keys derivation path format. Defaults to "m/44'/60'/0'/{}".


List of development accounts.

Return type


ape.utils.get_all_files_in_directory(path: pathlib.Path)List[pathlib.Path]

Returns all the files in a directory structure.

For example, given a directory structure like:

dir_a: dir_b, file_a, file_b
dir_b: file_c

and you provide the path to dir_a, it will return a list containing the paths to file_a, file_b and file_c.


path (pathlib.Path) – A directory containing files of interest.


A list of files in the given directory.

Return type


ape.utils.get_package_version(obj: Any)str

Get the version of a single package.


obj – object to search inside for __version__.


version string.

Return type


ape.utils.get_relative_path(target: pathlib.Path, anchor: pathlib.Path)pathlib.Path

Compute the relative path of target relative to anchor, which may or may not share a common ancestor. NOTE: Both paths must be absolute.

  • target (pathlib.Path) – The path we are interested in.

  • anchor (pathlib.Path) – The path we are starting from.


The new path to the target path from the anchor path.

Return type


ape.utils.load_config(path: pathlib.Path, expand_envars=True, must_exist=False)Dict

Load a configuration file into memory. A file at the given path must exist or else it will throw OSError. The configuration file must be a .json or .yaml or else it will throw TypeError.

  • path (str) – path to filesystem to find.

  • expand_envars (bool) – True the variables in path are able to expand to show full path.

  • must_exist (bool) – True will be set if the configuration file exist and is able to be load.


Configured settings parsed from a config file.

Return type

Dict (dict)

class ape.utils.singledispatchmethod(func)

Bases: object

Single-dispatch generic method descriptor.

Supports wrapping existing descriptors and handles non-descriptor callables as instance methods.

register(cls, func)func

Registers a new implementation for the given cls on a generic_method.