chore: merge main

.pre-commit-config.yaml

@@ -1,6 +1,6 @@
 repos:
 -   repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.6.0
+    rev: v5.0.0
     hooks:
     -   id: check-yaml
 
@@ -10,7 +10,7 @@ repos:
       - id: isort
 
 -   repo: https://github.com/psf/black
-    rev: 24.8.0
+    rev: 24.10.0
     hooks:
       - id: black
         name: black
@@ -22,7 +22,7 @@ repos:
         additional_dependencies: [flake8-breakpoint, flake8-print, flake8-pydantic]
 
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.11.1
+    rev: v1.11.2
     hooks:
     -   id: mypy
         additional_dependencies: [
@@ -37,7 +37,7 @@ repos:
         ]
 
 -   repo: https://github.com/executablebooks/mdformat
-    rev: 0.7.17
+    rev: 0.7.18
     hooks:
     -   id: mdformat
         additional_dependencies: [mdformat-gfm, mdformat-frontmatter, mdformat-pyproject]

docs/index.rst

@@ -1 +1,25 @@
 .. dynamic-toc-tree::
+    :plugin-prefix: ape_
+    :userguides:
+        - quickstart
+        - accounts
+        - networks
+        - forking_networks
+        - contracts
+        - proxy
+        - installing_plugins
+        - projects
+        - dependencies
+        - config
+        - compile
+        - console
+        - transactions
+        - trace
+        - scripts
+        - testing
+        - reverts
+        - publishing
+        - clis
+        - data
+        - developing_plugins
+        - logging

docs/userguides/config.md

@@ -1,15 +1,16 @@
 # Configure Ape
 
-You can configure Ape using configuration files with the name `ape-config.yaml`.
-There are two locations you can place an `ape-config.yaml` file.
+You can configure Ape using a `pyproject.toml` file and the prefix `tool.ape` or any configuration file named `ape-config.[yaml|yml|json]`.
+There are two locations you can place config files.
 
 1. In the root of your project
 2. In your `$HOME/.ape` directory (global)
 
 Project settings take precedent, but global settings allow you to configure preferences across all projects, such as your default mainnet provider (e.g. Alchemy versus running your own node).
 
-This guide serves as an index of the settings you can include in any `ape-config.yaml` file.
+This guide serves as an index of some settings you can include in any `ape-config.yaml` file.
 This guide is **PURPOSELY** alphabetized to facilitate easier look-up of keys.
+Plugins for Ape may define their own configs.
 
 Most of the features in this guide are documented more-fully elsewhere in the user-guides.
 
@@ -22,6 +23,13 @@ However, here is a list of common-use cases requiring the `ape-config.yaml` file
 **Environment Variables**: `ape-config.yaml` files support environment-variable expansion.
 Simply include environment variables (with the `$` prefix) in your config file and Ape will automatically expand them.
 
+```toml
+[tool.ape.plugin]
+secret_rpc = "$MY_SECRET_RPC"
+```
+
+Or the equivalent YAML:
+
 ```yaml
 plugin:
   secret_rpc: $MY_SECRET_RPC
@@ -43,6 +51,13 @@ project
 
 In this case, you want to configure Ape like:
 
+```toml
+[tool.ape]
+base_path = "src"
+```
+
+Or the equivalent YAML:
+
 ```yaml
 base_path: src
 ```
@@ -55,6 +70,13 @@ Some dependencies, such as python-based ones like `snekmate`, use this structure
 Specify a different path to your `contracts/` directory.
 This is useful when using a different naming convention, such as `src/` rather than `contracts/`.
 
+```toml
+[tool.ape]
+contracts_folder = "src"
+```
+
+Or the equivalent YAML:
+
 ```yaml
 contracts_folder: src
 ```
@@ -70,6 +92,13 @@ contracts_folder: "~/GlobalContracts"
 
 You can change the default ecosystem by including the following:
 
+```toml
+[tool.ape]
+default_ecosystem = "fantom"
+```
+
+Or the equivalent YAML:
+
 ```yaml
 default_ecosystem: fantom
 ```
@@ -83,9 +112,18 @@ To learn more about dependencies, see [this guide](./dependencies.html).
 
 A simple example of configuring dependencies looks like this:
 
+```toml
+[[tool.ape.dependencies]]
+name = "openzeppelin"
+github = "OpenZeppelin/openzeppelin-contracts"
+version = "4.4.2"
+```
+
+Or the equivalent YAML:
+
 ```yaml
 dependencies:
-  - name: OpenZeppelin
+  - name: openzeppelin
     github: OpenZeppelin/openzeppelin-contracts
     version: 4.4.2
 ```
@@ -97,6 +135,18 @@ Set deployments that were made outside of Ape in your `ape-config.yaml` to creat
 
 Config example:
 
+```toml
+[[tool.ape.deployments.ethereum.mainnet]]
+contract_type = "MyContract"
+address = "0x5FbDB2315678afecb367f032d93F642f64180aa3"
+
+[[tool.ape.deployments.ethereum.sepolia]]
+contract_type = "MyContract"
+address = "0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512"
+```
+
+Or the equivalent YAML:
+
 ```yaml
 deployments:
   ethereum:
@@ -125,6 +175,13 @@ Ape does not add or edit deployments in your `ape-config.yaml` file.
 When using the `node` provider, you can customize its settings.
 For example, to change the URI for an Ethereum network, do:
 
+```toml
+[tool.ape.node.ethereum.mainnet]
+uri = "http://localhost:5030"
+```
+
+Or the equivalent YAML:
+
 ```yaml
 node:
   ethereum:
@@ -144,6 +201,16 @@ For more information on networking as a whole, see [this guide](./networks.html)
 
 Set default network and network providers:
 
+```toml
+[tool.ape.ethereum]
+default_network = "mainnet-fork"
+
+[tool.ape.ethereum.mainnet_fork]
+default_provider = "hardhat"
+```
+
+Or the equivalent YAML:
+
 ```yaml
 ethereum:
   default_network: mainnet-fork
@@ -187,6 +254,17 @@ Set which `ape` plugins you want to always use.
 The `ape-` prefix is not needed and shouldn't be included here.
 ```
 
+```toml
+[[tool.ape.plugins]]
+name = "solidity"
+version = "0.1.0b2"
+
+[[tool.ape.plugins]]
+name = "ens"
+```
+
+Or the equivalent YAML:
+
 ```yaml
 plugins:
   - name: solidity # ape-solidity plugin
@@ -242,3 +320,40 @@ test:
   mnemonic: test test test test test test test test test test test junk
   number_of_accounts: 5
 ```
+
+## Plugin Settings
+
+To configure a plugin, use the name of the plugin followed by any of the plugin's settings.
+For example, to configure the `ape-solidity` plugin, you would do:
+
+```yaml
+solidity:
+  evm_version: paris  # Or any other setting defined in `ape-solidity`.
+```
+
+## Non-plugin settings
+
+Projects can use their own settings.
+Meaning, you can put whatever data you want in an `ape-config.yaml` file and read it in Ape.
+
+```{note}
+These types of settings lack sophisticated Pydantic validation and are limited in that respect.
+Simple validation, however, will occur, such as if it the value `isnumeric()`, it will be converted to an int, or if the value is a boolean name it will convert it to a `bool`.
+```
+
+```yaml
+my_project_key:
+  my_string: "my_value"
+  my_int: 123
+  my_bool: True
+```
+
+Then, to access it (or any setting for that matter):
+
+```python
+from ape import project
+
+my_str = project.config.my_project_key.my_string  #  "my_value"
+my_int = project.config.my_project_key.my_int  #  123
+my_bool = project.config.my_project_key.my_bool  #  True
+```

docs/userguides/installing_plugins.md

@@ -67,6 +67,12 @@ Or from the CLI like:
 ape plugins install "foobar@git+https://github.com/<owner-of-plugin>/ape-foobar.git@<branch/name>"
 ```
 
+Also, you may omit the `foobar@` prefix and allow Ape to deduce the name:
+
+```shell
+ape plugins install "git+https://github.com/<owner-of-plugin>/ape-foobar.git@<branch/name>"
+```
+
 ## Plugin Versions
 
 By default, `ape plugins` commands install plugins within your current Ape version specification.

setup.py

@@ -21,8 +21,8 @@
         "hypothesis-jsonschema==0.19.0",  # JSON Schema fuzzer extension
     ],
     "lint": [
-        "black>=24.8.0,<25",  # Auto-formatter and linter
-        "mypy>=1.11.1,<2",  # Static type analyzer
+        "black>=24.10.0,<25",  # Auto-formatter and linter
+        "mypy>=1.11.2,<2",  # Static type analyzer
         "types-PyYAML",  # Needed due to mypy typeshed
         "types-requests",  # Needed due to mypy typeshed
         "types-setuptools",  # Needed due to mypy typeshed
@@ -35,7 +35,7 @@
         "flake8-print>=4.0.1,<5",  # Detect print statements left in code
         "flake8-pydantic",  # For detecting issues with Pydantic models
         "isort>=5.13.2,<6",  # Import sorting linter
-        "mdformat>=0.7.17",  # Auto-formatter for markdown
+        "mdformat>=0.7.18",  # Auto-formatter for markdown
         "mdformat-gfm>=0.3.5",  # Needed for formatting GitHub-flavored markdown
         "mdformat-frontmatter>=0.4.1",  # Needed for frontmatters-style headers in issue templates
         "mdformat-pyproject>=0.0.1",  # Allows configuring in pyproject.toml
@@ -128,7 +128,7 @@
         "eip712>=0.2.10,<0.3",
         "ethpm-types>=0.6.17,<0.7",
         "eth_pydantic_types>=0.1.3,<0.2",
-        "evmchains>=0.0.10,<0.1",
+        "evmchains>=0.1.0,<0.2",
         "evm-trace>=0.2.3,<0.3",
     ],
     entry_points={

src/ape/api/config.py

@@ -424,6 +424,21 @@ def __ape_extra_attributes__(self) -> Iterator[ExtraModelAttributes]:
 
     @classmethod
     def validate_file(cls, path: Path, **overrides) -> "ApeConfig":
+        """
+        Create an ApeConfig class using the given path.
+        Supports both pyproject.toml and ape-config.[.yml|.yaml|.json] files.
+
+        Raises:
+            :class:`~ape.exceptions.ConfigError`: When given an unknown file type
+              or the data is invalid.
+
+        Args:
+            path (Path): The path to the file.
+            **overrides: Config overrides.
+
+        Returns:
+            :class:`~ape.api.config.ApeConfig`
+        """
         data = {**load_config(path), **overrides}
 
         # NOTE: We are including the project path here to assist

src/ape/api/explorers.py

@@ -60,3 +60,19 @@ def publish_contract(self, address: AddressType):
         Args:
             address (:class:`~ape.types.address.AddressType`): The address of the deployed contract.
         """
+
+    @classmethod
+    def supports_chain(cls, chain_id: int) -> bool:
+        """
+        Returns ``True`` when the given chain ID is claimed to be
+        supported by this explorer. Adhoc / custom networks rely on
+        this feature to have automatic-explorer support. Explorer
+        plugins should override this.
+
+        Args:
+            chain_id (int): The chain ID to check.
+
+        Returns:
+            bool
+        """
+        return False