Update documentation

ApeWorX · Jan 23, 2024 · 38f5789 · 38f5789
1 parent 3b5153e
commit 38f5789
Show file tree

Hide file tree

Showing 203 changed files with 34,410 additions and 18 deletions.
diff --git a/stable/.buildinfo b/stable/.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: 65d73da52d5ef675e18029111232e5b6
+config: 60db2b9bdc92843939bc2f12445a1cfa
 tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/stable/.doctrees/commands/networks.doctree b/stable/.doctrees/commands/networks.doctree
diff --git a/stable/.doctrees/commands/run.doctree b/stable/.doctrees/commands/run.doctree
diff --git a/stable/.doctrees/environment.pickle b/stable/.doctrees/environment.pickle
diff --git a/stable/.doctrees/methoddocs/ape.doctree b/stable/.doctrees/methoddocs/ape.doctree
diff --git a/stable/.doctrees/methoddocs/api.doctree b/stable/.doctrees/methoddocs/api.doctree
diff --git a/stable/.doctrees/methoddocs/cli.doctree b/stable/.doctrees/methoddocs/cli.doctree
diff --git a/stable/.doctrees/methoddocs/contracts.doctree b/stable/.doctrees/methoddocs/contracts.doctree
diff --git a/stable/.doctrees/methoddocs/exceptions.doctree b/stable/.doctrees/methoddocs/exceptions.doctree
diff --git a/stable/.doctrees/methoddocs/managers.doctree b/stable/.doctrees/methoddocs/managers.doctree
diff --git a/stable/.doctrees/methoddocs/plugins.doctree b/stable/.doctrees/methoddocs/plugins.doctree
diff --git a/stable/.doctrees/methoddocs/types.doctree b/stable/.doctrees/methoddocs/types.doctree
diff --git a/stable/.doctrees/methoddocs/utils.doctree b/stable/.doctrees/methoddocs/utils.doctree
diff --git a/stable/.doctrees/userguides/contracts.doctree b/stable/.doctrees/userguides/contracts.doctree
diff --git a/stable/.doctrees/userguides/scripts.doctree b/stable/.doctrees/userguides/scripts.doctree
diff --git a/stable/_sources/userguides/contracts.md.txt b/stable/_sources/userguides/contracts.md.txt
@@ -362,6 +362,32 @@ bytes_value = contract.encode_input(0, 1, 2, 4, 5)
 method_id, input_dict = contract.decode_input(bytes_value)
 ```
 
+## Contract Interface Introspection
+
+There may be times you need to figure out ABI selectors and method or event identifiers for a contract.
+A contract instance provides properties to make this easy.
+For instance, if you have a 4-byte hex method ID, you can return the ABI type for that method:
+
+```python
+import ape
+
+usdc = ape.Contract("0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48")
+
+# ABI type for a hex method ID
+assert usdc.identifier_lookup['0x70a08231'].selector == 'balanceOf(address)'
+
+# Also, selectors from method and event signatures
+assert usdc.selector_identifiers["balances(address)"] == "0x27e235e3"
+
+# Or dump all selectors and IDs
+for identifier, abi_type in usdc.identifier_lookup.items():
+    print(identifier, abi_type)
+    # 0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef type='event' name='Transfer' inputs=...
+    # ...
+```
+
+These include methods and error IDs, as well as event topics.
+
 ## Multi-Call and Multi-Transaction
 
 The `ape_ethereum` core plugin comes with a `multicall` module containing tools for interacting with the [multicall3 smart contract](https://github.com/mds1/multicall).

diff --git a/stable/_sources/userguides/scripts.md.txt b/stable/_sources/userguides/scripts.md.txt
@@ -32,12 +32,12 @@ For example, assuming we have script `<project>/scripts/hello/helloworld.py`, we
 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.
+**Note**: 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` or `ConnectedProviderCommand` to your scripts by importing them from the `ape.cli` namespace:
 
 ```python
 import click
-from ape.cli import network_option, ConnectedProviderCommand
+from ape.cli import ConnectedProviderCommand
 
 
 @click.command(cls=ConnectedProviderCommand)
@@ -61,6 +61,45 @@ Try changing the network using the `--network` option:
 ape run shownet --network ethereum:mainnet:alchemy
 ```
 
+### Multi-network Scripting
+
+Because CLI-based scripts do not automatically connect to the provider before executing, they are ideal for multi-chain use-cases because they allow you to delay and manage the connection(s).
+To learn more about how to control the network-context in Ape Pythonically, see [this guide](https://docs.apeworx.io/ape/stable/userguides/networks.html#provider-context-manager).
+
+Here is an example of a multi-chain script:
+
+```python
+import click
+from ape.cli import ape_cli_context
+
+@click.command()
+@ape_cli_context()
+def cli(cli_ctx):        
+    # There is no connection yet at this point.
+    testnets = {
+        "ethereum": ["sepolia", "goerli"],
+        "polygon": ["mumbai"]
+    }
+    nm = cli_ctx.network_manager
+
+    for ecosystem_name, networks in testnets.items():
+        ecosystem = nm.ecosystems[ecosystem_name]
+
+        for network_name in networks:
+            # Start making connections.
+            network = ecosystem.get_network(network_name)
+
+            with network.use_provider("alchemy") as provider:
+                print(f"Connected to {provider.network_choice}")
+```
+
+Things to notice:
+
+1. It uses the CLI approach _without_ `cls=ConnectedProviderCommand`; thus it is not connected before it makes the first call to `.use_provider("alchemy")`.
+2. It uses the `@ape_cli_context()` decorator to get access to Ape instances such as the `network_manager`.
+3. Each network is only active during the context, thus allowing you to switch contexts and control chain-hopping in scripts.
+4. **You do not need to call `.connect()` on the provider yourself!**
+
 ## Main Method Scripts
 
 You can also use the main-method approach when defining scripts.
@@ -71,18 +110,35 @@ def main():
     print("Hello world!")
 ```
 
-**NOTE**: main-method scripts will always provide a network option to the call and thus will always connect to a network.
+**NOTE**: main-method scripts will always provide a `--network` option and run in a connected-context.
+Therefore, they are not ideal for multi-chain scripts.
+`main`-method scripts work best for quick, single-network, connection-based workflows.
 
 To demonstrate, use the following script:
 
 ```python
 from ape import networks
 import click
 
-
 def main():
     ecosystem_name = networks.provider.network.ecosystem.name
     network_name = networks.provider.network.name
     provider_name = networks.provider.name
     click.echo(f"You are connected to network '{ecosystem_name}:{network_name}:{provider_name}'.")
 ```
+
+Suppose the name of the script is `foobar`, you can run it via:
+
+```shell
+ape run foobar
+```
+
+Without specifying `--network`, the script with connect to your default network.
+Else, specify the network using the `--network` flag:
+
+```shell
+ape run foobar --network polygon:mumbai:alchemy
+```
+
+You can also change networks within the script using the `ProviderContextManager` (see examples in the CLI-script section above).
+For multi-chain use-cases, we recommend sticking to the CLI based scripts to avoid the initial connection `main`-method scripts make.
diff --git a/stable/commands/accounts.html b/stable/commands/accounts.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
                 <option value="v0.7.3">v0.7.3</option>
                 <option value="v0.7.2">v0.7.2</option>

diff --git a/stable/commands/compile.html b/stable/commands/compile.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
                 <option value="v0.7.3">v0.7.3</option>
                 <option value="v0.7.2">v0.7.2</option>

diff --git a/stable/commands/console.html b/stable/commands/console.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
                 <option value="v0.7.3">v0.7.3</option>
                 <option value="v0.7.2">v0.7.2</option>

diff --git a/stable/commands/init.html b/stable/commands/init.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
                 <option value="v0.7.3">v0.7.3</option>
                 <option value="v0.7.2">v0.7.2</option>

diff --git a/stable/commands/networks.html b/stable/commands/networks.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
                 <option value="v0.7.3">v0.7.3</option>
                 <option value="v0.7.2">v0.7.2</option>
@@ -251,7 +252,7 @@ <h2>list<a class="headerlink" href="#networks-list" title="Permalink to this hea
 <dd><p>Filter the results by network</p>
 <dl class="field-list simple">
 <dt class="field-odd">Options<span class="colon">:</span></dt>
-<dd class="field-odd"><p>local | mainnet-fork | sepolia | mainnet | goerli-fork | sepolia-fork | goerli</p>
+<dd class="field-odd"><p>sepolia-fork | mainnet-fork | sepolia | mainnet | local | goerli | goerli-fork</p>
 </dd>
 </dl>
 </dd></dl>
@@ -262,7 +263,7 @@ <h2>list<a class="headerlink" href="#networks-list" title="Permalink to this hea
 <dd><p>Filter the results by provider</p>
 <dl class="field-list simple">
 <dt class="field-odd">Options<span class="colon">:</span></dt>
-<dd class="field-odd"><p>test | geth</p>
+<dd class="field-odd"><p>geth | test</p>
 </dd>
 </dl>
 </dd></dl>

diff --git a/stable/commands/plugins.html b/stable/commands/plugins.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
                 <option value="v0.7.3">v0.7.3</option>
                 <option value="v0.7.2">v0.7.2</option>

diff --git a/stable/commands/pm.html b/stable/commands/pm.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
                 <option value="v0.7.3">v0.7.3</option>
                 <option value="v0.7.2">v0.7.2</option>

diff --git a/stable/commands/run.html b/stable/commands/run.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
                 <option value="v0.7.3">v0.7.3</option>
                 <option value="v0.7.2">v0.7.2</option>
@@ -162,7 +163,10 @@
 <li class="toctree-l1"><a class="reference internal" href="networks.html">networks</a></li>
 <li class="toctree-l1"><a class="reference internal" href="plugins.html">plugins</a></li>
 <li class="toctree-l1 current"><a class="current reference internal" href="#">run</a><ul>
-<li class="toctree-l2"><a class="reference internal" href="#run">run</a></li>
+<li class="toctree-l2"><a class="reference internal" href="#run">run</a><ul>
+<li class="toctree-l3"><a class="reference internal" href="#run-update-rpc">update_rpc</a></li>
+</ul>
+</li>
 </ul>
 </li>
 <li class="toctree-l1"><a class="reference internal" href="test.html">test</a></li>
@@ -223,6 +227,20 @@ <h2>run<a class="headerlink" href="#run" title="Permalink to this heading"></
 <dd><p>Drop into interactive console session after running</p>
 </dd></dl>
 
+<section id="run-update-rpc">
+<h3>update_rpc<a class="headerlink" href="#run-update-rpc" title="Permalink to this heading"></a></h3>
+<p>Run ‘scripts/update_rpc.py:main’</p>
+<div class="highlight-shell notranslate"><div class="highlight"><pre><span></span>run<span class="w"> </span>update_rpc<span class="w"> </span><span class="o">[</span>OPTIONS<span class="o">]</span>
+</pre></div>
+</div>
+<p class="rubric">Options</p>
+<dl class="std option">
+<dt class="sig sig-object std" id="cmdoption-run-update_rpc-v">
+<span id="cmdoption-run-update-rpc-v"></span><span id="cmdoption-run-update_rpc-verbosity"></span><span id="cmdoption-run-update-rpc-verbosity"></span><span class="sig-name descname"><span class="pre">-v</span></span><span class="sig-prename descclassname"></span><span class="sig-prename descclassname"><span class="pre">,</span> </span><span class="sig-name descname"><span class="pre">--verbosity</span></span><span class="sig-prename descclassname"> <span class="pre">&lt;LVL&gt;</span></span><a class="headerlink" href="#cmdoption-run-update_rpc-v" title="Permalink to this definition"></a></dt>
+<dd><p>One of ERROR, WARNING, SUCCESS, INFO, or DEBUG</p>
+</dd></dl>
+
+</section>
 </section>
 </section>
 

diff --git a/stable/commands/test.html b/stable/commands/test.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
                 <option value="v0.7.3">v0.7.3</option>
                 <option value="v0.7.2">v0.7.2</option>

diff --git a/stable/genindex.html b/stable/genindex.html
@@ -47,6 +47,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
                 <option value="v0.7.3">v0.7.3</option>
                 <option value="v0.7.2">v0.7.2</option>
@@ -395,6 +396,8 @@ <h2 id="Symbols">Symbols</h2>
         <li><a href="commands/pm.html#cmdoption-pm-list-v">pm-list command line option</a>
 </li>
         <li><a href="commands/pm.html#cmdoption-pm-remove-v">pm-remove command line option</a>
+</li>
+        <li><a href="commands/run.html#cmdoption-run-update_rpc-v">run-update_rpc command line option</a>
 </li>
         <li><a href="commands/test.html#cmdoption-test-v">test command line option</a>
 </li>
@@ -527,6 +530,8 @@ <h2 id="Symbols">Symbols</h2>
         <li><a href="commands/pm.html#cmdoption-pm-list-v">pm-list command line option</a>
 </li>
         <li><a href="commands/pm.html#cmdoption-pm-remove-v">pm-remove command line option</a>
+</li>
+        <li><a href="commands/run.html#cmdoption-run-update_rpc-v">run-update_rpc command line option</a>
 </li>
         <li><a href="commands/test.html#cmdoption-test-v">test command line option</a>
 </li>
@@ -1872,6 +1877,8 @@ <h2 id="H">H</h2>
 <h2 id="I">I</h2>
 <table style="width: 100%" class="indextable genindextable"><tr>
   <td style="width: 33%; vertical-align: top;"><ul>
+      <li><a href="methoddocs/contracts.html#ape.contracts.base.ContractTypeWrapper.identifier_lookup">identifier_lookup (ape.contracts.base.ContractTypeWrapper property)</a>
+</li>
       <li><a href="methoddocs/api.html#ape.api.accounts.ImpersonatedAccount">ImpersonatedAccount (class in ape.api.accounts)</a>
 </li>
       <li><a href="methoddocs/types.html#ape.types.coverage.ContractSourceCoverage.include">include() (ape.types.coverage.ContractSourceCoverage method)</a>
@@ -1917,6 +1924,8 @@ <h2 id="I">I</h2>
 </li>
       <li><a href="methoddocs/api.html#ape.api.address.BaseAddress.is_contract">is_contract (ape.api.address.BaseAddress property)</a>
 </li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="methoddocs/api.html#ape.api.convert.ConverterAPI.is_convertible">is_convertible() (ape.api.convert.ConverterAPI method)</a>
 
       <ul>
@@ -1939,8 +1948,6 @@ <h2 id="I">I</h2>
         <li><a href="methoddocs/managers.html#ape.managers.converters.TimestampConverter.is_convertible">(ape.managers.converters.TimestampConverter method)</a>
 </li>
       </ul></li>
-  </ul></td>
-  <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="methoddocs/api.html#ape.api.networks.NetworkAPI.is_dev">is_dev (ape.api.networks.NetworkAPI property)</a>
 </li>
       <li><a href="methoddocs/utils.html#ape.utils.is_evm_precompile">is_evm_precompile() (in module ape.utils)</a>
@@ -2669,8 +2676,6 @@ <h2 id="R">R</h2>
 </li>
       <li><a href="methoddocs/api.html#ape.api.accounts.AccountContainerAPI.remove">remove() (ape.api.accounts.AccountContainerAPI method)</a>
 </li>
-  </ul></td>
-  <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="methoddocs/api.html#ape.api.projects.ProjectAPI.replace_manifest">replace_manifest() (ape.api.projects.ProjectAPI method)</a>
 </li>
       <li><a href="methoddocs/api.html#ape.api.networks.EcosystemAPI.request_header">request_header (ape.api.networks.EcosystemAPI attribute)</a>
@@ -2681,6 +2686,8 @@ <h2 id="R">R</h2>
         <li><a href="methoddocs/api.html#ape.api.providers.ProviderAPI.request_header">(ape.api.providers.ProviderAPI attribute)</a>
 </li>
       </ul></li>
+  </ul></td>
+  <td style="width: 33%; vertical-align: top;"><ul>
       <li><a href="methoddocs/api.html#ape.api.networks.NetworkAPI.required_confirmations">required_confirmations (ape.api.networks.NetworkAPI property)</a>
 </li>
       <li><a href="methoddocs/managers.html#ape.managers.chain.ChainManager.restore">restore() (ape.managers.chain.ChainManager method)</a>
@@ -2708,6 +2715,15 @@ <h2 id="R">R</h2>
         <li><a href="commands/run.html#cmdoption-run-I">--interactive</a>
 </li>
         <li><a href="commands/run.html#cmdoption-run-I">-I</a>
+</li>
+      </ul></li>
+      <li>
+    run-update_rpc command line option
+
+      <ul>
+        <li><a href="commands/run.html#cmdoption-run-update_rpc-v">--verbosity</a>
+</li>
+        <li><a href="commands/run.html#cmdoption-run-update_rpc-v">-v</a>
 </li>
       </ul></li>
       <li><a href="methoddocs/utils.html#ape.utils.run_until_complete">run_until_complete() (in module ape.utils)</a>
@@ -2726,6 +2742,8 @@ <h2 id="S">S</h2>
         <li><a href="methoddocs/cli.html#ape.cli.choices.select_account">(in module ape.cli.choices)</a>
 </li>
       </ul></li>
+      <li><a href="methoddocs/contracts.html#ape.contracts.base.ContractTypeWrapper.selector_identifiers">selector_identifiers (ape.contracts.base.ContractTypeWrapper property)</a>
+</li>
       <li><a href="methoddocs/api.html#ape.api.providers.ProviderAPI.send_call">send_call() (ape.api.providers.ProviderAPI method)</a>
 </li>
       <li><a href="methoddocs/api.html#ape.api.providers.ProviderAPI.send_private_transaction">send_private_transaction() (ape.api.providers.ProviderAPI method)</a>

diff --git a/stable/index.html b/stable/index.html
@@ -49,6 +49,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
                 <option value="v0.7.3">v0.7.3</option>
                 <option value="v0.7.2">v0.7.2</option>

diff --git a/stable/methoddocs/ape.html b/stable/methoddocs/ape.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
                 <option value="v0.7.3">v0.7.3</option>
                 <option value="v0.7.2">v0.7.2</option>

diff --git a/stable/methoddocs/api.html b/stable/methoddocs/api.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
                 <option value="v0.7.3">v0.7.3</option>
                 <option value="v0.7.2">v0.7.2</option>

diff --git a/stable/methoddocs/cli.html b/stable/methoddocs/cli.html
@@ -50,6 +50,7 @@
               <option value="">Select version...</option>
               <option value="latest">latest</option>
               <option value="stable">stable</option>
+                <option value="v0.7.5">v0.7.5</option>
                 <option value="v0.7.4">v0.7.4</option>
                 <option value="v0.7.3">v0.7.3</option>
                 <option value="v0.7.2">v0.7.2</option>