diff --git a/latest/.buildinfo b/latest/.buildinfo index ffd4cbb018..d5eb87dfb5 100644 --- a/latest/.buildinfo +++ b/latest/.buildinfo @@ -1,4 +1,4 @@ # Sphinx build info version 1 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. -config: f3023e2797f9cc61efdeb5e7ee9293c8 +config: 2ec3a14ed9d76d18ce50b44f21cf234a tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/latest/.doctrees/commands/console.doctree b/latest/.doctrees/commands/console.doctree index 7295056c34..a0134f955f 100644 Binary files a/latest/.doctrees/commands/console.doctree and b/latest/.doctrees/commands/console.doctree differ diff --git a/latest/.doctrees/commands/networks.doctree b/latest/.doctrees/commands/networks.doctree index 110ebe2768..0f8e5cc5e0 100644 Binary files a/latest/.doctrees/commands/networks.doctree and b/latest/.doctrees/commands/networks.doctree differ diff --git a/latest/.doctrees/environment.pickle b/latest/.doctrees/environment.pickle index a30addf0fd..a74a503fc9 100644 Binary files a/latest/.doctrees/environment.pickle and b/latest/.doctrees/environment.pickle differ diff --git a/latest/.doctrees/methoddocs/ape.doctree b/latest/.doctrees/methoddocs/ape.doctree index 3959daa222..1cf1ac7300 100644 Binary files a/latest/.doctrees/methoddocs/ape.doctree and b/latest/.doctrees/methoddocs/ape.doctree differ diff --git a/latest/.doctrees/methoddocs/api.doctree b/latest/.doctrees/methoddocs/api.doctree index d49960abe4..27d5308744 100644 Binary files a/latest/.doctrees/methoddocs/api.doctree and b/latest/.doctrees/methoddocs/api.doctree differ diff --git a/latest/.doctrees/methoddocs/cli.doctree b/latest/.doctrees/methoddocs/cli.doctree index 65e5735d3a..204b14118b 100644 Binary files a/latest/.doctrees/methoddocs/cli.doctree and b/latest/.doctrees/methoddocs/cli.doctree differ diff --git a/latest/.doctrees/methoddocs/contracts.doctree b/latest/.doctrees/methoddocs/contracts.doctree index b7196a91b4..e1b5df7945 100644 Binary files a/latest/.doctrees/methoddocs/contracts.doctree and b/latest/.doctrees/methoddocs/contracts.doctree differ diff --git a/latest/.doctrees/methoddocs/exceptions.doctree b/latest/.doctrees/methoddocs/exceptions.doctree index f19c527a2d..0869f85dc0 100644 Binary files a/latest/.doctrees/methoddocs/exceptions.doctree and b/latest/.doctrees/methoddocs/exceptions.doctree differ diff --git a/latest/.doctrees/methoddocs/managers.doctree b/latest/.doctrees/methoddocs/managers.doctree index 2c2c9b3d6e..f52cb72d26 100644 Binary files a/latest/.doctrees/methoddocs/managers.doctree and b/latest/.doctrees/methoddocs/managers.doctree differ diff --git a/latest/.doctrees/methoddocs/plugins.doctree b/latest/.doctrees/methoddocs/plugins.doctree index 02921bb060..2a9be18ae8 100644 Binary files a/latest/.doctrees/methoddocs/plugins.doctree and b/latest/.doctrees/methoddocs/plugins.doctree differ diff --git a/latest/.doctrees/methoddocs/types.doctree b/latest/.doctrees/methoddocs/types.doctree index f8501f0a85..4dec28ca40 100644 Binary files a/latest/.doctrees/methoddocs/types.doctree and b/latest/.doctrees/methoddocs/types.doctree differ diff --git a/latest/.doctrees/methoddocs/utils.doctree b/latest/.doctrees/methoddocs/utils.doctree index f653bb238d..807b5211e4 100644 Binary files a/latest/.doctrees/methoddocs/utils.doctree and b/latest/.doctrees/methoddocs/utils.doctree differ diff --git a/latest/.doctrees/userguides/clis.doctree b/latest/.doctrees/userguides/clis.doctree index ff2af0a4b2..bc80b70f5f 100644 Binary files a/latest/.doctrees/userguides/clis.doctree and b/latest/.doctrees/userguides/clis.doctree differ diff --git a/latest/.doctrees/userguides/networks.doctree b/latest/.doctrees/userguides/networks.doctree index d33e73453e..1559aa7264 100644 Binary files a/latest/.doctrees/userguides/networks.doctree and b/latest/.doctrees/userguides/networks.doctree differ diff --git a/latest/.doctrees/userguides/scripts.doctree b/latest/.doctrees/userguides/scripts.doctree index 9e20b0d90f..5c703ca219 100644 Binary files a/latest/.doctrees/userguides/scripts.doctree and b/latest/.doctrees/userguides/scripts.doctree differ diff --git a/latest/_sources/userguides/clis.md.txt b/latest/_sources/userguides/clis.md.txt index 09c63ffc99..395a9f6fe6 100644 --- a/latest/_sources/userguides/clis.md.txt +++ b/latest/_sources/userguides/clis.md.txt @@ -63,28 +63,60 @@ def cli(cli_ctx): ## Network Tools -The [@network_option()](../methoddocs/cli.html#ape.cli.options.network_option) allows you to select an ecosystem / network / provider combination. -When using with the [NetworkBoundCommand](../methoddocs/cli.html#ape.cli.commands.NetworkBoundCommand) class, you can cause your CLI to connect before any of your code executes. -This is useful if your script or command requires a provider connection in order for it to run. +The [@network_option()](../methoddocs/cli.html#ape.cli.options.network_option) allows you to select an ecosystem, network, and provider. +To specify the network option, use values like: + +```shell +--network ethereum +--network ethereum:sepolia +--network ethereum:mainnet:alchemy +--network ::foundry +``` + +To use default values automatically, omit sections of the choice, but leave the semi-colons for parsing. +For example, `::test` means use the default ecosystem and network and the `test` provider. + +Use `ecosystem`, `network`, and `provider` argument names in your command implementation to access their corresponding class instances: ```python import click -from ape import networks -from ape.cli import network_option, NetworkBoundCommand +from ape.cli import network_option +@click.command() +@network_option() +def cmd(provider): + # This command only needs the provider. + click.echo(provider.name) @click.command() @network_option() -def cmd(network): - # Choices like "ethereum" or "polygon:local:test". - click.echo(network) +def cmd_2(ecosystem, network, provider): + # This command uses all parts of the parsed network choice. + click.echo(ecosystem.name) + click.echo(network.name) + click.echo(provider.name) +``` +The [ConnectedProviderCommand](../methoddocs/cli.html#ape.cli.commands.ConnectedProviderCommand) automatically uses the `--network` option and connects to the network before any of your code executes and then disconnects afterward. +This is useful if your script or command requires a provider connection in order for it to run. +Additionally, specify `ecosystem`, `network`, or `provider` in your command function if you need any of those instances in your `ConnectedProviderCommand`, just like when using `network_option`. -@click.command(cls=NetworkBoundCommand) -@network_option() -def cmd(network): - # Fails if we are not connected. - click.echo(networks.provider.network.name) +```python +import click +from ape.cli import ConnectedProviderCommand + +@click.command(cls=ConnectedProviderCommand) +def cmd(network, provider): + click.echo(network.name) + click.echo(provider.is_connected) # True + +@click.command(cls=ConnectedProviderCommand) +def cmd(provider): + click.echo(provider.is_connected) # True + +@click.command(cls=ConnectedProviderCommand) +def cmd(): + click.echo("Using params is from ConnectedProviderCommand is optional") ``` ## Account Tools diff --git a/latest/_sources/userguides/networks.md.txt b/latest/_sources/userguides/networks.md.txt index 6e5b949834..4a554cd5b0 100644 --- a/latest/_sources/userguides/networks.md.txt +++ b/latest/_sources/userguides/networks.md.txt @@ -12,7 +12,7 @@ ape test --network ethereum:local:foundry ape console --network arbitrum:testnet:alchemy ``` -You can also use the `--network` option on scripts that use the `main()` method approach or scripts that implement that `NetworkBoundCommand` command type. +You can also use the `--network` option on scripts that use the `main()` method approach or scripts that implement that `ConnectedProviderCommand` command type. See [the scripting guide](./scripts.html) to learn more about scripts and how to add the network option. **NOTE**: You can omit values to use defaults. @@ -85,9 +85,9 @@ geth: uri: https://foo.node.bar ``` -## Ad-hoc Network Connection +## Custom Network Connection -If you would like to connect to a URI using the `geth` provider, you can specify a URI for the provider name in the `--network` option: +If you would like to connect to a URI using the default Ethereum node provider, you can specify a URI for the provider name in the `--network` option: ```bash ape run script --network ethereum:mainnet:https://foo.bar diff --git a/latest/_sources/userguides/scripts.md.txt b/latest/_sources/userguides/scripts.md.txt index 28fc79b27e..ffb363c47e 100644 --- a/latest/_sources/userguides/scripts.md.txt +++ b/latest/_sources/userguides/scripts.md.txt @@ -33,17 +33,25 @@ ape run hello helloworld ``` Note that by default, `cli` scripts do not have [`ape.cli.network_option`](../methoddocs/cli.html?highlight=options#ape.cli.options.network_option) installed, giving you more flexibility in how you define your scripts. -However, you can add the `network_option` to your scripts by importing both the `NetworkBoundCommand` and the `network_option` from the `ape.cli` namespace: +However, you can add the `network_option` or `ConnectedProviderCommand` to your scripts by importing them from the `ape.cli` namespace: ```python import click -from ape.cli import network_option, NetworkBoundCommand +from ape.cli import network_option, ConnectedProviderCommand -@click.command(cls=NetworkBoundCommand) -@network_option() -def cli(network): - click.echo(f"You are connected to network '{network}'.") +@click.command(cls=ConnectedProviderCommand) +def cli(ecosystem, network): + click(f"You selected a provider on ecosystem '{ecosystem.name}' and {network.name}.") + +@click.command(cls=ConnectedProviderCommand) +def cli(network, provider): + click.echo(f"You are connected to network '{network.name}'.") + click.echo(provider.chain_id) + +@click.command(cls=ConnectedProviderCommand) +def cli_2(): + click.echo(f"Using any network-based argument is completely optional.") ``` Assume we saved this script as `shownet.py` and have the [ape-alchemy](https://github.com/ApeWorX/ape-alchemy) plugin installed. diff --git a/latest/commands/console.html b/latest/commands/console.html index fb6f4c28c4..46a46c7437 100644 --- a/latest/commands/console.html +++ b/latest/commands/console.html @@ -208,20 +208,6 @@
Override the default network and provider. (see ape networks list for options)
-<function network_option.<locals>.fn at 0x7efd865197e0>
:mainnet:geth | ethereum:mainnet:geth | :mainnet | ethereum:mainnet | :goerli:geth | ethereum:goerli:geth | :goerli | ethereum:goerli | :sepolia:geth | ethereum:sepolia:geth | :sepolia | ethereum:sepolia | ::test | :local:test | ethereum::test | ethereum:local:test | ::geth | :local:geth | ethereum::geth | ethereum:local:geth | :local | ethereum:local | ethereum
-goerli-fork | goerli | sepolia-fork | local | mainnet-fork | sepolia | mainnet
+mainnet-fork | goerli-fork | mainnet | sepolia | goerli | sepolia-fork | local
Start a node process
+partial(func, *args, **keywords) - new function with partial application +of the given arguments and keywords.
networks run [OPTIONS]
Override the default network and provider. (see ape networks list for options)
-ethereum:local:geth
:mainnet:geth | ethereum:mainnet:geth | :mainnet | ethereum:mainnet | :goerli:geth | ethereum:goerli:geth | :goerli | ethereum:goerli | :sepolia:geth | ethereum:sepolia:geth | :sepolia | ethereum:sepolia | ::test | :local:test | ethereum::test | ethereum:local:test | ::geth | :local:geth | ethereum::geth | ethereum:local:geth | :local | ethereum:local | ethereum
-EcosystemAPI.decode_logs()
EcosystemAPI.decode_receipt()
EcosystemAPI.decode_returndata()
EcosystemAPI.default_network
EcosystemAPI.default_network_name
EcosystemAPI.encode_address()
EcosystemAPI.encode_calldata()
EcosystemAPI.encode_deployment()
NetworkAPI.chain_id
NetworkAPI.config
NetworkAPI.data_folder
NetworkAPI.default_provider
NetworkAPI.default_provider_name
NetworkAPI.ecosystem
NetworkAPI.explorer
NetworkAPI.get_provider()
The name of the default network in this ecosystem.
The name of the default provider or None
.
Use and connect to a provider in a temporary context. When entering the context, it calls
method ape.api.providers.ProviderAPI.connect()
and when exiting, it calls
method ape.api.providers.ProviderAPI.disconnect()
.
provider_name (str) – The name of the provider to use.
provider (str) – The provider instance or the name of the provider to use.
provider_settings (dict, optional) – Settings to apply to the provider.
+Defaults to None
.
disconnect_after (bool) – Set to True
to force a disconnect after ending
the context. This defaults to False
so you can re-connect to the
same network, such as in a multi-chain testing scenario.
provider_settings (dict, optional) – Settings to apply to the provider.
-Defaults to None
.
disconnect_on_exit (bool) – Whether to disconnect on the exit of the python
+session. Defaults to True
.
PromptChoice.print_choices()
get_user_selected_account()
output_format_choice()
select_account()
NetworkBoundCommand
ApeCliContextObject.abort()
NetworkOption
account_option()
ape_cli_context()
contract_option()
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 @@ -488,6 +492,12 @@
DEPRECATED: Use select_account()
instead.
Bases: Command
A command that uses the network_option()
.
It will automatically set the network for the duration of the command execution.
Given a context, this invokes the attached callback (if it exists) in the right way.
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()
.
Bases: ConnectedProviderCommand
Bases: Option
The class used in :meth:~ape.cli.options.network_option.
+Create an ad-hoc connection to a URI using the GethProvider core plugin. +
Create a custom connection to a URI using the EthereumNodeProvider provider. NOTE: This provider will assume EVM-like behavior and this is generally not recommended. Use plugins when possible!
uri (str) – The URI of the node.
+connection_str (str) – The connection string of the node, such as its URI +when using HTTP.
provider_cls (Type[ProviderAPI
]) – Defaults to
+EthereumNodeProvider
.
provider_name (Optional[str]) – The name of the provider. Defaults to best guess.
disconnect_after (bool) – Set to True to terminate the connection completely at the end of context. NOTE: May only work if the network was also started from this session.
disconnect_on_exit (bool) – Whether to disconnect on the exit of the python
+session. Defaults to True
.
The @network_option() allows you to select an ecosystem / network / provider combination. -When using with the NetworkBoundCommand class, you can cause your CLI to connect before any of your code executes. -This is useful if your script or command requires a provider connection in order for it to run.
+The @network_option() allows you to select an ecosystem, network, and provider. +To specify the network option, use values like:
+--network ethereum
+--network ethereum:sepolia
+--network ethereum:mainnet:alchemy
+--network ::foundry
+
To use default values automatically, omit sections of the choice, but leave the semi-colons for parsing.
+For example, ::test
means use the default ecosystem and network and the test
provider.
Use ecosystem
, network
, and provider
argument names in your command implementation to access their corresponding class instances:
import click
-from ape import networks
-from ape.cli import network_option, NetworkBoundCommand
+from ape.cli import network_option
+@click.command()
+@network_option()
+def cmd(provider):
+ # This command only needs the provider.
+ click.echo(provider.name)
@click.command()
@network_option()
-def cmd(network):
- # Choices like "ethereum" or "polygon:local:test".
- click.echo(network)
+def cmd_2(ecosystem, network, provider):
+ # This command uses all parts of the parsed network choice.
+ click.echo(ecosystem.name)
+ click.echo(network.name)
+ click.echo(provider.name)
+
The ConnectedProviderCommand automatically uses the --network
option and connects to the network before any of your code executes and then disconnects afterward.
+This is useful if your script or command requires a provider connection in order for it to run.
+Additionally, specify ecosystem
, network
, or provider
in your command function if you need any of those instances in your ConnectedProviderCommand
, just like when using network_option
.
import click
+from ape.cli import ConnectedProviderCommand
+@click.command(cls=ConnectedProviderCommand)
+def cmd(network, provider):
+ click.echo(network.name)
+ click.echo(provider.is_connected) # True
-@click.command(cls=NetworkBoundCommand)
-@network_option()
-def cmd(network):
- # Fails if we are not connected.
- click.echo(networks.provider.network.name)
+@click.command(cls=ConnectedProviderCommand)
+def cmd(provider):
+ click.echo(provider.is_connected) # True
+
+@click.command(cls=ConnectedProviderCommand)
+def cmd():
+ click.echo("Using params is from ConnectedProviderCommand is optional")
You can also use the --network
option on scripts that use the main()
method approach or scripts that implement that NetworkBoundCommand
command type.
+
You can also use the --network
option on scripts that use the main()
method approach or scripts that implement that ConnectedProviderCommand
command type.
See the scripting guide to learn more about scripts and how to add the network option.
NOTE: You can omit values to use defaults.
For example, the default ecosystem is ethereum
and the default network is local
, so you can do:
If you would like to connect to a URI using the geth
provider, you can specify a URI for the provider name in the --network
option:
If you would like to connect to a URI using the default Ethereum node provider, you can specify a URI for the provider name in the --network
option:
ape run script --network ethereum:mainnet:https://foo.bar
ape.cli.network_option
installed, giving you more flexibility in how you define your scripts.
-However, you can add the network_option
to your scripts by importing both the NetworkBoundCommand
and the network_option
from the ape.cli
namespace:
+However, you can add the network_option
or ConnectedProviderCommand
to your scripts by importing them from the ape.cli
namespace:
import click
-from ape.cli import network_option, NetworkBoundCommand
+from ape.cli import network_option, ConnectedProviderCommand
-@click.command(cls=NetworkBoundCommand)
-@network_option()
-def cli(network):
- click.echo(f"You are connected to network '{network}'.")
+@click.command(cls=ConnectedProviderCommand)
+def cli(ecosystem, network):
+ click(f"You selected a provider on ecosystem '{ecosystem.name}' and {network.name}.")
+
+@click.command(cls=ConnectedProviderCommand)
+def cli(network, provider):
+ click.echo(f"You are connected to network '{network.name}'.")
+ click.echo(provider.chain_id)
+
+@click.command(cls=ConnectedProviderCommand)
+def cli_2():
+ click.echo(f"Using any network-based argument is completely optional.")
Assume we saved this script as shownet.py
and have the ape-alchemy plugin installed.