fastweb3 0.1.0__tar.gz

fastweb3-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iamdefinitelyahuman
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastweb3-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: fastweb3
+Version: 0.1.0
+Summary: High-performance Web3 client with batching and latency optimization.
+Author: iamdefinitelyahuman
+License: MIT
+Project-URL: Homepage, https://github.com/iamdefinitelyahuman/fastweb3
+Project-URL: Repository, https://github.com/iamdefinitelyahuman/fastweb3
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Requires-Dist: lazy-object-proxy>=1.12.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: ruff>=0.9; extra == "dev"
+Requires-Dist: pre-commit>=3; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: mkdocs>=1.6; extra == "dev"
+Requires-Dist: mkdocs-material>=9.5; extra == "dev"
+Requires-Dist: websocket-client>=1.6; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Provides-Extra: wss
+Requires-Dist: websocket-client>=1.6; extra == "wss"
+Dynamic: license-file
+
+# fastweb3
+
+High-performance Web3 client.
+
+**NOTE**: This library is still in early alpha development. Prior to a `v1.0.0` (which may never come), expect breaking changes and no backward compatibility between versions.
+
+## Installation
+
+You can install the latest release via `pip`:
+
+```bash
+pip install fastweb3
+```
+
+Or clone the repository for the most up-to-date version:
+
+```bash
+git clone https://github.com/iamdefinitelyahuman/fastweb3.git
+cd fastweb3
+pip install -e .
+```
+
+## Features
+
+### Automatic public RPC discovery and pooling
+
+`fastweb3` queries a [list of public RPC endpoints](https://github.com/ethereum-lists/chains), maintains a pool of useable nodes, distributes requests between them, and reroutes failed requests. Users can rely on public infrastructure without thinking about timeouts, rate limiting, nodes falling out of sync, etc.
+
+```py
+>>> from fastweb3 import Web3
+
+# only a chainId is needed to connect
+>>> w3 = Web3(1)
+
+# the object immediately begins querying endpoints to check availability and latency
+# the best nodes are selected to be used in an "active pool"
+>>> w3.active_pool_size()
+6
+
+# we continue to monitor all known good endpoints, in case we have issues with any
+# member of the active pool
+>>> w3.pool_capacity()
+11
+```
+
+Users with their own RPC can target it as their primary endpoint. This endpoint is then favored for write methods, but read methods continue to be distributed amongst the node pool.
+
+```py
+>>> w3 = Web3(1, primary_endpoint=["my.local.node"])
+```
+
+### Deferred Execution
+
+RPC calls return [`Proxy`](github.com/ionelmc/python-lazy-object-proxy) objects immediately, while network I/O happens in the background.
+
+```py
+>>> amount = w3.eth.get_balance('0xd8da6bf26964af9d7eed9e03e53415d37aa96045')
+>>> amount
+<Proxy at 0x7b9ac0764a40 of object ... >
+>>> print(amount)
+32131215082101779377
+```
+
+### Simple Batching Semantics
+
+Batching uses natural syntax. With a context manager open, each requests is queued in the same batch until one of the `Proxy` objects is read, at which point the entire request is processed. This also guarantees queried values are all read from the same block.
+
+```py
+>>> with w3.batch_requests():
+...     a = w3.eth.get_balance("0xd8da6bf26964af9d7eed9e03e53415d37aa96045")
+...     b = w3.eth.get_balance("0x1db3439a222c519ab44bb1144fc28167b4fa6ee6")
+...     # both eth_getBalance queries are sent in the same batched request
+...     print(a + b)
+...
+32840401623804415458
+```
+
+## Tests
+
+First, install the dev dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+To run the test suite:
+
+```bash
+pytest
+```
+
+## License
+
+This project is licensed under the [MIT license](LICENSE).

fastweb3-0.1.0/README.md

@@ -0,0 +1,94 @@
+# fastweb3
+
+High-performance Web3 client.
+
+**NOTE**: This library is still in early alpha development. Prior to a `v1.0.0` (which may never come), expect breaking changes and no backward compatibility between versions.
+
+## Installation
+
+You can install the latest release via `pip`:
+
+```bash
+pip install fastweb3
+```
+
+Or clone the repository for the most up-to-date version:
+
+```bash
+git clone https://github.com/iamdefinitelyahuman/fastweb3.git
+cd fastweb3
+pip install -e .
+```
+
+## Features
+
+### Automatic public RPC discovery and pooling
+
+`fastweb3` queries a [list of public RPC endpoints](https://github.com/ethereum-lists/chains), maintains a pool of useable nodes, distributes requests between them, and reroutes failed requests. Users can rely on public infrastructure without thinking about timeouts, rate limiting, nodes falling out of sync, etc.
+
+```py
+>>> from fastweb3 import Web3
+
+# only a chainId is needed to connect
+>>> w3 = Web3(1)
+
+# the object immediately begins querying endpoints to check availability and latency
+# the best nodes are selected to be used in an "active pool"
+>>> w3.active_pool_size()
+6
+
+# we continue to monitor all known good endpoints, in case we have issues with any
+# member of the active pool
+>>> w3.pool_capacity()
+11
+```
+
+Users with their own RPC can target it as their primary endpoint. This endpoint is then favored for write methods, but read methods continue to be distributed amongst the node pool.
+
+```py
+>>> w3 = Web3(1, primary_endpoint=["my.local.node"])
+```
+
+### Deferred Execution
+
+RPC calls return [`Proxy`](github.com/ionelmc/python-lazy-object-proxy) objects immediately, while network I/O happens in the background.
+
+```py
+>>> amount = w3.eth.get_balance('0xd8da6bf26964af9d7eed9e03e53415d37aa96045')
+>>> amount
+<Proxy at 0x7b9ac0764a40 of object ... >
+>>> print(amount)
+32131215082101779377
+```
+
+### Simple Batching Semantics
+
+Batching uses natural syntax. With a context manager open, each requests is queued in the same batch until one of the `Proxy` objects is read, at which point the entire request is processed. This also guarantees queried values are all read from the same block.
+
+```py
+>>> with w3.batch_requests():
+...     a = w3.eth.get_balance("0xd8da6bf26964af9d7eed9e03e53415d37aa96045")
+...     b = w3.eth.get_balance("0x1db3439a222c519ab44bb1144fc28167b4fa6ee6")
+...     # both eth_getBalance queries are sent in the same batched request
+...     print(a + b)
+...
+32840401623804415458
+```
+
+## Tests
+
+First, install the dev dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+To run the test suite:
+
+```bash
+pytest
+```
+
+## License
+
+This project is licensed under the [MIT license](LICENSE).

fastweb3-0.1.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "fastweb3"
+version = "0.1.0"
+description = "High-performance Web3 client with batching and latency optimization."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [
+    { name = "iamdefinitelyahuman" }
+]
+
+dependencies = [
+    "httpx>=0.27",
+    "lazy-object-proxy>=1.12.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8",
+    "pytest-cov>=5",
+    "ruff>=0.9",
+    "pre-commit>=3",
+    "build",
+    "twine",
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "websocket-client>=1.6",
+]
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+]
+wss = ["websocket-client>=1.6"]
+
+[project.urls]
+Homepage = "https://github.com/iamdefinitelyahuman/fastweb3"
+Repository = "https://github.com/iamdefinitelyahuman/fastweb3"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+
+[tool.pytest.ini_options]
+addopts = [
+  "--cov=fastweb3",
+  "--cov-report=term-missing",
+  "--cov-report=xml",
+]
+testpaths = ["tests"]

fastweb3-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

fastweb3-0.1.0/src/fastweb3/__init__.py

@@ -0,0 +1,12 @@
+"""fastweb3 - High-performance Web3 client."""
+
+from .errors import FastWeb3Error, RPCError, TransportError
+from .web3 import Web3, Web3Config
+
+__all__ = [
+    "Web3",
+    "Web3Config",
+    "FastWeb3Error",
+    "RPCError",
+    "TransportError",
+]

fastweb3-0.1.0/src/fastweb3/deferred.py

@@ -0,0 +1,216 @@
+"""Deferred values used for optional background execution.
+
+This module provides a small primitive for returning proxy objects whose value
+is computed later.
+
+The main entrypoint is `deferred_response()`, which returns a
+``lazy_object_proxy.Proxy`` that blocks on first access until the underlying
+value is ready.
+
+These utilities are primarily used internally (e.g., for batched JSON-RPC
+requests), but are designed to be safe under concurrent access.
+"""
+
+# src/fastweb3/deferred.py
+import threading
+import traceback
+from typing import Any, Callable, Optional
+
+from lazy_object_proxy import Proxy
+
+_UNSET = object()
+
+
+class Handle:
+    """Handle for a deferred value.
+
+    A `Handle` represents a value that will be produced later, either by
+    a background task or by a "ref" callback that runs on first access.
+
+    The handle stores either a final value or an exception. Consumers typically
+    do not use `Handle` directly; instead, use `deferred_response()`
+    which returns a proxy object backed by a handle.
+    """
+
+    def __init__(
+        self,
+        bg_func: Optional[Callable[["Handle"], None]] = None,
+        format_func: Optional[Callable[[Any], Any]] = None,
+        ref_func: Optional[Callable[["Handle"], None]] = None,
+    ) -> None:
+        """Create a new handle.
+
+        Exactly one of ``bg_func`` or ``ref_func`` must be provided.
+
+        Args:
+            bg_func: If provided, executed immediately in a background thread.
+                The function is responsible for eventually calling
+                `set_value()` or `set_exc()`.
+            format_func: Optional pure function applied to the raw value before
+                storing it. If ``format_func`` raises, the handle is marked as
+                failed and the exception is re-raised.
+            ref_func: If provided, executed at most once on first access of the
+                proxy *and only if* the value has not been set yet. This is
+                typically used to force a flush or otherwise ensure that a value
+                will be produced.
+
+        Raises:
+            ValueError: If neither ``bg_func`` nor ``ref_func`` is provided.
+        """
+        self.lock = threading.Lock()
+        self.event = threading.Event()
+
+        self._exc: Optional[BaseException] = None
+        self._value: Any = _UNSET
+
+        self._format_func = format_func
+        self._ref_func = ref_func
+        self._ref_ran = False
+
+        # Capture creation site (strip this __init__ frame)
+        self._created_stack = traceback.format_stack()[:-1]
+
+        if bg_func is not None:
+
+            def execute_in_background() -> None:
+                try:
+                    bg_func(self)
+                except BaseException as exc:
+                    self.set_exc(exc)
+                finally:
+                    self.event.set()
+
+            threading.Thread(target=execute_in_background, daemon=True).start()
+        else:
+            if ref_func is None:
+                raise ValueError("Must set one of bg_func, ref_func")
+            self.event.set()
+
+    def set_exc(self, exc: BaseException) -> None:
+        """Mark the handle as failed.
+
+        Args:
+            exc: The exception to store.
+
+        Notes:
+            The exception is annotated with a creation-site note the first time
+            it is stored.
+        """
+        self._add_creation_note(exc)
+        with self.lock:
+            if self._exc is None:
+                self._exc = exc
+
+    def set_value(self, raw_value: Any) -> None:
+        """Store the handle's final value.
+
+        Args:
+            raw_value: Raw value to store. If ``format_func`` was provided,
+                it is applied first.
+
+        Raises:
+            BaseException: Re-raises any exception produced by ``format_func``.
+            Exception: If the value was already set.
+        """
+        with self.lock:
+            if self._exc is not None:
+                raise self._exc
+            if self._value is not _UNSET:
+                raise Exception("Value already set")
+            format_func = self._format_func
+
+        try:
+            final_value = raw_value if format_func is None else format_func(raw_value)
+        except BaseException as exc:
+            self.set_exc(exc)
+            raise
+
+        with self.lock:
+            if self._exc is not None:
+                raise self._exc
+            if self._value is not _UNSET:
+                raise Exception("Value already set")
+            self._value = final_value
+
+    def _add_creation_note(self, exc: BaseException) -> None:
+        # Add exactly once per exception instance
+        if getattr(exc, "_fastweb3_creation_note", False):
+            return
+        setattr(exc, "_fastweb3_creation_note", True)
+
+        exc.add_note(
+            "Deferred value was created at (most recent call last):\n"
+            + "".join(self._created_stack)
+        )
+
+    def get_value(self) -> Any:
+        """Return the stored value, blocking until it is available.
+
+        Returns:
+            The resolved value.
+
+        Raises:
+            BaseException: If the handle resolved to an exception.
+            AttributeError: If the handle was resolved but no value was set.
+        """
+        self.event.wait()
+
+        # Fast-path: already resolved or already failed
+        with self.lock:
+            exc = self._exc
+            value = self._value
+            if exc is not None:
+                raise exc
+            if value is not _UNSET:
+                return value
+
+            # Decide whether to run ref (at most once)
+            if self._ref_func is None or self._ref_ran:
+                ref = None
+            else:
+                self._ref_ran = True
+                ref = self._ref_func
+
+        if ref is not None:
+            try:
+                ref(self)
+            except BaseException as exc:
+                self.set_exc(exc)
+                raise
+
+        # Re-check after ref
+        with self.lock:
+            exc = self._exc
+            value = self._value
+
+        if exc is not None:
+            raise exc
+
+        if value is _UNSET:
+            e = AttributeError("Deferred value was not set")
+            self._add_creation_note(e)
+            raise e
+
+        return value
+
+
+def deferred_response(
+    bg_func: Callable[[Handle], None],
+    *,
+    format_func: Optional[Callable[[Any], Any]] = None,
+    ref_func: Optional[Callable[[Handle], None]] = None,
+) -> Any:
+    """Return a proxy whose value is computed later.
+
+    Args:
+        bg_func: Background function that computes the value and calls
+            `Handle.set_value()` or `Handle.set_exc()`.
+        format_func: Optional formatter applied to the raw value.
+        ref_func: Optional callback that runs on first proxy access if the
+            value is not yet set.
+
+    Returns:
+        A ``lazy_object_proxy.Proxy`` that resolves to the final value.
+    """
+    h = Handle(bg_func, format_func=format_func, ref_func=ref_func)
+    return Proxy(h.get_value)