Merge remote-tracking branch 'upstream/main' into docs/add_doctest

.github/workflows/test.yaml

@@ -65,7 +65,7 @@ jobs:
                 # TODO: Replace with macos-latest when works again.
                 #   https://github.com/actions/setup-python/issues/808
                 os: [ubuntu-latest, macos-12]   # eventually add `windows-latest`
-                python-version: [3.8, 3.9, "3.10", "3.11", "3.12"]
+                python-version: [3.9, "3.10", "3.11", "3.12"]
 
         env:
           GITHUB_ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.pre-commit-config.yaml

@@ -25,13 +25,14 @@ repos:
     hooks:
     -   id: mypy
         additional_dependencies: [
-                types-PyYAML,
+                pydantic,
+                pandas-stubs,
                 types-python-dateutil,
+                types-PyYAML,
                 types-requests,
                 types-setuptools,
-                pydantic,
-                pandas-stubs,
-                types-SQLAlchemy
+                types-SQLAlchemy,
+                types-toml
         ]
 
 -   repo: https://github.com/executablebooks/mdformat

CONTRIBUTING.md

@@ -15,7 +15,9 @@ source venv/bin/activate
 pip install -e .'[dev]'
 ```
 
-**NOTE**: You might run into issues where you have a local install and are trying to work with a plugin pinned to a specific version.
+```{note}
+You might run into issues where you have a local install and are trying to work with a plugin pinned to a specific version.
+```
 
 [The easiest solution](https://github.com/ApeWorX/ape/issues/90) to this is to fetch the tags via `git fetch upstream --tags` and reinstall via `pip install .`.
 You will then have the correct version.
@@ -66,7 +68,10 @@ python -m http.server --directory "docs/_build/" --bind 127.0.0.1 1337
 ```
 
 Then, open your browser to `127.0.0.1:1337` and click the `ape` directory link.
-NOTE: Serving from `"docs/_build/"` rather than `"docs/_build/ape"` is necessary to make routing work.
+
+```{note}
+Serving from `"docs/_build/"` rather than `"docs/_build/ape"` is necessary to make routing work.
+```
 
 ## Pull Requests
 

README.md

@@ -27,7 +27,7 @@ Read our [academic platform](https://academy.apeworx.io/) will help you master A
 In the latest release, Ape requires:
 
 - Linux or macOS
-- Python 3.8 up to 3.12
+- Python 3.9 up to 3.12
 - **Windows**: Install Windows Subsystem Linux [(WSL)](https://docs.microsoft.com/en-us/windows/wsl/install)
 
 Check your python version in a terminal with `python3 --version`.
@@ -95,8 +95,10 @@ Ape's modular plugin system allows users to have an interoperable experience wit
 
 - Learn more about **developing** your own plugins from this [developing user guide](https://docs.apeworx.io/ape/stable/userguides/developing_plugins.html).
 
-**NOTE**: If a plugin does not originate from the [ApeWorX GitHub Organization](https://github.com/ApeWorX?q=ape&type=all), you will get a warning about installing 3rd-party plugins.
+```{note}
+If a plugin does not originate from the [ApeWorX GitHub Organization](https://github.com/ApeWorX?q=ape&type=all), you will get a warning about installing 3rd-party plugins.
 Install 3rd party plugins at your own risk.
+```
 
 [accounts-guide]: https://docs.apeworx.io/ape/stable/userguides/accounts.html
 [actions-badge]: https://github.com/ApeWorX/ape/actions/workflows/test.yaml/badge.svg

docs/conf.py

@@ -15,7 +15,6 @@
 import sys
 from functools import lru_cache
 from pathlib import Path
-from typing import List
 
 import requests
 from packaging.version import Version
@@ -45,7 +44,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns: List[str] = ["_build", ".DS_Store"]
+exclude_patterns: list[str] = ["_build", ".DS_Store"]
 
 
 # The suffix(es) of source filenames.
@@ -83,7 +82,11 @@
 
 # Set some default to avoid unnecessary repetitious directives.
 autodoc_default_options = {
-    "exclude-members": "__repr__,__weakref__,__metaclass__,__init__,model_config,model_fields,model_post_init"
+    "exclude-members": (
+        "__repr__, __weakref__, __metaclass__, __init__, __format__,  __new__, __str__, __dir__"
+        "model_config, model_fields, model_post_init, model_computed_fields,"
+        "__ape_extra_attributes__,"
+    )
 }
 
 # -- Doctest configuration -------------------------------------------------
@@ -115,7 +118,7 @@ def fixpath(path: str) -> str:
 
 
 @lru_cache(maxsize=None)
-def get_versions() -> List[str]:
+def get_versions() -> list[str]:
     """
     Get all the versions from the Web.
     """

docs/index.md

@@ -25,6 +25,7 @@
    userguides/scripts
    userguides/publishing
    userguides/logging
+   userguides/trace
 ```
 
 ```{eval-rst}
@@ -45,11 +46,10 @@
 
 ```{eval-rst}
 .. toctree::
-   :caption: Python Reference
+   :caption: Core Python Reference
    :maxdepth: 1
 
    methoddocs/ape.md
-   methoddocs/ape_accounts.md
    methoddocs/api.md
    methoddocs/cli.md
    methoddocs/contracts.md
@@ -59,3 +59,16 @@
    methoddocs/types.md
    methoddocs/utils.md
 ```
+
+```{eval-rst}
+.. toctree::
+   :caption: Plugin Python Reference
+   :maxdepth: 1
+
+   methoddocs/ape_accounts.md
+   methoddocs/ape_compile.md
+   methoddocs/ape_ethereum.md
+   methoddocs/ape_node.md
+   methoddocs/ape_pm.md
+   methoddocs/ape_test.md
+```

docs/methoddocs/ape_compile.md

@@ -0,0 +1,6 @@
+# ape-compile
+
+```{eval-rst}
+.. automodule:: ape_compile
+    :members:
+```

docs/methoddocs/ape_ethereum.md

@@ -0,0 +1,15 @@
+# ape-ethereum
+
+```{eval-rst}
+.. automodule:: ape_ethereum
+    :members:
+```
+
+# ape-ethereum.multicall
+
+```{eval-rst}
+.. automodule:: ape_ethereum.multicall
+    :members:
+    :show-inheritance:
+    :special-members:
+```

docs/methoddocs/ape_node.md

@@ -0,0 +1,6 @@
+# ape-node
+
+```{eval-rst}
+.. automodule:: ape_node
+    :members:
+```

docs/methoddocs/ape_pm.md

@@ -0,0 +1,6 @@
+# ape-pm
+
+```{eval-rst}
+.. automodule:: ape_pm
+    :members:
+```

docs/methoddocs/ape_test.md

@@ -0,0 +1,6 @@
+# ape-test
+
+```{eval-rst}
+.. automodule:: ape_test
+    :members:
+```

docs/methoddocs/managers.md

@@ -72,31 +72,7 @@
 ## Project
 
 ```{eval-rst}
-.. automodule:: ape.managers.project.manager
-    :members:
-    :special-members:
-```
-
-```{eval-rst}
-.. automodule:: ape.managers.project.dependency
-    :members:
-    :special-members:
-```
-
-```{eval-rst}
-.. autoclass:: ape.managers.project.types.BaseProject
-    :members:
-    :special-members:
-```
-
-```{eval-rst}
-.. autoclass:: ape.managers.project.types.ApeProject
-    :members:
-    :special-members:
-```
-
-```{eval-rst}
-.. autoclass:: ape.managers.project.types.BrownieProject
+.. automodule:: ape.managers.project
     :members:
     :special-members:
 ```

docs/userguides/accounts.md

@@ -30,12 +30,12 @@ def test_my_contract_method(accounts):
 To access the same prefunded accounts in your scripts or console, use the root `accounts` object and the [test_accounts](../methoddocs/managers.html#ape.managers.accounts.AccountManager.test_accounts) property:
 
 ```{eval-rst}
-
 .. doctest::
 
->>> from ape import accounts
+  >>> from ape import accounts
+
+  >>> sender = accounts.test_accounts[0]
 
->>> sender = accounts.test_accounts[0]
 ```
 
 You can configure your test accounts using your `ape-config.yaml` file:
@@ -46,23 +46,27 @@ test:
   number_of_accounts: 5
 ```
 
-**WARN**: NEVER put a seed phrase with real funds here.
+```{warning}
+NEVER put a seed phrase with real funds here.
+```
+
 The accounts generated from this seed are solely for testing and debugging purposes.
 
 ### Creating new test accounts
 
 You can create a new test account by doing the following:
 
 ```{eval-rst}
-
 .. doctest::
 
->>> from ape import accounts
+  >>> from ape import accounts
 
->>> account = accounts.test_accounts.generate_test_account()
+  >>> account = accounts.test_accounts.generate_test_account()
 ```
 
-**NOTE**: Creating a new test account means it will be unfunded by default.
+```{note}
+Creating a new test account means it will be unfunded by default.
+```
 
 Learn more about test accounts from the [testing guide](./testing.html#accounts-fixture).
 
@@ -270,7 +274,10 @@ message = encode_defunct(text="Hello Apes!")
 signature = account.sign_message(message)
 ```
 
-**NOTE**: Ape's `sign_message` API intentionally accepts `Any` as the message argument type.
+```{note}
+Ape's `sign_message` API intentionally accepts `Any` as the message argument type.
+```
+
 Account plugins decide what data-types to support.
 Most Ethereum account plugins, such as `ape-account`, are able to sign messages like the example above.
 However, you can also provide other types, such as a `str` directly:
@@ -357,7 +364,9 @@ message = encode_defunct(text="Hello Apes!")
 signature = account.sign_message(message)
 ```
 
-**NOTE**: Alternatively, you may use the `passphrase=` kwarg on methods `account.set_autosign()` and `account.unlock()`, but we highly recommend using the environment variable approach to avoid accidentally leaking your passphrase.
+```{note}
+Alternatively, you may use the `passphrase=` kwarg on methods `account.set_autosign()` and `account.unlock()`, but we highly recommend using the environment variable approach to avoid accidentally leaking your passphrase.
+```
 
 ## Hardware Wallets
 

docs/userguides/clis.md

@@ -150,12 +150,12 @@ And when invoking the command from the CLI, it would look like the following:
 
 ```shell
 <prefix> cmd  # Use the default account.
-<prefix> cmd --account 0  # Use first account that would show up in `get_user_selected_account()`.
+<prefix> cmd --account 0  # Use first account that would show up in `select_account()`.
 <prefix> cmd --account metamask  # Use account with alias "metamask".
 <prefix> cmd --account TEST::0  # Use the test account at index 0.
 ```
 
-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:
+Alternatively, you can call the [select_account()](../methoddocs/cli.html#ape.cli.choices.select_account) directly to have more control of when the account gets selected:
 
 ```python
 import click
@@ -197,7 +197,7 @@ Use `account_type` to filter the choices by specific types of [AccountAPI](../me
 ```python
 import click
 from ape import accounts
-from ape.cli import existing_alias_argument, get_user_selected_account
+from ape.cli import existing_alias_argument, select_account
 from ape_accounts.accounts import KeyfileAccount
 
 # NOTE: This is just an example and not anything specific or recommended.
@@ -215,7 +215,7 @@ def cli_1(alias):
 
 # Select from the given accounts directly.
 my_accounts = [accounts.load("me"), accounts.load("me2")]
-selected_account = get_user_selected_account(account_type=my_accounts)
+selected_account = select_account(account_type=my_accounts)
 ```
 
 ## Contract File Paths

docs/userguides/compile.md

@@ -39,7 +39,9 @@ contract.my_method()
 3. **Raw Compiler Output**: If you have an artifact with binary compiled elsewhere, you can include it in your project.
    This is useful if you want to use contracts from much larger projects as dependency for your test cases.
 
-**WARN**: You may have to adjust name and source ID similarly to raw contract-type output.
+```{warning}
+You may have to adjust name and source ID similarly to raw contract-type output.
+```
 
 ## Other Compiler Plugins
 
@@ -58,6 +60,7 @@ compile:
   exclude:
     - "examples"  # Exclude all files in the examples/ directory
     - "*Mock.sol"  # Exclude all files ending in Mock.sol
+    - r"(?!.*_mock\.vy$)"  # You can also use regex instead of globs (prefix with `r`).
 ```
 
 You can also exclude files using the `--config-override` CLI option:
@@ -87,23 +90,8 @@ compile:
 ## Settings
 
 Generally, configure compiler plugins using your `ape-config.yaml` file.
-One setting that applies to many compiler plugins is `cache_folder`, which holds dependency source files the compiler uses when compiling your contracts.
-By default, the folder is in your `contracts/.cache` folder but there are times you may want to move this to another location.
-Paths are relative to the project directory.
-For instance, to move the dependency cache to the root project directory:
-
-```yaml
-compile:
-   cache_folder: .cache
-```
-
-```{caution}
-Changing the location of the dependency cache folder may alter the the output bytecode of your contracts from some compilers.
-Specifically, the [solc compiler will apend a hash of the input metadata to the contract bytecode](https://docs.soliditylang.org/en/latest/metadata.html#encoding-of-the-metadata-hash-in-the-bytecode) which will change with contract path or compiler settings changes.
-This may impact things like contract verification on existing projects.
-```
 
-As another example, when using the `vyper` plugin, you can configure settings under the `vyper` key:
+For example, when using the `vyper` plugin, you can configure settings under the `vyper` key:
 
 ```yaml
 vyper:
@@ -158,3 +146,19 @@ owner = accounts.test_accounts[0]
 
 instance = container.deploy(sender=owner)
 ```
+
+## Output Extra
+
+Sometimes, there are extra output styles you may want.
+For example, to output minified ABI JSONs, use the following config:
+
+```yaml
+compile:
+  output_extra:
+     - ABI
+```
+
+Then, after compiling, you should notice minified ABI json files in your `.build/abi` folder.
+This is useful if hosting these files on a web-server.
+
+To see the full list of supported output-extra, see [the OutpuExtra enum documentation](../methoddocs/ape_compile.html#ape_compile.OutputExtras).