web3 7.6.1__py3-none-any.whl → 7.8.0__py3-none-any.whl

web3/types.py

@@ -36,13 +36,9 @@ from web3._utils.compat import (
 )
 
 if TYPE_CHECKING:
-    from web3.contract.async_contract import (  # noqa: F401
-        AsyncContractEvent,
-        AsyncContractFunction,
-    )
-    from web3.contract.contract import (  # noqa: F401
-        ContractEvent,
-        ContractFunction,
+    from web3.contract.base_contract import (
+        BaseContractEvent,
+        BaseContractFunction,
     )
     from web3.main import (  # noqa: F401
         AsyncWeb3,
@@ -262,6 +258,13 @@ EthSubscriptionParams = Union[
 RPCId = Optional[Union[int, str]]
 
 
+class RPCRequest(TypedDict, total=False):
+    id: RPCId
+    jsonrpc: Literal["2.0"]
+    method: RPCEndpoint
+    params: Any
+
+
 class RPCResponse(TypedDict, total=False):
     error: RPCError
     id: RPCId
@@ -273,11 +276,19 @@ class RPCResponse(TypedDict, total=False):
     params: EthSubscriptionParams
 
 
+EthSubscriptionResult = Union[
+    BlockData,  # newHeads
+    TxData,  # newPendingTransactions, full_transactions=True
+    HexBytes,  # newPendingTransactions, full_transactions=False
+    LogReceipt,  # logs
+    SyncProgress,  # syncing
+    GethSyncingSubscriptionResult,  # geth syncing
+]
+
+
 class FormattedEthSubscriptionResponse(TypedDict):
     subscription: HexStr
-    result: Union[
-        BlockData, TxData, LogReceipt, SyncProgress, GethSyncingSubscriptionResult
-    ]
+    result: EthSubscriptionResult
 
 
 class CreateAccessListResponse(TypedDict):
@@ -286,10 +297,13 @@ class CreateAccessListResponse(TypedDict):
 
 
 MakeRequestFn = Callable[[RPCEndpoint, Any], RPCResponse]
-MakeBatchRequestFn = Callable[[List[Tuple[RPCEndpoint, Any]]], List[RPCResponse]]
+MakeBatchRequestFn = Callable[
+    [List[Tuple[RPCEndpoint, Any]]], Union[List[RPCResponse], RPCResponse]
+]
 AsyncMakeRequestFn = Callable[[RPCEndpoint, Any], Coroutine[Any, Any, RPCResponse]]
 AsyncMakeBatchRequestFn = Callable[
-    [List[Tuple[RPCEndpoint, Any]]], Coroutine[Any, Any, List[RPCResponse]]
+    [List[Tuple[RPCEndpoint, Any]]],
+    Coroutine[Any, Any, Union[List[RPCResponse], RPCResponse]],
 ]
 
 
@@ -566,8 +580,8 @@ class GethWallet(TypedDict):
 
 # Contract types
 
-TContractFn = TypeVar("TContractFn", "ContractFunction", "AsyncContractFunction")
-TContractEvent = TypeVar("TContractEvent", "ContractEvent", "AsyncContractEvent")
+TContractFn = TypeVar("TContractFn", bound="BaseContractFunction")
+TContractEvent = TypeVar("TContractEvent", bound="BaseContractEvent")
 
 
 # Tracing types

web3/utils/__init__.py

@@ -42,6 +42,9 @@ from .caching import (
 from .exception_handling import (
     handle_offchain_lookup,
 )
+from .subscriptions import (
+    EthSubscription,
+)
 
 __all__ = [
     "abi_to_signature",
@@ -70,5 +73,6 @@ __all__ = [
     "async_handle_offchain_lookup",
     "RequestCacheValidationThreshold",
     "SimpleCache",
+    "EthSubscription",
     "handle_offchain_lookup",
 ]

web3/utils/subscriptions.py

@@ -0,0 +1,289 @@
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Coroutine,
+    Dict,
+    Generic,
+    List,
+    Optional,
+    Sequence,
+    TypeVar,
+    Union,
+)
+
+from eth_typing import (
+    Address,
+    ChecksumAddress,
+    HexStr,
+)
+from hexbytes import (
+    HexBytes,
+)
+
+from web3.exceptions import (
+    Web3AttributeError,
+    Web3ValueError,
+)
+from web3.types import (
+    BlockData,
+    FilterParams,
+    LogReceipt,
+    SyncProgress,
+    TxData,
+)
+
+if TYPE_CHECKING:
+    from web3 import (
+        AsyncWeb3,
+    )
+    from web3.providers.persistent.subscription_manager import (
+        SubscriptionManager,
+    )
+    from web3.types import EthSubscriptionResult  # noqa: F401
+
+
+TSubscriptionResult = TypeVar("TSubscriptionResult", bound="EthSubscriptionResult")
+TSubscription = TypeVar("TSubscription", bound="EthSubscription[Any]")
+
+
+class EthSubscriptionContext(Generic[TSubscription, TSubscriptionResult]):
+    def __init__(
+        self,
+        async_w3: "AsyncWeb3",
+        subscription: TSubscription,
+        result: TSubscriptionResult,
+        **kwargs: Any,
+    ) -> None:
+        self.async_w3 = async_w3
+        self.subscription = subscription
+        self.result = result
+        self.__dict__.update(kwargs)
+
+    def __getattr__(self, item: str) -> Any:
+        if item in self.__dict__:
+            return self.__dict__[item]
+        raise Web3AttributeError(
+            f"'{self.__class__.__name__}' object has no attribute '{item}'"
+        )
+
+
+EthSubscriptionHandler = Callable[
+    [EthSubscriptionContext[Any, Any]], Coroutine[Any, Any, None]
+]
+
+
+def handler_wrapper(
+    handler: Optional[EthSubscriptionHandler],
+) -> Optional[EthSubscriptionHandler]:
+    """Wrap the handler to add bookkeeping and context creation."""
+    if handler is None:
+        return None
+
+    async def wrapped_handler(
+        context: EthSubscriptionContext[TSubscription, TSubscriptionResult],
+    ) -> None:
+        sub = context.subscription
+        sub.handler_call_count += 1
+        sub.manager.total_handler_calls += 1
+        sub.manager.logger.debug(
+            f"Subscription handler called.\n"
+            f"    label: {sub.label}\n"
+            f"    call count: {sub.handler_call_count}\n"
+            f"    total handler calls: {sub.manager.total_handler_calls}"
+        )
+        await handler(context)
+
+    return wrapped_handler
+
+
+class EthSubscription(Generic[TSubscriptionResult]):
+    _id: HexStr = None
+    manager: "SubscriptionManager" = None
+
+    def __init__(
+        self: TSubscription,
+        subscription_params: Optional[Sequence[Any]] = None,
+        handler: Optional[EthSubscriptionHandler] = None,
+        handler_context: Optional[Dict[str, Any]] = None,
+        label: Optional[str] = None,
+    ) -> None:
+        self._subscription_params = subscription_params
+        self._handler = handler_wrapper(handler)
+        self._handler_context = handler_context or {}
+        self._label = label
+        self.handler_call_count = 0
+
+    @property
+    def _default_label(self) -> str:
+        return f"{self.__class__.__name__}{self.subscription_params}"
+
+    @classmethod
+    def _create_type_aware_subscription(
+        cls,
+        subscription_params: Optional[Sequence[Any]],
+        handler: Optional[EthSubscriptionHandler] = None,
+        handler_context: Optional[Dict[str, Any]] = None,
+        label: Optional[str] = None,
+    ) -> "EthSubscription[Any]":
+        subscription_type = subscription_params[0]
+        subscription_arg = (
+            subscription_params[1] if len(subscription_params) > 1 else None
+        )
+        if subscription_type == "newHeads":
+            return NewHeadsSubscription(
+                handler=handler, handler_context=handler_context, label=label
+            )
+        elif subscription_type == "logs":
+            subscription_arg = subscription_arg or {}
+            return LogsSubscription(
+                **subscription_arg,
+                handler=handler,
+                handler_context=handler_context,
+                label=label,
+            )
+        elif subscription_type == "newPendingTransactions":
+            subscription_arg = subscription_arg or False
+            return PendingTxSubscription(
+                full_transactions=subscription_arg,
+                handler=handler,
+                handler_context=handler_context,
+                label=label,
+            )
+        elif subscription_type == "syncing":
+            return SyncingSubscription(
+                handler=handler, handler_context=handler_context, label=label
+            )
+        else:
+            params = (
+                (subscription_type, subscription_arg)
+                if subscription_arg
+                else (subscription_type,)
+            )
+            return cls(
+                params,
+                handler=handler,
+                handler_context=handler_context,
+                label=label,
+            )
+
+    @property
+    def subscription_params(self) -> Sequence[Any]:
+        return self._subscription_params
+
+    @property
+    def label(self) -> str:
+        if not self._label:
+            self._label = self._default_label
+        return self._label
+
+    @property
+    def id(self) -> HexStr:
+        if not self._id:
+            raise Web3ValueError("No `id` found for subscription.")
+        return self._id
+
+    async def unsubscribe(self) -> bool:
+        return await self.manager.unsubscribe(self)
+
+
+LogsSubscriptionContext = EthSubscriptionContext[
+    "LogsSubscription", "EthSubscriptionResult"
+]
+LogsSubscriptionHandler = Callable[[LogsSubscriptionContext], Coroutine[Any, Any, None]]
+
+
+class LogsSubscription(EthSubscription[LogReceipt]):
+    def __init__(
+        self,
+        address: Optional[
+            Union[Address, ChecksumAddress, List[Address], List[ChecksumAddress]]
+        ] = None,
+        topics: Optional[List[HexStr]] = None,
+        handler: LogsSubscriptionHandler = None,
+        handler_context: Optional[Dict[str, Any]] = None,
+        label: Optional[str] = None,
+    ) -> None:
+        self.address = address
+        self.topics = topics
+
+        logs_filter: FilterParams = {}
+        if address:
+            logs_filter["address"] = address
+        if topics:
+            logs_filter["topics"] = topics
+        self.logs_filter = logs_filter
+
+        super().__init__(
+            subscription_params=("logs", logs_filter),
+            handler=handler,
+            handler_context=handler_context,
+            label=label,
+        )
+
+
+NewHeadsSubscriptionContext = EthSubscriptionContext["NewHeadsSubscription", BlockData]
+NewHeadsSubscriptionHandler = Callable[
+    [NewHeadsSubscriptionContext], Coroutine[Any, Any, None]
+]
+
+
+class NewHeadsSubscription(EthSubscription[BlockData]):
+    def __init__(
+        self,
+        label: Optional[str] = None,
+        handler: Optional[NewHeadsSubscriptionHandler] = None,
+        handler_context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(
+            subscription_params=("newHeads",),
+            handler=handler,
+            handler_context=handler_context,
+            label=label,
+        )
+
+
+PendingTxSubscriptionContext = EthSubscriptionContext[
+    "PendingTxSubscription", Union[HexBytes, TxData]
+]
+PendingTxSubscriptionHandler = Callable[
+    [PendingTxSubscriptionContext], Coroutine[Any, Any, None]
+]
+
+
+class PendingTxSubscription(EthSubscription[Union[HexBytes, TxData]]):
+    def __init__(
+        self,
+        full_transactions: bool = False,
+        label: Optional[str] = None,
+        handler: Optional[PendingTxSubscriptionHandler] = None,
+        handler_context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        self.full_transactions = full_transactions
+        super().__init__(
+            subscription_params=("newPendingTransactions", full_transactions),
+            handler=handler,
+            handler_context=handler_context,
+            label=label,
+        )
+
+
+SyncingSubscriptionContext = EthSubscriptionContext["SyncingSubscription", SyncProgress]
+SyncingSubscriptionHandler = Callable[
+    [SyncingSubscriptionContext], Coroutine[Any, Any, None]
+]
+
+
+class SyncingSubscription(EthSubscription[SyncProgress]):
+    def __init__(
+        self,
+        label: Optional[str] = None,
+        handler: Optional[SyncingSubscriptionHandler] = None,
+        handler_context: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        super().__init__(
+            subscription_params=("syncing",),
+            handler=handler,
+            handler_context=handler_context,
+            label=label,
+        )

{web3-7.6.1.dist-info → web3-7.8.0.dist-info}/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016-2024 The Ethereum Foundation
+Copyright (c) 2016-2025 The Ethereum Foundation
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{web3-7.6.1.dist-info → web3-7.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: web3
-Version: 7.6.1
+Version: 7.8.0
 Summary: web3: A Python library for interacting with Ethereum
 Home-page: https://github.com/ethereum/web3.py
 Author: The Ethereum Foundation
@@ -21,63 +21,75 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.8, <4
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: eth-abi >=5.0.1
-Requires-Dist: eth-account >=0.13.1
-Requires-Dist: eth-hash[pycryptodome] >=0.5.1
-Requires-Dist: eth-typing >=5.0.0
-Requires-Dist: eth-utils >=5.0.0
-Requires-Dist: hexbytes >=1.2.0
-Requires-Dist: aiohttp >=3.7.4.post0
-Requires-Dist: pydantic >=2.4.0
-Requires-Dist: requests >=2.23.0
-Requires-Dist: typing-extensions >=4.0.1
-Requires-Dist: types-requests >=2.0.0
-Requires-Dist: websockets <14.0.0,>=10.0.0
-Requires-Dist: pyunormalize >=15.0.0
-Requires-Dist: pywin32 >=223 ; platform_system == "Windows"
+Requires-Dist: eth-abi>=5.0.1
+Requires-Dist: eth-account>=0.13.1
+Requires-Dist: eth-hash[pycryptodome]>=0.5.1
+Requires-Dist: eth-typing>=5.0.0
+Requires-Dist: eth-utils>=5.0.0
+Requires-Dist: hexbytes>=1.2.0
+Requires-Dist: aiohttp>=3.7.4.post0
+Requires-Dist: pydantic>=2.4.0
+Requires-Dist: pywin32>=223; platform_system == "Windows"
+Requires-Dist: requests>=2.23.0
+Requires-Dist: typing-extensions>=4.0.1
+Requires-Dist: types-requests>=2.0.0
+Requires-Dist: websockets<14.0.0,>=10.0.0
+Requires-Dist: pyunormalize>=15.0.0
+Provides-Extra: tester
+Requires-Dist: eth-tester[py-evm]<0.13.0b1,>=0.12.0b1; extra == "tester"
+Requires-Dist: py-geth>=5.1.0; extra == "tester"
 Provides-Extra: dev
-Requires-Dist: build >=0.9.0 ; extra == 'dev'
-Requires-Dist: bumpversion >=0.5.3 ; extra == 'dev'
-Requires-Dist: ipython ; extra == 'dev'
-Requires-Dist: setuptools >=38.6.0 ; extra == 'dev'
-Requires-Dist: tqdm >4.32 ; extra == 'dev'
-Requires-Dist: twine >=1.13 ; extra == 'dev'
-Requires-Dist: wheel ; extra == 'dev'
-Requires-Dist: sphinx >=6.0.0 ; extra == 'dev'
-Requires-Dist: sphinx-autobuild >=2021.3.14 ; extra == 'dev'
-Requires-Dist: sphinx-rtd-theme >=1.0.0 ; extra == 'dev'
-Requires-Dist: towncrier <22,>=21 ; extra == 'dev'
-Requires-Dist: pytest-asyncio <0.23,>=0.18.1 ; extra == 'dev'
-Requires-Dist: pytest-mock >=1.10 ; extra == 'dev'
-Requires-Dist: pytest-xdist >=2.4.0 ; extra == 'dev'
-Requires-Dist: pytest >=7.0.0 ; extra == 'dev'
-Requires-Dist: flaky >=3.7.0 ; extra == 'dev'
-Requires-Dist: hypothesis >=3.31.2 ; extra == 'dev'
-Requires-Dist: tox >=4.0.0 ; extra == 'dev'
-Requires-Dist: mypy ==1.10.0 ; extra == 'dev'
-Requires-Dist: pre-commit >=3.4.0 ; extra == 'dev'
-Requires-Dist: eth-tester[py-evm] <0.13.0b1,>=0.12.0b1 ; extra == 'dev'
-Requires-Dist: py-geth >=5.1.0 ; extra == 'dev'
+Requires-Dist: build>=0.9.0; extra == "dev"
+Requires-Dist: bumpversion>=0.5.3; extra == "dev"
+Requires-Dist: ipython; extra == "dev"
+Requires-Dist: setuptools>=38.6.0; extra == "dev"
+Requires-Dist: tqdm>4.32; extra == "dev"
+Requires-Dist: twine>=1.13; extra == "dev"
+Requires-Dist: wheel; extra == "dev"
+Requires-Dist: sphinx>=6.0.0; extra == "dev"
+Requires-Dist: sphinx-autobuild>=2021.3.14; extra == "dev"
+Requires-Dist: sphinx_rtd_theme>=1.0.0; extra == "dev"
+Requires-Dist: towncrier<22,>=21; extra == "dev"
+Requires-Dist: pytest-asyncio<0.23,>=0.18.1; extra == "dev"
+Requires-Dist: pytest-mock>=1.10; extra == "dev"
+Requires-Dist: pytest-xdist>=2.4.0; extra == "dev"
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: flaky>=3.7.0; extra == "dev"
+Requires-Dist: hypothesis>=3.31.2; extra == "dev"
+Requires-Dist: tox>=4.0.0; extra == "dev"
+Requires-Dist: mypy==1.10.0; extra == "dev"
+Requires-Dist: pre-commit>=3.4.0; extra == "dev"
+Requires-Dist: eth-tester[py-evm]<0.13.0b1,>=0.12.0b1; extra == "dev"
+Requires-Dist: py-geth>=5.1.0; extra == "dev"
 Provides-Extra: docs
-Requires-Dist: sphinx >=6.0.0 ; extra == 'docs'
-Requires-Dist: sphinx-autobuild >=2021.3.14 ; extra == 'docs'
-Requires-Dist: sphinx-rtd-theme >=1.0.0 ; extra == 'docs'
-Requires-Dist: towncrier <22,>=21 ; extra == 'docs'
+Requires-Dist: sphinx>=6.0.0; extra == "docs"
+Requires-Dist: sphinx-autobuild>=2021.3.14; extra == "docs"
+Requires-Dist: sphinx_rtd_theme>=1.0.0; extra == "docs"
+Requires-Dist: towncrier<22,>=21; extra == "docs"
 Provides-Extra: test
-Requires-Dist: pytest-asyncio <0.23,>=0.18.1 ; extra == 'test'
-Requires-Dist: pytest-mock >=1.10 ; extra == 'test'
-Requires-Dist: pytest-xdist >=2.4.0 ; extra == 'test'
-Requires-Dist: pytest >=7.0.0 ; extra == 'test'
-Requires-Dist: flaky >=3.7.0 ; extra == 'test'
-Requires-Dist: hypothesis >=3.31.2 ; extra == 'test'
-Requires-Dist: tox >=4.0.0 ; extra == 'test'
-Requires-Dist: mypy ==1.10.0 ; extra == 'test'
-Requires-Dist: pre-commit >=3.4.0 ; extra == 'test'
-Requires-Dist: eth-tester[py-evm] <0.13.0b1,>=0.12.0b1 ; extra == 'test'
-Requires-Dist: py-geth >=5.1.0 ; extra == 'test'
-Provides-Extra: tester
-Requires-Dist: eth-tester[py-evm] <0.13.0b1,>=0.12.0b1 ; extra == 'tester'
-Requires-Dist: py-geth >=5.1.0 ; extra == 'tester'
+Requires-Dist: pytest-asyncio<0.23,>=0.18.1; extra == "test"
+Requires-Dist: pytest-mock>=1.10; extra == "test"
+Requires-Dist: pytest-xdist>=2.4.0; extra == "test"
+Requires-Dist: pytest>=7.0.0; extra == "test"
+Requires-Dist: flaky>=3.7.0; extra == "test"
+Requires-Dist: hypothesis>=3.31.2; extra == "test"
+Requires-Dist: tox>=4.0.0; extra == "test"
+Requires-Dist: mypy==1.10.0; extra == "test"
+Requires-Dist: pre-commit>=3.4.0; extra == "test"
+Requires-Dist: eth-tester[py-evm]<0.13.0b1,>=0.12.0b1; extra == "test"
+Requires-Dist: py-geth>=5.1.0; extra == "test"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
 
 # web3.py