Update documentation

ApeWorX · Nov 3, 2023 · dc27c8d · dc27c8d
1 parent 9406089
commit dc27c8d
Show file tree

Hide file tree

Showing 210 changed files with 32,476 additions and 70 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: 1a94eaebab537c2268820cb836f7367a
+config: 8d486467506e05617178b0568f5ca8eb
 tags: 645f666f9bcd5a90fca523b33c5a78b7
diff --git a/stable/.doctrees/commands/console.doctree b/stable/.doctrees/commands/console.doctree
diff --git a/stable/.doctrees/commands/networks.doctree b/stable/.doctrees/commands/networks.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/clis.doctree b/stable/.doctrees/userguides/clis.doctree
diff --git a/stable/.doctrees/userguides/compile.doctree b/stable/.doctrees/userguides/compile.doctree
diff --git a/stable/.doctrees/userguides/dependencies.doctree b/stable/.doctrees/userguides/dependencies.doctree
diff --git a/stable/.doctrees/userguides/networks.doctree b/stable/.doctrees/userguides/networks.doctree
diff --git a/stable/.doctrees/userguides/quickstart.doctree b/stable/.doctrees/userguides/quickstart.doctree
diff --git a/stable/.doctrees/userguides/testing.doctree b/stable/.doctrees/userguides/testing.doctree
diff --git a/stable/_sources/userguides/clis.md.txt b/stable/_sources/userguides/clis.md.txt
@@ -18,7 +18,7 @@ This guide is for showcasing utilities that ship with Ape to assist in your CLI
 
 ## Ape Context Decorator
 
-The `@ape_cli_context` gives you access to all the root Ape objects (`accounts`, `networks` etc.), the ape logger, and an `abort` method for stopping execution of your CLI gracefully.
+The [@ape_cli_context](../methoddocs/cli.html#ape.cli.options.ape_cli_context) gives you access to all the root Ape objects (`accounts`, `networks` etc.), the ape logger, and an [abort](../methoddocs/cli.html#ape.cli.options.ApeCliContextObject.abort) method for stopping execution of your CLI gracefully.
 Here is an example using all of those features from the `cli_ctx`:
 
 ```python
@@ -34,10 +34,37 @@ def cmd(cli_ctx):
     cli_ctx.abort(f"Bad account: {account.address}")
 ```
 
+In Ape, it is easy to extend the CLI context object and use the extended version in your CLIs:
+
+```python
+from ape.cli import ApeCliContextObject, ape_cli_context
+import click
+
+class MyManager:
+   """My custom manager."""
+
+class CustomContext(ApeCliContextObject):
+   """Add new managers to your custom context"""
+   my_manager: MyManager = MyManager()
+
+   @property
+   def signer(self):
+      """Utilize existing managers in your custom context."""
+      return self.account_manager.load("my_account")
+
+@click.command()
+@ape_cli_context(obj_type=CustomContext)
+def cli(cli_ctx):
+    # Access your manager.
+    print(cli_ctx.my_manager)
+    # Access other Ape managers.
+    print(cli_ctx.account_manager)
+```
+
 ## Network Tools
 
-The `@network_option()` allows you to select an ecosystem / network / provider combination.
-When using with the `NetworkBoundCommand` cls, you can cause your CLI to connect before any of your code executes.
+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.
 
 ```python
@@ -62,7 +89,7 @@ def cmd(network):
 
 ## Account Tools
 
-Use the `@account_option()` for adding an option to your CLIs to select an account.
+Use the [@account_option()](../methoddocs/cli.html#ape.cli.options.account_option) for adding an option to your CLIs to select an account.
 This option does several things:
 
 1. If you only have a single account in Ape (from both test accounts _and_ other accounts), it will use that account as the default.
@@ -96,7 +123,7 @@ And when invoking the command from the CLI, it would look like the following:
 <prefix> cmd --account TEST::0  # Use the test account at index 0.
 ```
 
-Alternatively, you can call the `get_user_selected_account()` directly to have more control of when the account gets selected:
+Alternatively, you can call the [get_user_selected_account()](../methoddocs/cli.html#ape.cli.choices.get_user_selected_account) directly to have more control of when the account gets selected:
 
 ```python
 import click
@@ -110,8 +137,8 @@ def cmd():
 ```
 
 Similarly, there are a couple custom arguments for aliases alone that are useful when making CLIs for account creation.
-If you use `@existing_alias_argument()` and specify an alias does not already exist, it will error.
-And visa-versa when using `@non_existing_alias_argument()`
+If you use [@existing_alias_argument()](../methoddocs/cli.html#ape.cli.arguments.existing_alias_argument) and specify an alias does not already exist, it will error.
+And visa-versa when using [@non_existing_alias_argument()](../methoddocs/cli.html#ape.cli.arguments.non_existing_alias_argument).
 
 ```python
 import click
@@ -131,3 +158,31 @@ def create_account(alias):
     # We know the alias is not yet used in Ape at this point.
     click.echo(alias)
 ```
+
+You can control additional filtering of the accounts by using the `account_type` kwarg.
+Use `account_type` to filter the choices by specific types of [AccountAPI](../methoddocs/api.html#ape.api.accounts.AccountAPI), or you can give it a list of already known accounts, or you can provide a callable-filter that takes an account and returns a boolean.
+
+```python
+import click
+from ape import accounts
+from ape.cli import existing_alias_argument, get_user_selected_account
+from ape_accounts.accounts import KeyfileAccount
+
+# NOTE: This is just an example and not anything specific or recommended.
+APPLICATION_PREFIX = "<FOO_BAR>"
+
+@click.command()
+@existing_alias_argument(account_type=KeyfileAccount)
+def cli_0(alias):
+   pass
+
+@click.command()
+@existing_alias_argument(account_type=lambda a: a.alias.startswith(APPLICATION_PREFIX))
+def cli_1(alias):
+   pass
+
+
+# Select from the given accounts directly.
+my_accounts = [accounts.load("me"), accounts.load("me2")]
+selected_account = get_user_selected_account(account_type=my_accounts)
+```
diff --git a/stable/_sources/userguides/compile.md.txt b/stable/_sources/userguides/compile.md.txt
@@ -81,3 +81,55 @@ Alternatively, configure it to always happen:
 compile:
   use_dependencies: true
 ```
+
+## Settings
+
+Generally, configure compiler plugins using your `ape-config.yaml` file.
+For example, when using the `vyper` plugin, you can configure settings under the `vyper` key:
+
+```yaml
+vyper:
+  version: 0.3.10
+```
+
+You can also configure adhoc settings in Python code:
+
+```python
+from pathlib import Path
+from ape import compilers
+
+settings = {"vyper": {"version": "0.3.7"}, "solidity": {"version": "0.8.0"}}
+compilers.compile(
+   ["path/to/contract.vy", "path/to/contract.sol"], settings=settings
+)
+
+# Or, more explicitly:
+vyper = compilers.get_compiler("vyper", settings=settings["vyper"])
+vyper.compile([Path("path/to/contract.vy")])
+
+solidity = compilers.get_compiler("solidity", settings=settings["solidity"])
+vyper.compile([Path("path/to/contract.sol")])
+```
+
+## Compile Source Code
+
+Instead of compiling project source files, you can compile code (str) directly:
+
+```python
+from ape import accounts, compilers
+
+CODE = """
+   ... source code here
+"""
+
+container = compilers.compile_source(
+   "vyper",
+   CODE,
+   settings={"vyper": {"version": "0.3.7"}}, 
+   contractName="MyContract",
+)
+
+owner = accounts.test_accounts[0]
+
+instance = container.deploy(sender=owner)
+```
diff --git a/stable/_sources/userguides/dependencies.md.txt b/stable/_sources/userguides/dependencies.md.txt
@@ -62,6 +62,16 @@ This is helpful when:
 - When there is not a suitable `DependencyAPI` implementation available for downloading your dependency.
 - Testing the framework.
 
+You can also reference local project manifests and use those as dependencies.
+To do this, use a local value pointing to the manifest file, like this:
+
+```yaml
+dependencies:
+  - name: MyDependency
+    local: ./my-dependency.json
+    version: 1.0.0
+```
+
 ### NPM
 
 You can use dependencies from NPM.

diff --git a/stable/_sources/userguides/networks.md.txt b/stable/_sources/userguides/networks.md.txt
@@ -135,3 +135,94 @@ from ape import chain
 
 block = chain.provider.get_block("latest")
 ```
+
+## Provider Context Manager
+
+Use the [ProviderContextManager](../methoddocs/api.html#ape.api.networks.ProviderContextManager) to change the network-context in Python.
+When entering a network for the first time, it will connect to that network.
+**You do not need to call `.connect()` or `.disconnect()` manually**.
+
+For example, if you are using a script with a default network connection, you can change connection in the middle of the script by using the provider context manager:
+
+```python
+from ape import chain, networks
+
+def main():
+    start_provider = chain.provider.name
+    with networks.ethereum.mainnet.use_provider("geth") as provider:
+        # We are using a different provider than the one we started with.
+        assert start_provider != provider.name
+```
+
+Jump between networks to simulate multi-chain behavior.
+
+```python
+import click
+from ape import networks
+
+@click.command()
+def cli():
+    with networks.polygon.mainnet.use_provider("geth"):
+        ...
+    with networks.ethereum.mainnet.use_provider("geth"):
+        ...
+```
+
+The argument to [use_provider()](../methoddocs/api.html#ape.api.networks.NetworkAPI.use_provider) is the name of the provider you want to use.
+You can also tell Ape to use the default provider by calling method [use_default_provider()](../methoddocs/api.html#ape.api.networks.NetworkAPI.use_default_provider) instead.
+This will use whatever provider is set as default for your ecosystem / network combination (via one of your `ape-config.yaml` files).
+
+For example, let's say I have a default provider set like this:
+
+```yaml
+arbitrum:
+  mainnet:
+    default_provider: alchemy
+```
+
+```python
+import ape
+
+# Use the provider configured as the default for the arbitrum::mainnet network.
+# In this case, it will use the "alchemy" provider.
+with ape.networks.arbitrum.mainnet.use_default_provider():
+    ...
+```
+
+You can also use the [parse_network_choice()](../methoddocs/managers.html#ape.managers.networks.NetworkManager.parse_network_choice) method when working with network choice strings:
+
+```python
+from ape import networks
+
+# Same as doing `networks.ethereum.local.use_provider("test")`.
+with networks.parse_network_choice("ethereum:local:test") as provider:
+    print(provider)
+```
+
+**A note about disconnect**: Providers do not disconnect until the very end of your Python session.
+This is so you can easily switch network contexts in a bridge or multi-chain environment, which happens in fixtures and other sessions out of Ape's control.
+However, sometimes you may definitely want your temporary network session to end before continuing, in which case you can use the `disconnect_after=True` kwarg:
+
+```python
+from ape import networks
+
+with networks.parse_network_choice("ethereum:local:foundry", disconnect_after=True) as provider:
+    print(provider)
+```
+
+### Forked Context
+
+Using the `networks.fork()` method, you can achieve similar effects to using a forked network with `disconnect_after=True`.
+For example, let's say we are running the following script on the network `ethereum:mainnet`.
+We can switch to a forked network by doing this:
+
+```python
+from ape import networks
+
+def main():
+    with networks.fork("foundry"):
+        ...
+        # Do stuff on a local, forked version of mainnet
+
+    # Switch back to mainnet.
+```
diff --git a/stable/_sources/userguides/testing.md.txt b/stable/_sources/userguides/testing.md.txt
@@ -47,17 +47,12 @@ To disable isolation add the `--disable-isolation` flag when running `ape test`
 
 ## Fixtures
 
-Fixtures are any type of reusable instances of something with configurable scopes. `pytest` handles passing fixtures
-into each test method as test-time. To learn more about [fixtures](https://docs.pytest.org/en/7.1.x/explanation/fixtures.html)
+You can define and use `pytest` fixtures in your Ape tests.
+Learn more about fixtures from [this guide](https://docs.pytest.org/en/7.1.x/explanation/fixtures.html).
+The syntax and functionalities of fixtures work exactly the same in Ape as it does with `pytest`.
 
-Define fixtures for static data used by tests. This data can be accessed by all tests in the suite unless specified otherwise. This could be data as well as helpers of modules which will be passed to all tests.
-
-A common place to define fixtures are in the **conftest.py** which should be saved under the test directory:
-
-conftest.py is used to import external plugins or modules. By defining the following global variable, pytest will load the module and make it available for its test.
-
-You can define your own fixtures or use existing ones. The `ape-test` plugin comes
-with fixtures you will likely want to use:
+The `ape-test` plugin comes with fixtures you will likely want to use.
+The following guide explains each fixture that comes with Ape.
 
 ### accounts fixture
 

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.6.22">v0.6.22</option>
                 <option value="v0.6.21">v0.6.21</option>
                 <option value="v0.6.20">v0.6.20</option>
                 <option value="v0.6.19">v0.6.19</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.6.22">v0.6.22</option>
                 <option value="v0.6.21">v0.6.21</option>
                 <option value="v0.6.20">v0.6.20</option>
                 <option value="v0.6.19">v0.6.19</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.6.22">v0.6.22</option>
                 <option value="v0.6.21">v0.6.21</option>
                 <option value="v0.6.20">v0.6.20</option>
                 <option value="v0.6.19">v0.6.19</option>
@@ -208,10 +209,10 @@ <h2>console<a class="headerlink" href="#console" title="Permalink to this headin
 <dd><p>Override the default network and provider. (see <cite>ape networks list</cite> for options)</p>
 <dl class="field-list simple">
 <dt class="field-odd">Default<span class="colon">:</span></dt>
-<dd class="field-odd"><p><code class="docutils literal notranslate"><span class="pre">&lt;function</span> <span class="pre">network_option.&lt;locals&gt;.fn</span> <span class="pre">at</span> <span class="pre">0x7f1f6421dcf0&gt;</span></code></p>
+<dd class="field-odd"><p><code class="docutils literal notranslate"><span class="pre">&lt;function</span> <span class="pre">network_option.&lt;locals&gt;.fn</span> <span class="pre">at</span> <span class="pre">0x7f6506e539a0&gt;</span></code></p>
 </dd>
 <dt class="field-even">Options<span class="colon">:</span></dt>
-<dd class="field-even"><p>: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 | ethereum:local:test | ::geth | ethereum:local:geth | :local | ethereum:local | ethereum</p>
+<dd class="field-even"><p>: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</p>
 </dd>
 </dl>
 </dd></dl>

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.6.22">v0.6.22</option>
                 <option value="v0.6.21">v0.6.21</option>
                 <option value="v0.6.20">v0.6.20</option>
                 <option value="v0.6.19">v0.6.19</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.6.22">v0.6.22</option>
                 <option value="v0.6.21">v0.6.21</option>
                 <option value="v0.6.20">v0.6.20</option>
                 <option value="v0.6.19">v0.6.19</option>
@@ -240,7 +241,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>sepolia | goerli-fork | mainnet | sepolia-fork | mainnet-fork | local | goerli</p>
+<dd class="field-odd"><p>sepolia-fork | mainnet-fork | goerli-fork | mainnet | sepolia | local | goerli</p>
 </dd>
 </dl>
 </dd></dl>
@@ -279,7 +280,7 @@ <h2>run<a class="headerlink" href="#networks-run" title="Permalink to this headi
 <dd class="field-odd"><p><code class="docutils literal notranslate"><span class="pre">ethereum:local:geth</span></code></p>
 </dd>
 <dt class="field-even">Options<span class="colon">:</span></dt>
-<dd class="field-even"><p>: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 | ethereum:local:test | ::geth | ethereum:local:geth | :local | ethereum:local | ethereum</p>
+<dd class="field-even"><p>: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</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.6.22">v0.6.22</option>
                 <option value="v0.6.21">v0.6.21</option>
                 <option value="v0.6.20">v0.6.20</option>
                 <option value="v0.6.19">v0.6.19</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.6.22">v0.6.22</option>
                 <option value="v0.6.21">v0.6.21</option>
                 <option value="v0.6.20">v0.6.20</option>
                 <option value="v0.6.19">v0.6.19</option>