Console

Ape provides an IPython interactive console with useful pre-defined locals to interact with your project.

ape console --network ethereum:mainnet

In [1]: chain.blocks.head.timestamp
Out[1]: 1647323479

Warning

Contract changes are not reflected in the active console session. If you need to make changes to your contract, you must re-start your console session for the compiler to handle the changes.

Ape Namespace

Your console comes with pre-initialized root ape objects in your namespace.

Name	Class
`accounts`	AccountManager
`networks`	NetworkManager
`chain`	ChainManager
`project`	ProjectManager
`query`	QueryManager
`convert`	convert
`ape`	ape

You can access them as if they are already initialized:

First, launch the console:

ape console

Then, type the name of the item and you will see its Python representation:

In [1]: networks
Out[1]: <NetworkManager active_provider=<test chain_id=61>>

Note

To change the network of the active console, use the --network option.

Follow this guide for more information on networks in Ape.

Namespace Extras

You can also create scripts to be included in the console namespace by adding a file (ape_console_extras.py) to your root project directory. All non-internal symbols from this file will be included in the console namespace. Internal symbols are prefixed by an underscore (_).

An example file might look something like this:

from ape import networks
from eth_utils import encode_hex, decode_hex

def latest(key):
    return getattr(networks.active_provider.get_block("latest"), key)

Then both imported util functions and latest() will be available when you launch the console.

In [1]: latest('number')
Out[1]: 14388241

In [2]: encode_hex(latest('hash'))
Out[2]: '0x68f768988e9bd4be971d527f72483f321975fa52aff9692b6d0e0af71fb77aaf'

Init Function

If you include a function named ape_init_extras, it will be executed with the symbols from the existing namespace being provided as keyword arguments. This allows you to alter the scripts namespace using locals already included in the Ape namespace. If you return a dict, these values will be added to the console namespace. For example, you could set up an initialized Web3.py object by using one from an existing Ape Provider.

def ape_init_extras(chain):
    return {"web3": chain.provider.web3}

Then web3 will be available to use immediately.

In [1]: web3.eth.chain_id
Out[1]: 1

Global Extras

You can also add an ape_console_extras.py file to the global ape data directory ($HOME/.ape/ape_console_extras.py) and it will execute regardless of what project context you are in. This may be useful for variables and utility functions you use across all of your projects.

Configure

To automatically use other IPython extensions, add them to your ape-config.yaml file:

console:
  plugins:
    # A plugin that lets you modify Python modules without having close/reopen your console.
    - autoreload

Magic Commands

The ape-console plugin ships with custom magics that are available when running the ape console command or loading the ape_console.plugin IPython extension manually. When starting an embedded console (from -I in ape run or ape test), you will have to load the extension manually. To do this, run the following from any IPython environment:

In [1]: %load_ext ape_console.plugin

Or add the ape_console.plugin extension to your IPython config.

Otherwise, when launching ape console, the magics are automatically available.

%ape

The %ape magic invokes the CLI in your ape-console session:

In [1]: %ape
Usage: cli [OPTIONS] COMMAND [ARGS]...

Options:
  -v, --verbosity LVL  One of ERROR, WARNING, SUCCESS, INFO, or DEBUG
  --version            Show the version and exit.
  --config             Show configuration options (using `ape-config.yaml`)
  -h, --help           Show this message and exit.

Commands:
  accounts  Manage local accounts
  cache     Query from caching database
  compile   Compile select contract source files
  console   Load the console
  init      Initialize an ape project
  networks  Manage networks
  plugins   Manage ape plugins
  run       Run scripts from the `scripts/` folder
  test      Launches pytest and runs the tests for a project

Out[1]: <Result okay>

Run any CLI command this way without exiting your session.

%bal

The %bal magic outputs a human-readable balance on an account, contract, address, or account alias.

In [1]: account = accounts.load("metamask0")

In [2]: %bal account
Out[2]: '0.00040634 ETH'

In [3]: %bal metamask0
Out[3]: '0.00040634 ETH'

In [4]: %bal 0xE3747e6341E0d3430e6Ea9e2346cdDCc2F8a4b5b
Out[4]: '0.00040634 ETH'

Executing Code

You can also use the ape console to execute programs directly from strings. This is similar to the python -c|--code option except it will display the output cell. Anything available in ape console is also available in ape console --code.

ape console -c 'project.name'
Out[1]: 'my-project'
ape console -c 'x = 3\nx + 1'
Out[1]: 4
ape console -c 'networks.active_provider.name'
Out[1]: 'test'