Rework FallbackProvider

docs/api.rst

@@ -25,12 +25,15 @@ Providers
 .. autoclass:: HTTPProvider
    :show-inheritance:
 
+.. autoclass:: ProviderPath
+
 
 Fallback providers
 ------------------
 
 .. autoclass:: FallbackProvider
    :show-inheritance:
+   :members: errors
 
 .. autoclass:: CycleFallback
    :show-inheritance:
@@ -148,7 +151,7 @@ Testing utilities
    :show-inheritance:
    :members: disable_auto_mine_transactions, enable_auto_mine_transactions, take_snapshot, revert_to_snapshot
 
-.. autoclass:: SnapshotID
+.. autoclass:: SnapshotID()
 
 .. autoclass:: HTTPProviderServer
    :members:
@@ -266,11 +269,11 @@ Compiled and deployed contracts
 Filter objects
 --------------
 
-.. autoclass:: pons._client_rpc.BlockFilter()
+.. autoclass:: pons.BlockFilter()
 
-.. autoclass:: pons._client_rpc.PendingTransactionFilter()
+.. autoclass:: pons.PendingTransactionFilter()
 
-.. autoclass:: pons._client_rpc.LogFilter()
+.. autoclass:: pons.LogFilter()
 
 
 Solidity types

docs/changelog.rst

@@ -12,6 +12,8 @@ Changed
 - Renamed ``id_`` fields of ``BlockFilter``, ``PendingTransactionFilter``, and ``LogFilter`` to just ``id``. (PR_82_)
 - Split out ``http-provider-server`` feature from ``local-provider``. (PR_82_)
 - ``RemoteError`` removed. (PR_82_)
+- The internal structure of ``BlockFilter``, ``LogFilter``, and ``PendingTransactionFilter`` is now undocumented. (PR_87_)
+- The path returned by ``Provider.rpc_and_pin()`` is now a ``ProviderPath`` object. (PR_87_)
 
 
 Added
@@ -23,12 +25,15 @@ Added
 - Exporting ``HTTPError`` and ``BadResponseFormat``. (PR_82_)
 - Exporting ``InvalidResponse``. (PR_86_)
 - ``LocalProvider.root`` is now of type ``AccountSigner`` instead of ``Signer``. (PR_86_)
+- ``FallbackProvider`` now records encountered errors, and they can be accessed via the ``errors()`` method. (PR_87_)
+- ``BlockFilter``, ``LogFilter``, and ``PendingTransactionFilter`` are exported from the top level. (PR_87_)
 
 
 .. _PR_81: https://github.com/fjarri-eth/pons/pull/81
 .. _PR_82: https://github.com/fjarri-eth/pons/pull/82
 .. _PR_84: https://github.com/fjarri-eth/pons/pull/84
 .. _PR_86: https://github.com/fjarri-eth/pons/pull/86
+.. _PR_87: https://github.com/fjarri-eth/pons/pull/87
 
 
 0.8.1 (2024-11-12)

docs/conf.py

@@ -47,6 +47,11 @@
 
 autoclass_content = "both"
 autodoc_member_order = "groupwise"
+autodoc_default_options = {
+    #'members': True,
+    "undoc-members": False,
+    #'show-inheritance': True,
+}
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = []

pons/__init__.py

@@ -10,7 +10,14 @@
     ContractPanic,
     TransactionFailed,
 )
-from ._client_rpc import BadResponseFormat, ClientSessionRPC, ProviderError
+from ._client_rpc import (
+    BadResponseFormat,
+    BlockFilter,
+    ClientSessionRPC,
+    LogFilter,
+    PendingTransactionFilter,
+    ProviderError,
+)
 from ._compiler import EVMVersion, compile_contract_file
 from ._contract import (
     BaseBoundMethodCall,
@@ -54,6 +61,7 @@
     InvalidResponse,
     ProtocolError,
     Provider,
+    ProviderPath,
     Unreachable,
 )
 from ._signer import AccountSigner, Signer
@@ -65,6 +73,7 @@
     "AccountSigner",
     "BadResponseFormat",
     "BaseBoundMethodCall",
+    "BlockFilter",
     "BoundConstructor",
     "BoundConstructorCall",
     "BoundEvent",
@@ -99,15 +108,18 @@
     "HTTPProviderServer",
     "InvalidResponse",
     "LocalProvider",
+    "LogFilter",
     "Method",
     "MethodCall",
     "MultiMethod",
     "Multicall",
     "Mutability",
+    "PendingTransactionFilter",
     "PriorityFallback",
     "ProtocolError",
     "Provider",
     "ProviderError",
+    "ProviderPath",
     "Receive",
     "Signer",
     "SnapshotID",

pons/_client_rpc.py

@@ -26,25 +26,43 @@
 
 from ._contract import BaseBoundMethodCall
 from ._contract_abi import EventFilter
-from ._provider import InvalidResponse, ProviderSession
+from ._provider import InvalidResponse, ProviderPath, ProviderSession
 
 
 @dataclass
 class BlockFilter:
+    """
+    A block filter created on a remote provider.
+
+    Expires after some time subject to the provider's settings.
+    """
+
     id: int
-    provider_path: tuple[int, ...]
+    provider_path: ProviderPath
 
 
 @dataclass
 class PendingTransactionFilter:
+    """
+    A pending transaction filter created on a remote provider.
+
+    Expires after some time subject to the provider's settings.
+    """
+
     id: int
-    provider_path: tuple[int, ...]
+    provider_path: ProviderPath
 
 
 @dataclass
 class LogFilter:
+    """
+    A log filter created on a remote provider.
+
+    Expires after some time subject to the provider's settings.
+    """
+
     id: int
-    provider_path: tuple[int, ...]
+    provider_path: ProviderPath
 
 
 class BadResponseFormat(Exception):
@@ -116,7 +134,7 @@ async def rpc_call(
 
 async def rpc_call_pin(
     provider_session: ProviderSession, method_name: str, ret_type: type[RetType], *args: Any
-) -> tuple[RetType, tuple[int, ...]]:
+) -> tuple[RetType, ProviderPath]:
     """Catches various response formatting errors and returns them in a unified way."""
     with convert_errors(method_name):
         result, provider_path = await provider_session.rpc_and_pin(
@@ -127,7 +145,7 @@ async def rpc_call_pin(
 
 async def rpc_call_at_pin(
     provider_session: ProviderSession,
-    provider_path: tuple[int, ...],
+    provider_path: ProviderPath,
     method_name: str,
     ret_type: type[RetType],
     *args: Any,