Update documentation

ApeWorX · Dec 10, 2024 · 5cbce7a · 5cbce7a
1 parent dc732a1
commit 5cbce7a
Show file tree

Hide file tree

Showing 242 changed files with 49,129 additions and 142 deletions.
diff --git a/index.html b/index.html
@@ -2,4 +2,4 @@
 <!DOCTYPE html>
 <meta charset="utf-8">
 <title>Redirecting...</title>
-<meta http-equiv="refresh" content="0; URL=./latest/userguides/quickstart.html">
+<meta http-equiv="refresh" content="0; URL=./stable/userguides/quickstart.html">
diff --git a/latest/.doctrees/commands/networks.doctree b/latest/.doctrees/commands/networks.doctree
diff --git a/latest/.doctrees/environment.pickle b/latest/.doctrees/environment.pickle
diff --git a/latest/.doctrees/methoddocs/ape.doctree b/latest/.doctrees/methoddocs/ape.doctree
diff --git a/latest/.doctrees/methoddocs/ape_accounts.doctree b/latest/.doctrees/methoddocs/ape_accounts.doctree
diff --git a/latest/.doctrees/methoddocs/ape_compile.doctree b/latest/.doctrees/methoddocs/ape_compile.doctree
diff --git a/latest/.doctrees/methoddocs/ape_ethereum.doctree b/latest/.doctrees/methoddocs/ape_ethereum.doctree
diff --git a/latest/.doctrees/methoddocs/ape_node.doctree b/latest/.doctrees/methoddocs/ape_node.doctree
diff --git a/latest/.doctrees/methoddocs/ape_pm.doctree b/latest/.doctrees/methoddocs/ape_pm.doctree
diff --git a/latest/.doctrees/methoddocs/ape_test.doctree b/latest/.doctrees/methoddocs/ape_test.doctree
diff --git a/latest/.doctrees/methoddocs/api.doctree b/latest/.doctrees/methoddocs/api.doctree
diff --git a/latest/.doctrees/methoddocs/cli.doctree b/latest/.doctrees/methoddocs/cli.doctree
diff --git a/latest/.doctrees/methoddocs/contracts.doctree b/latest/.doctrees/methoddocs/contracts.doctree
diff --git a/latest/.doctrees/methoddocs/exceptions.doctree b/latest/.doctrees/methoddocs/exceptions.doctree
diff --git a/latest/.doctrees/methoddocs/managers.doctree b/latest/.doctrees/methoddocs/managers.doctree
diff --git a/latest/.doctrees/methoddocs/plugins.doctree b/latest/.doctrees/methoddocs/plugins.doctree
diff --git a/latest/.doctrees/methoddocs/types.doctree b/latest/.doctrees/methoddocs/types.doctree
diff --git a/latest/.doctrees/methoddocs/utils.doctree b/latest/.doctrees/methoddocs/utils.doctree
diff --git a/latest/commands/networks.html b/latest/commands/networks.html
@@ -193,7 +193,7 @@ <h2>list<a class="headerlink" href="#networks-list" title="Link to this heading"
 <dd><p>Filter the results by ecosystem</p>
 <dl class="field-list simple">
 <dt class="field-odd">Options<span class="colon">:</span></dt>
-<dd class="field-odd"><p>zksync | bsc | moonbeam | blast | bttc | apechain | xai | crossfi | rootstock | base | polygon | avalanche | unichain | gnosis | polynomial | shape | xmtp | abstract | geist | palm | cronos-zkevm | oort | zetachain | zora | linea | lens | soneium | world-chain | ethereum | astar | shibarium | taiko | celo | berachain | scroll | optimism | cronos | arbitrum | fantom | lumia | metis | mantle | flow-evm | wemix | kroma | fraxtal | polygon-zkevm</p>
+<dd class="field-odd"><p>mantle | polygon-zkevm | ethereum | taiko | gnosis | zksync | apechain | berachain | palm | lumia | metis | moonbeam | polygon | blast | wemix | zetachain | cronos | scroll | lens | cronos-zkevm | base | xai | abstract | avalanche | celo | polynomial | geist | crossfi | bttc | unichain | zora | shape | world-chain | astar | fraxtal | arbitrum | kroma | rootstock | fantom | optimism | oort | shibarium | flow-evm | linea | bsc | soneium | xmtp</p>
 </dd>
 </dl>
 </dd></dl>
@@ -204,7 +204,7 @@ <h2>list<a class="headerlink" href="#networks-list" title="Link to this heading"
 <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>polter | moonriver-fork | bartio-fork | holesky-fork | puppynet-fork | testnet-fork | dev | bartio | curtis-fork | moonbase | testnet | sepolia-fork | chiado-fork | curtis | minato | chiado | goerli | mumbai-fork | sepolia | hekla-fork | cardona-fork | prism-fork | mumbai | local | amoy | cardona | alfajores | opbnb-testnet | nova-fork | fuji | fuji-fork | dev-fork | moonbase-fork | opbnb-fork | donau-fork | hekla | donau | goerli-fork | mainnet | opbnb | puppynet | polter-fork | prism | nova | moonriver | holesky | minato-fork | alfajores-fork | opbnb-testnet-fork | amoy-fork | mainnet-fork</p>
+<dd class="field-odd"><p>curtis | goerli-fork | polter-fork | mumbai | chiado | hekla | alfajores-fork | opbnb-testnet-fork | amoy | puppynet-fork | bartio | fuji-fork | testnet | testnet-fork | fuji | prism-fork | holesky-fork | dev | moonriver | opbnb | moonbase-fork | opbnb-testnet | minato | nova | holesky | hekla-fork | local | cardona | moonriver-fork | moonbase | alfajores | polter | bartio-fork | opbnb-fork | chiado-fork | nova-fork | prism | donau | puppynet | minato-fork | cardona-fork | amoy-fork | dev-fork | sepolia-fork | mumbai-fork | mainnet-fork | curtis-fork | donau-fork | sepolia | goerli | mainnet</p>
 </dd>
 </dl>
 </dd></dl>
@@ -215,7 +215,7 @@ <h2>list<a class="headerlink" href="#networks-list" title="Link to this heading"
 <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>node | test</p>
+<dd class="field-odd"><p>test | node</p>
 </dd>
 </dl>
 </dd></dl>

diff --git a/latest/methoddocs/ape_node.html b/latest/methoddocs/ape_node.html
diff --git a/latest/searchindex.js b/latest/searchindex.js
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/ape_accounts.doctree b/stable/.doctrees/methoddocs/ape_accounts.doctree
diff --git a/stable/.doctrees/methoddocs/ape_compile.doctree b/stable/.doctrees/methoddocs/ape_compile.doctree
diff --git a/stable/.doctrees/methoddocs/ape_ethereum.doctree b/stable/.doctrees/methoddocs/ape_ethereum.doctree
diff --git a/stable/.doctrees/methoddocs/ape_node.doctree b/stable/.doctrees/methoddocs/ape_node.doctree
diff --git a/stable/.doctrees/methoddocs/ape_pm.doctree b/stable/.doctrees/methoddocs/ape_pm.doctree
diff --git a/stable/.doctrees/methoddocs/ape_test.doctree b/stable/.doctrees/methoddocs/ape_test.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/compile.doctree b/stable/.doctrees/userguides/compile.doctree
diff --git a/stable/.doctrees/userguides/contracts.doctree b/stable/.doctrees/userguides/contracts.doctree
diff --git a/stable/.doctrees/userguides/quickstart.doctree b/stable/.doctrees/userguides/quickstart.doctree
diff --git a/stable/.doctrees/userguides/scripts.doctree b/stable/.doctrees/userguides/scripts.doctree
diff --git a/stable/.doctrees/userguides/testing.doctree b/stable/.doctrees/userguides/testing.doctree
diff --git a/stable/_sources/methoddocs/ape_accounts.md.txt b/stable/_sources/methoddocs/ape_accounts.md.txt
@@ -1,6 +1,6 @@
 # ape-accounts
 
 ```{eval-rst}
-.. automodule:: ape_accounts
+.. automodule:: ape_accounts.accounts
     :members:
 ```
diff --git a/stable/_sources/methoddocs/ape_compile.md.txt b/stable/_sources/methoddocs/ape_compile.md.txt
@@ -1,6 +1,6 @@
 # ape-compile
 
 ```{eval-rst}
-.. automodule:: ape_compile
+.. automodule:: ape_compile.config
     :members:
 ```
diff --git a/stable/_sources/methoddocs/ape_ethereum.md.txt b/stable/_sources/methoddocs/ape_ethereum.md.txt
@@ -1,7 +1,27 @@
 # ape-ethereum
 
 ```{eval-rst}
-.. automodule:: ape_ethereum
+.. automodule:: ape_ethereum.ecosystem
+    :members:
+```
+
+```{eval-rst}
+.. automodule:: ape_ethereum.provider
+    :members:
+```
+
+```{eval-rst}
+.. automodule:: ape_ethereum.proxies
+    :members:
+```
+
+```{eval-rst}
+.. automodule:: ape_ethereum.trace
+    :members:
+```
+
+```{eval-rst}
+.. automodule:: ape_ethereum.transactions
     :members:
 ```
 

diff --git a/stable/_sources/methoddocs/ape_node.md.txt b/stable/_sources/methoddocs/ape_node.md.txt
@@ -1,6 +1,6 @@
 # ape-node
 
 ```{eval-rst}
-.. automodule:: ape_node
+.. automodule:: ape_node.provider
     :members:
 ```
diff --git a/stable/_sources/methoddocs/ape_pm.md.txt b/stable/_sources/methoddocs/ape_pm.md.txt
@@ -1,6 +1,16 @@
 # ape-pm
 
 ```{eval-rst}
-.. automodule:: ape_pm
+.. automodule:: ape_pm.compiler
+    :members:
+```
+
+```{eval-rst}
+.. automodule:: ape_pm.dependency
+    :members:
+```
+
+```{eval-rst}
+.. automodule:: ape_pm.project
     :members:
 ```
diff --git a/stable/_sources/methoddocs/ape_test.md.txt b/stable/_sources/methoddocs/ape_test.md.txt
@@ -1,6 +1,16 @@
 # ape-test
 
 ```{eval-rst}
-.. automodule:: ape_test
+.. automodule:: ape_test.accounts
+    :members:
+```
+
+```{eval-rst}
+.. automodule:: ape_test.config
+    :members:
+```
+
+```{eval-rst}
+.. automodule:: ape_test.provider
     :members:
 ```
diff --git a/stable/_sources/userguides/compile.md.txt b/stable/_sources/userguides/compile.md.txt
@@ -121,7 +121,7 @@ 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")])
+solidity.compile([Path("path/to/contract.sol")])
 ```
 
 ## Compile Source Code

diff --git a/stable/_sources/userguides/contracts.md.txt b/stable/_sources/userguides/contracts.md.txt
@@ -111,7 +111,18 @@ from ape import Contract
 contract = Contract("0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45")
 ```
 
-It will fetch the `contract-type` using the explorer plugin from the active network, such as [ape-etherscan](https://github.com/ApeWorX/ape-etherscan).
+If the contract ABI and/or code is cached on disk or in memory (such as from a previous deploy or retrieval), it will use it.
+Otherwise, it will fetch the `ContractType` using the explorer plugin from the active network, such as [ape-etherscan](https://github.com/ApeWorX/ape-etherscan).
+
+To avoid fetching the contract from an explorer such as Etherscan, use `fetch_from_explorer=False`.
+
+```python
+from ape import Contract
+
+contract = Contract("0x68b3465833fb72A70ecDF485E0e4C7bD8665Fc45", fetch_from_explorer=False)
+```
+
+This also avoids checking for an updated `ContractType` and forces Ape to only use types cached to disk or in memory.
 
 If you have the [ENS plugin](https://github.com/ApeWorX/ape-ens) installed, you can use `.eth` domain names as the argument:
 

diff --git a/stable/_sources/userguides/scripts.md.txt b/stable/_sources/userguides/scripts.md.txt
@@ -138,7 +138,7 @@ Suppose the name of the script is `foobar`, you can run it via:
 ape run foobar
 ```
 
-Without specifying `--network`, the script with connect to your default network.
+Without specifying `--network`, the script will connect to your default network.
 Else, specify the network using the `--network` flag:
 
 ```shell

diff --git a/stable/_sources/userguides/testing.md.txt b/stable/_sources/userguides/testing.md.txt
@@ -70,11 +70,6 @@ def test_authorization(my_contract, owner, not_owner):
         my_contract.authorized_method(sender=not_owner)
 ```
 
-```{note}
-Ape has built-in test and fixture isolation for all pytest scopes.
-To disable isolation add the `--disable-isolation` flag when running `ape test`
-```
-
 ## Fixtures
 
 Now that we have discussed the full flow of a test, let's dive deeper into the specific parts, starting with `pytest.fixtures`.
@@ -200,12 +195,10 @@ You also have access to the `project` you are testing. You will need this to dep
 ```python
 import pytest
 
-
 @pytest.fixture
 def owner(accounts):
     return accounts[0]
 
-
 @pytest.fixture
 def my_contract(project, owner):
     #           ^ use the 'project' fixture from the 'ape-test' plugin
@@ -226,6 +219,72 @@ def my_contract(Contract):
 
 It has the same interface as the [ChainManager](../methoddocs/managers.html#ape.managers.chain.ChainManager).
 
+## Isolation
+
+By default, tests run with chain-isolation.
+This means, at the start of each test, a snapshot is taken.
+After each test completes, the chain reverts to that snapshot from the beginning of the test.
+
+By default, every `pytest` fixture is `function` scoped, meaning it will be replayed each time it is requested (no result-caching).
+For example, if you deploy a contract in a function-scoped fixture, it will be re-deployed each time the fixture gets used in your tests.
+To only deploy once, you can use different scopes, such as `"session"`, `"package"`, `"module"`, or `"class"`, and you **must** use these fixtures right away, either via `autouse=True` or using them in the first collected tests.
+Otherwise, higher-scoped fixtures that arrive late in a Pytest session will cause the snapshotting system to have to rebase itself, which can be costly.
+For example, if you define a session scoped fixture that deploys a contract and makes transactions, the state changes from those transactions remain in subsequent tests, whether those tests use that fixture or not.
+However, if a new fixture of a session scope comes into play after module, package, or class scoped snapshots have already been taken, those lower-scoped fixtures are now invalid and have to re-run after the session fixture to ensure the session fixture remains in the session-snapshot.
+
+In the following example, the `my_contract` fixture gets deployed upon its first usage, which happens in the test `test_my_contract_0()`.
+During the test `test_something_else()`, it may not have been deployed yet, as it was not requested, and it is defined before the other tests.
+Then, during `test_my_contract_1()`, instead of deploying again, it uses the cached result from the session-scoped fixture and the chain still has it in its state because the fixture is session-scoped and runs before the test-isolation.
+
+```python
+import pytest
+
+@pytest.fixture(scope="session")
+def my_contract(accounts, project):
+    owner = accounts[0]
+    contract = project.MyContract.deploy(sender=owner)
+    # Can also do stateful transactions in a session-scoped fixture.
+    contract.initialize(sender=owner)
+    return contract
+
+def test_something_else():
+    ...
+
+def test_my_contract_0(my_contract):
+    my_contract.myMethod()
+
+def test_my_contract_1(my_contract):
+    my_contract.myMethod()
+```
+
+To disable isolation, run `ape test` with the `--disable-isolation` flag.
+When isolation is disabled, the blockchain's state persists as the tests run.
+This will be more performant and less complex, but will also cause non-deterministic results in your tests as each test inherits the state of whatever was run before it.
+
+This may be further complicated when running with other pytest plugins such as `pytest-xdist` or `pytest-split` which re-arranges the order that tests are executed in (not recommended to use these plugins together with ape until more proper integrations are developed).
+
+```shell
+ape test --disable-isolation
+```
+
+```{warning}
+Be mindful if, when, and how you define non-function scoped fixtures.
+Pytest activates fixtures in the order they are used.
+If a session scoped fixture comes into play after package, module, or class scoped fixtures, the isolation logic has to invalidate each of those scopes and replay them after the session scoped, which causes any benefits of package, module, or class scopes to be void.
+If you are using higher-scoped fixtures for parametrized fixtures with lower-scoped fixtures, each itertion of the parametried fixture invalidates the lower-level fixtures each time, rendering everything to behave as function scoped until the end of the parametrized fixtures first run-through.
+```
+
+If you are using chain-isolation and have a higher-scoped fixture that you know is for-sure not chain-altering, you can use `ape.fixture` and the `chain_isolation` flag, and it may improve performance:
+
+```python
+import ape
+from ape_tokens import tokens
+
+@ape.fixture(scope="session", chain_isolation=False, params=("WETH", "DAI", "BAT"))
+def token_addresses(request):
+    return tokens[request].address
+```
+
 ## Ape testing commands
 
 ```bash
@@ -345,7 +404,8 @@ You may also supply an `re.Pattern` object to assert on a message pattern, rathe
 import ape
 import re
 
-# Matches explicitly "foo" or "bar"
+# Matches
+# "foo" or "bar"
 with ape.reverts(re.compile(r"^(foo|bar)$")):
     ...
 ```
@@ -396,8 +456,9 @@ You may also supply an `re.Pattern` object to assert on a dev message pattern, r
 
 ```python
 import ape
+import re
 
-# Matches explictly "dev: foo" or "dev: bar"
+# Matches "dev: foo" or "dev: bar"
 with ape.reverts(dev_message=re.compile(r"^dev: (foo|bar)$")):
     ...
 ```