Merge branch 'ApeWorX:main' into main

Author: craig-openlaw

.github/workflows/docs.yaml

@@ -0,0 +1,34 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+  release:
+    types: [released]
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Setup Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: "3.10"
+
+    - name: Install Dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install .[doc]
+
+    - name: Ape Docs
+      uses: apeworx/sphinx-ape@main
+      with:
+        github-token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test.yaml

@@ -63,7 +63,7 @@ jobs:
         strategy:
             matrix:
                 os: [ubuntu-latest, macos-latest]   # eventually add `windows-latest`
-                python-version: [3.9, "3.10", "3.11", "3.12"]
+                python-version: [3.9, "3.10", "3.11", "3.12", "3.13"]
 
         steps:
         - uses: actions/checkout@v4

.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,24 +10,25 @@ repos:
       - id: isort
 
 -   repo: https://github.com/psf/black
-    rev: 24.4.2
+    rev: 24.10.0
     hooks:
       - id: black
         name: black
 
 -   repo: https://github.com/pycqa/flake8
-    rev: 7.0.0
+    rev: 7.1.1
     hooks:
     -   id: flake8
+        additional_dependencies: [flake8-breakpoint, flake8-print, flake8-pydantic, flake8-type-checking]
 
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.10.0
+    rev: v1.13.0
     hooks:
     -   id: mypy
         additional_dependencies: [types-setuptools, pydantic]
 
 -   repo: https://github.com/executablebooks/mdformat
-    rev: 0.7.17
+    rev: 0.7.19
     hooks:
     -   id: mdformat
         additional_dependencies: [mdformat-gfm, mdformat-frontmatter, mdformat-pyproject]

ape_ledger/__init__.py

@@ -1,8 +1,25 @@
-from ape import plugins
+from importlib import import_module
+from typing import Any
 
-from ape_ledger.accounts import AccountContainer, LedgerAccount
+from ape import plugins
 
 
 @plugins.register(plugins.AccountPlugin)
 def account_types():
+    from ape_ledger.accounts import AccountContainer, LedgerAccount
+
     return AccountContainer, LedgerAccount
+
+
+def __getattr__(name: str) -> Any:
+    if name in ("AccountContainer", "LedgerAccount"):
+        return getattr(import_module("ape_ledger.accounts"), name)
+
+    else:
+        raise AttributeError(name)
+
+
+__all__ = [
+    "AccountContainer",
+    "LedgerAccount",
+]

ape_ledger/_cli.py

@@ -1,24 +1,22 @@
-from typing import Union
+from typing import TYPE_CHECKING, Union
 
 import click
-from ape import accounts
-from ape.cli import (
-    ape_cli_context,
-    existing_alias_argument,
-    network_option,
-    non_existing_alias_argument,
-    skip_confirmation_option,
-)
-from eth_account import Account
-from eth_account.messages import encode_defunct
+from ape.cli.arguments import existing_alias_argument, non_existing_alias_argument
+from ape.cli.options import ape_cli_context, network_option, skip_confirmation_option
+
+if TYPE_CHECKING:
+    # NOTE: Type-checking only imports so CLI help loads faster.
+    from ape.api import AccountAPI
+    from ape_ledger.accounts import LedgerAccount
+    from ape_ledger.hdpath import HDAccountPath, HDBasePath
 
-from ape_ledger.accounts import LedgerAccount
-from ape_ledger.choices import AddressPromptChoice
 from ape_ledger.exceptions import LedgerSigningError
-from ape_ledger.hdpath import HDAccountPath, HDBasePath
 
 
-def _select_account(hd_path: Union[HDBasePath, str]) -> tuple[str, HDAccountPath]:
+def _select_account(hd_path: Union["HDBasePath", str]) -> tuple[str, "HDAccountPath"]:
+    # NOTE: Lazy import so CLI help loads faster.
+    from ape_ledger.choices import AddressPromptChoice
+
     choices = AddressPromptChoice(hd_path)
     return choices.get_user_selected_account()
 
@@ -52,8 +50,18 @@ def _list(cli_ctx):
         click.echo(f"  {account.address}{alias_display}{hd_path_display}")
 
 
-def _get_ledger_accounts() -> list[LedgerAccount]:
-    return [a for a in accounts if isinstance(a, LedgerAccount)]
+def _get_ledger_accounts() -> list["LedgerAccount"]:
+    from ape.utils.basemodel import ManagerAccessMixin
+
+    from ape_ledger.accounts import LedgerAccount
+
+    return [a for a in ManagerAccessMixin.account_manager if isinstance(a, LedgerAccount)]
+
+
+def _hdpath_callback(ctx, param, val) -> "HDBasePath":
+    from ape_ledger.hdpath import HDBasePath
+
+    return HDBasePath(val)
 
 
 @cli.command()
@@ -66,24 +74,30 @@ def _get_ledger_accounts() -> list[LedgerAccount]:
         "Defaults to m/44'/60'/{x}'/0/0 where {{x}} is the account ID. "
         "Exclude {x} to append the account ID to the end of the base path."
     ),
-    callback=lambda ctx, param, arg: HDBasePath(arg),
+    callback=_hdpath_callback,
 )
 def add(cli_ctx, alias, hd_path):
     """Add an account from your Ledger hardware wallet"""
 
     address, account_hd_path = _select_account(hd_path)
-    container = accounts.containers["ledger"]
+    container = cli_ctx.account_manager.containers["ledger"]
     container.save_account(alias, address, str(account_hd_path))
     cli_ctx.logger.success(f"Account '{address}' successfully added with alias '{alias}'.")
 
 
+def _filter_accounts(acct: "AccountAPI") -> bool:
+    from ape_ledger.accounts import LedgerAccount
+
+    return isinstance(acct, LedgerAccount)
+
+
 @cli.command()
 @ape_cli_context()
-@existing_alias_argument(account_type=LedgerAccount)
+@existing_alias_argument(account_type=_filter_accounts)
 def delete(cli_ctx, alias):
     """Remove a Ledger account from ape"""
 
-    container = accounts.containers["ledger"]
+    container = cli_ctx.account_manager.containers["ledger"]
     container.delete_account(alias)
     cli_ctx.logger.success(f"Account '{alias}' has been removed.")
 
@@ -94,7 +108,7 @@ def delete(cli_ctx, alias):
 def delete_all(cli_ctx, skip_confirmation):
     """Remove all Ledger accounts from ape"""
 
-    container = accounts.containers["ledger"]
+    container = cli_ctx.account_manager.containers["ledger"]
     ledger_accounts = _get_ledger_accounts()
     if len(ledger_accounts) == 0:
         cli_ctx.logger.warning("No accounts found.")
@@ -131,11 +145,14 @@ def sign_message(cli_ctx, alias, message, network):
 
 
 def _sign_message(cli_ctx, alias, message):
-    if alias not in accounts.aliases:
+    from eth_account.account import Account
+    from eth_account.messages import encode_defunct
+
+    if alias not in cli_ctx.account_manager.aliases:
         cli_ctx.abort(f"Account with alias '{alias}' does not exist.")
 
     eip191message = encode_defunct(text=message)
-    account = accounts.load(alias)
+    account = cli_ctx.account_manager.load(alias)
     signature = account.sign_message(eip191message)
 
     if not signature:
@@ -153,9 +170,13 @@ def _sign_message(cli_ctx, alias, message):
 
 
 @cli.command(short_help="Verify a message with your Trezor device")
+@ape_cli_context()
 @click.argument("message")
 @click.argument("signature")
-def verify_message(message, signature):
+def verify_message(cli_ctx, message, signature):
+    from eth_account.account import Account
+    from eth_account.messages import encode_defunct
+
     eip191message = encode_defunct(text=message)
 
     try:
@@ -164,5 +185,9 @@ def verify_message(message, signature):
         message = "Message cannot be verified. Check the signature and try again."
         raise LedgerSigningError(message) from exc
 
-    alias = accounts[signer_address].alias if signer_address in accounts else ""
+    alias = (
+        cli_ctx.account_manager[signer_address].alias
+        if signer_address in cli_ctx.account_manager
+        else ""
+    )
     click.echo(f"Signer: {signer_address}  {alias}")

ape_ledger/choices.py

@@ -1,11 +1,13 @@
-from typing import Any, Optional, Union
+from typing import TYPE_CHECKING, Any, Optional, Union
 
 import click
 from ape.cli import PromptChoice
-from click import Context, Parameter
 
-from ape_ledger.client import get_device
-from ape_ledger.hdpath import HDAccountPath, HDBasePath
+if TYPE_CHECKING:
+    from click import Context, Parameter
+
+    from ape_ledger.client import LedgerDeviceClient
+    from ape_ledger.hdpath import HDAccountPath, HDBasePath
 
 
 class AddressPromptChoice(PromptChoice):
@@ -17,10 +19,12 @@ class AddressPromptChoice(PromptChoice):
 
     def __init__(
         self,
-        hd_path: Union[HDBasePath, str],
+        hd_path: Union["HDBasePath", str],
         index_offset: int = 0,
         page_size: int = DEFAULT_PAGE_SIZE,
     ):
+        from ape_ledger.hdpath import HDBasePath
+
         if isinstance(hd_path, str):
             hd_path = HDBasePath(base_path=hd_path)
 
@@ -58,7 +62,7 @@ def convert(
         self._choice_index = self._choice_index if address_index is None else address_index
         return address
 
-    def get_user_selected_account(self) -> tuple[str, HDAccountPath]:
+    def get_user_selected_account(self) -> tuple[str, "HDAccountPath"]:
         """Returns the selected address from the user along with the HD path.
         The user is able to page using special characters ``n`` and ``p``.
         """
@@ -69,7 +73,7 @@ def get_user_selected_account(self) -> tuple[str, HDAccountPath]:
 
             address = self._get_user_selection()
 
-        account_id = self._choice_index + self._index_offset
+        account_id = (self._choice_index or 0) + self._index_offset
         return address, self._hd_root_path.get_account_path(account_id)
 
     def _get_user_selection(self) -> str:
@@ -103,4 +107,11 @@ def _get_address(self, account_id: int) -> str:
         return device.get_address()
 
 
+def get_device(path: "HDAccountPath") -> "LedgerDeviceClient":
+    # Perf: lazy load so CLI-usage is faster and abstracted for testing purposes.
+    from ape_ledger.client import get_device as _get_device
+
+    return _get_device(path)
+
+
 __all__ = ["AddressPromptChoice"]

ape_ledger/client.py

@@ -1,5 +1,6 @@
 import atexit
 from functools import cached_property
+from typing import TYPE_CHECKING
 
 import hid  # type: ignore
 from ape.logging import LogLevel, logger
@@ -8,13 +9,14 @@
 from ledgereth.messages import sign_message, sign_typed_data_draft
 from ledgereth.transactions import SignedType2Transaction, create_transaction
 
-from ape_ledger.hdpath import HDAccountPath
+if TYPE_CHECKING:
+    from ape_ledger.hdpath import HDAccountPath
 
 
 class DeviceFactory:
     device_map: dict[str, "LedgerDeviceClient"] = {}
 
-    def create_device(self, account: HDAccountPath):
+    def create_device(self, account: "HDAccountPath"):
         if account.path in self.device_map:
             return self.device_map[account.path]
 
@@ -36,7 +38,7 @@ def get_dongle(debug: bool = False, reopen_on_fail: bool = True) -> HIDDongleHID
         raise  # the OSError
 
 class LedgerDeviceClient:
-    def __init__(self, account: HDAccountPath):
+    def __init__(self, account: "HDAccountPath"):
         self._account = account.path.lstrip("m/")
 
     @cached_property
@@ -80,5 +82,5 @@ def sign_transaction(self, txn: dict) -> tuple[int, int, int]:
 _device_factory = DeviceFactory()
 
 
-def get_device(account: HDAccountPath):
+def get_device(account: "HDAccountPath") -> LedgerDeviceClient:
     return _device_factory.create_device(account)

docs/conf.py

@@ -0,0 +1 @@
+extensions = ["sphinx_ape"]

docs/index.rst

@@ -0,0 +1 @@
+.. dynamic-toc-tree::

docs/userguides/quickstart.md

@@ -0,0 +1,2 @@
+```{include} ../../README.md
+```