py-geth 4.2.0__py3-none-any.whl → 5.2.0__py3-none-any.whl

geth/reset.py

@@ -1,5 +1,23 @@
+from __future__ import (
+    annotations,
+)
+
 import os
 
+from typing_extensions import (
+    Unpack,
+)
+
+from geth.exceptions import (
+    PyGethValueError,
+)
+from geth.types import (
+    GethKwargsTypedDict,
+)
+from geth.utils.validation import (
+    validate_geth_kwargs,
+)
+
 from .chains import (
     is_live_chain,
     is_testnet_chain,
@@ -9,47 +27,53 @@ from .utils.filesystem import (
     remove_file_if_exists,
 )
 from .wrapper import (
-    spawn_geth_subprocess,
+    spawn_geth,
 )
 
 
-def soft_reset_chain(allow_live=False, allow_testnet=False, **geth_kwargs):
+def soft_reset_chain(
+    allow_live: bool = False,
+    allow_testnet: bool = False,
+    **geth_kwargs: Unpack[GethKwargsTypedDict],
+) -> None:
+    validate_geth_kwargs(geth_kwargs)
     data_dir = geth_kwargs.get("data_dir")
 
     if data_dir is None or (not allow_live and is_live_chain(data_dir)):
-        raise ValueError(
+        raise PyGethValueError(
             "To reset the live chain you must call this function with `allow_live=True`"
         )
 
     if not allow_testnet and is_testnet_chain(data_dir):
-        raise ValueError(
+        raise PyGethValueError(
             "To reset the testnet chain you must call this function with `allow_testnet=True`"  # noqa: E501
         )
 
-    suffix_args = geth_kwargs.pop("suffix_args", [])
+    suffix_args = geth_kwargs.pop("suffix_args") or []
     suffix_args.extend(("removedb",))
+    geth_kwargs.update({"suffix_args": suffix_args})
 
-    geth_kwargs["suffix_args"] = suffix_args
-
-    _, proc = spawn_geth_subprocess(**geth_kwargs)
+    _, proc = spawn_geth(geth_kwargs)
 
-    stdoutdata, stderrdata = proc.communicate("y")
+    stdoutdata, stderrdata = proc.communicate(b"y")
 
-    if "Removing chaindata" not in stdoutdata:
-        raise ValueError(
-            f"An error occurred while removing the chain:\n\nError:\n{stderrdata}\n\n"
-            f"Output:\n{stdoutdata}"
+    if "Removing chaindata" not in stdoutdata.decode():
+        raise PyGethValueError(
+            "An error occurred while removing the chain:\n\nError:\n"
+            f"{stderrdata.decode()}\n\nOutput:\n{stdoutdata.decode()}"
         )
 
 
-def hard_reset_chain(data_dir, allow_live=False, allow_testnet=False):
+def hard_reset_chain(
+    data_dir: str, allow_live: bool = False, allow_testnet: bool = False
+) -> None:
     if not allow_live and is_live_chain(data_dir):
-        raise ValueError(
+        raise PyGethValueError(
             "To reset the live chain you must call this function with `allow_live=True`"
         )
 
     if not allow_testnet and is_testnet_chain(data_dir):
-        raise ValueError(
+        raise PyGethValueError(
             "To reset the testnet chain you must call this function with `allow_testnet=True`"  # noqa: E501
         )
 

geth/types.py

@@ -0,0 +1,65 @@
+from __future__ import (
+    annotations,
+)
+
+from typing import (
+    IO,
+    Any,
+    Literal,
+    TypedDict,
+    Union,
+)
+
+IO_Any = Union[IO[Any], int, None]
+
+
+class GethKwargsTypedDict(TypedDict, total=False):
+    cache: str | None
+    data_dir: str | None
+    dev_mode: bool | None
+    gcmode: Literal["full", "archive"] | None
+    geth_executable: str | None
+    ipc_disable: bool | None
+    ipc_path: str | None
+    max_peers: str | None
+    network_id: str | None
+    nice: bool | None
+    no_discover: bool | None
+    password: bytes | str | None
+    port: str | None
+    preload: str | None
+    rpc_addr: str | None
+    rpc_api: str | None
+    rpc_cors_domain: str | None
+    rpc_enabled: bool | None
+    rpc_port: str | None
+    stdin: str | None
+    suffix_args: list[str] | None
+    suffix_kwargs: dict[str, str] | None
+    tx_pool_global_slots: str | None
+    tx_pool_lifetime: str | None
+    tx_pool_price_limit: str | None
+    verbosity: str | None
+    ws_addr: str | None
+    ws_api: str | None
+    ws_enabled: bool | None
+    ws_origins: str | None
+    ws_port: str | None
+
+
+class GenesisDataTypedDict(TypedDict, total=False):
+    alloc: dict[str, dict[str, Any]]
+    baseFeePerGas: str
+    blobGasUsed: str
+    coinbase: str
+    config: dict[str, Any]
+    difficulty: str
+    excessBlobGas: str
+    extraData: str
+    gasLimit: str
+    gasUsed: str
+    mixHash: str
+    nonce: str
+    number: str
+    parentHash: str
+    timestamp: str

geth/utils/encoding.py

@@ -1,41 +1,53 @@
-import codecs
-
-binary_types = (bytes, bytearray)
-text_types = (str,)
-string_types = (bytes, str, bytearray)
-
-
-def is_binary(value):
-    return isinstance(value, binary_types)
+from __future__ import (
+    annotations,
+)
 
+import codecs
+from typing import (
+    Any,
+)
 
-def is_text(value):
-    return isinstance(value, text_types)
+from geth.exceptions import (
+    PyGethTypeError,
+)
 
 
-def is_string(value):
-    return isinstance(value, string_types)
+def is_string(value: Any) -> bool:
+    return isinstance(value, (bytes, bytearray, str))
 
 
-def force_bytes(value, encoding="iso-8859-1"):
-    if is_binary(value):
+def force_bytes(value: bytes | bytearray | str, encoding: str = "iso-8859-1") -> bytes:
+    if isinstance(value, bytes):
+        return value
+    elif isinstance(value, bytearray):
         return bytes(value)
-    elif is_text(value):
-        return codecs.encode(value, encoding)
+    elif isinstance(value, str):
+        encoded = codecs.encode(value, encoding)
+        if isinstance(encoded, (bytes, bytearray)):
+            return encoded
+        else:
+            raise PyGethTypeError(
+                f"Encoding {encoding!r} produced non-binary result: {encoded!r}"
+            )
     else:
-        raise TypeError(f"Unsupported type: {type(value)}")
+        raise PyGethTypeError(
+            f"Unsupported type: {type(value)}, expected bytes, bytearray or str"
+        )
 
 
-def force_text(value, encoding="iso-8859-1"):
-    if is_text(value):
-        return value
-    elif is_binary(value):
+def force_text(value: bytes | bytearray | str, encoding: str = "iso-8859-1") -> str:
+    if isinstance(value, (bytes, bytearray)):
         return codecs.decode(value, encoding)
+    elif isinstance(value, str):
+        return value
     else:
-        raise TypeError(f"Unsupported type: {type(value)}")
+        raise PyGethTypeError(
+            f"Unsupported type: {type(value)}, "
+            "expected value to be bytes, bytearray or str"
+        )
 
 
-def force_obj_to_text(obj):
+def force_obj_to_text(obj: Any) -> Any:
     if is_string(obj):
         return force_text(obj)
     elif isinstance(obj, dict):

geth/utils/filesystem.py

@@ -1,19 +1,12 @@
-import errno
 import os
 import shutil
 
 
-def mkdir(path):
-    try:
-        os.makedirs(path)
-    except OSError as exc:  # Python >2.5
-        if exc.errno == errno.EEXIST and os.path.isdir(path):
-            pass
-        else:
-            raise
+def mkdir(path: str) -> None:
+    os.makedirs(path, exist_ok=True)
 
 
-def ensure_path_exists(dir_path):
+def ensure_path_exists(dir_path: str) -> bool:
     """
     Make sure that a path exists
     """
@@ -23,22 +16,22 @@ def ensure_path_exists(dir_path):
     return False
 
 
-def remove_file_if_exists(path):
+def remove_file_if_exists(path: str) -> bool:
     if os.path.isfile(path):
         os.remove(path)
         return True
     return False
 
 
-def remove_dir_if_exists(path):
+def remove_dir_if_exists(path: str) -> bool:
     if os.path.isdir(path):
         shutil.rmtree(path)
         return True
     return False
 
 
-def is_executable_available(program):
-    def is_exe(fpath):
+def is_executable_available(program: str) -> bool:
+    def is_exe(fpath: str) -> bool:
         return os.path.isfile(fpath) and os.access(fpath, os.X_OK)
 
     fpath = os.path.dirname(program)
@@ -55,7 +48,7 @@ def is_executable_available(program):
     return False
 
 
-def is_same_path(p1, p2):
+def is_same_path(p1: str, p2: str) -> bool:
     n_p1 = os.path.abspath(os.path.expanduser(p1))
     n_p2 = os.path.abspath(os.path.expanduser(p2))
 

geth/utils/networking.py

@@ -1,17 +1,24 @@
 import contextlib
 import socket
 import time
+from typing import (
+    Generator,
+)
+
+from geth.exceptions import (
+    PyGethValueError,
+)
 
 from .timeout import (
     Timeout,
 )
 
 
-def is_port_open(port):
+def is_port_open(port: int) -> bool:
     sock = socket.socket()
     try:
         sock.bind(("127.0.0.1", port))
-    except socket.error:
+    except OSError:
         return False
     else:
         return True
@@ -19,7 +26,7 @@ def is_port_open(port):
         sock.close()
 
 
-def get_open_port():
+def get_open_port() -> str:
     sock = socket.socket()
     sock.bind(("127.0.0.1", 0))
     port = sock.getsockname()[1]
@@ -28,7 +35,9 @@ def get_open_port():
 
 
 @contextlib.contextmanager
-def get_ipc_socket(ipc_path, timeout=0.1):
+def get_ipc_socket(
+    ipc_path: str, timeout: float = 0.1
+) -> Generator[socket.socket, None, None]:
     sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
     sock.connect(ipc_path)
     sock.settimeout(timeout)
@@ -38,7 +47,7 @@ def get_ipc_socket(ipc_path, timeout=0.1):
     sock.close()
 
 
-def wait_for_http_connection(port, timeout=5):
+def wait_for_http_connection(port: int, timeout: int = 5) -> None:
     with Timeout(timeout) as _timeout:
         while True:
             s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
@@ -52,4 +61,7 @@ def wait_for_http_connection(port, timeout=5):
             else:
                 break
         else:
-            raise ValueError("Unable to establish HTTP connection")
+            raise PyGethValueError(
+                "Unable to establish HTTP connection, "
+                f"timed out after {timeout} seconds"
+            )

geth/utils/proc.py

@@ -1,12 +1,20 @@
+from __future__ import (
+    annotations,
+)
+
 import signal
+import subprocess
 import time
+from typing import (
+    AnyStr,
+)
 
 from .timeout import (
     Timeout,
 )
 
 
-def wait_for_popen(proc, timeout=30):
+def wait_for_popen(proc: subprocess.Popen[AnyStr], timeout: int = 30) -> None:
     try:
         with Timeout(timeout) as _timeout:
             while proc.poll() is None:
@@ -16,7 +24,7 @@ def wait_for_popen(proc, timeout=30):
         pass
 
 
-def kill_proc(proc):
+def kill_proc(proc: subprocess.Popen[AnyStr]) -> None:
     try:
         if proc.poll() is None:
             try:
@@ -43,7 +51,9 @@ def kill_proc(proc):
         proc.kill()
 
 
-def format_error_message(prefix, command, return_code, stdoutdata, stderrdata):
+def format_error_message(
+    prefix: str, command: list[str], return_code: int, stdoutdata: str, stderrdata: str
+) -> str:
     lines = [prefix]
 
     lines.append(f"Command    : {' '.join(command)}")

geth/utils/thread.py

@@ -1,7 +1,11 @@
 import threading
+from typing import (
+    Any,
+    Callable,
+)
 
 
-def spawn(target, *args, **kwargs):
+def spawn(target: Callable[..., Any], *args: Any, **kwargs: Any) -> threading.Thread:
     thread = threading.Thread(
         target=target,
         args=args,

geth/utils/timeout.py

@@ -1,4 +1,19 @@
+from __future__ import (
+    annotations,
+)
+
 import time
+from types import (
+    TracebackType,
+)
+from typing import (
+    Any,
+    Literal,
+)
+
+from geth.exceptions import (
+    PyGethValueError,
+)
 
 
 class Timeout(Exception):
@@ -11,43 +26,54 @@ class Timeout(Exception):
     begun_at = None
     is_running = None
 
-    def __init__(self, seconds=None, exception=None, *args, **kwargs):
+    def __init__(
+        self,
+        seconds: int | None = None,
+        exception: Any | None = None,
+        *args: Any,
+        **kwargs: Any,
+    ):
         self.seconds = seconds
         self.exception = exception
 
-    def __enter__(self):
+    def __enter__(self) -> Timeout:
         self.start()
         return self
 
-    def __exit__(self, exc_type, exc_val, exc_tb):
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        tb: TracebackType | None,
+    ) -> Literal[False]:
         return False
 
-    def __str__(self):
+    def __str__(self) -> str:
         if self.seconds is None:
             return ""
         return f"{self.seconds} seconds"
 
     @property
-    def expire_at(self):
+    def expire_at(self) -> float:
         if self.seconds is None:
-            raise ValueError(
+            raise PyGethValueError(
                 "Timeouts with `seconds == None` do not have an expiration time"
             )
         elif self.begun_at is None:
-            raise ValueError("Timeout has not been started")
+            raise PyGethValueError("Timeout has not been started")
         return self.begun_at + self.seconds
 
-    def start(self):
+    def start(self) -> None:
         if self.is_running is not None:
-            raise ValueError("Timeout has already been started")
+            raise PyGethValueError("Timeout has already been started")
         self.begun_at = time.time()
         self.is_running = True
 
-    def check(self):
+    def check(self) -> None:
         if self.is_running is None:
-            raise ValueError("Timeout has not been started")
+            raise PyGethValueError("Timeout has not been started")
         elif self.is_running is False:
-            raise ValueError("Timeout has already been cancelled")
+            raise PyGethValueError("Timeout has already been cancelled")
         elif self.seconds is None:
             return
         elif time.time() > self.expire_at:
@@ -59,5 +85,5 @@ class Timeout(Exception):
             else:
                 raise self
 
-    def cancel(self):
+    def cancel(self) -> None:
         self.is_running = False

geth/utils/validation.py

@@ -0,0 +1,179 @@
+from __future__ import (
+    annotations,
+)
+
+from typing import (
+    Any,
+    Literal,
+)
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    ValidationError,
+)
+
+from geth.exceptions import (
+    PyGethValueError,
+)
+from geth.types import (
+    GenesisDataTypedDict,
+    GethKwargsTypedDict,
+)
+
+
+class GethKwargs(BaseModel):
+    cache: str | None = None
+    data_dir: str | None = None
+    dev_mode: bool | None = False
+    gcmode: Literal["full", "archive"] | None = None
+    geth_executable: str | None = None
+    ipc_disable: bool | None = None
+    ipc_path: str | None = None
+    max_peers: str | None = None
+    network_id: str | None = None
+    nice: bool | None = True
+    no_discover: bool | None = None
+    password: bytes | str | None = None
+    port: str | None = None
+    preload: str | None = None
+    rpc_addr: str | None = None
+    rpc_api: str | None = None
+    rpc_cors_domain: str | None = None
+    rpc_enabled: bool | None = None
+    rpc_port: str | None = None
+    stdin: str | None = None
+    suffix_args: list[str] | None = None
+    suffix_kwargs: dict[str, str] | None = None
+    tx_pool_global_slots: str | None = None
+    tx_pool_lifetime: str | None = None
+    tx_pool_price_limit: str | None = None
+    verbosity: str | None = None
+    ws_addr: str | None = None
+    ws_api: str | None = None
+    ws_enabled: bool | None = None
+    ws_origins: str | None = None
+    ws_port: str | None = None
+
+    model_config = ConfigDict(extra="forbid")
+
+
+def validate_geth_kwargs(geth_kwargs: GethKwargsTypedDict) -> None:
+    """
+    Converts geth_kwargs to GethKwargs and raises a ValueError if the conversion fails.
+    """
+    try:
+        GethKwargs(**geth_kwargs)
+    except ValidationError as e:
+        raise PyGethValueError(f"geth_kwargs validation failed: {e}")
+    except TypeError as e:
+        raise PyGethValueError(f"error while validating geth_kwargs: {e}")
+
+
+class GenesisDataConfig(BaseModel):
+    chainId: int = 0
+    ethash: dict[str, Any] = {}  # so that geth treats config as PoW -> PoS transition
+    homesteadBlock: int = 0
+    daoForkBlock: int = 0
+    daoForkSupport: bool = True
+    eip150Block: int = 0
+    eip155Block: int = 0
+    eip158Block: int = 0
+    byzantiumBlock: int = 0
+    constantinopleBlock: int = 0
+    petersburgBlock: int = 0
+    istanbulBlock: int = 0
+    berlinBlock: int = 0
+    londonBlock: int = 0
+    arrowGlacierBlock: int = 0
+    grayGlacierBlock: int = 0
+    # merge
+    terminalTotalDifficulty: int = 0
+    terminalTotalDifficultyPassed: bool = True
+    # post-merge, timestamp is used for network transitions
+    shanghaiTime: int = 0
+    cancunTime: int = 0
+
+    model_config = ConfigDict(extra="forbid")
+
+
+class GenesisData(BaseModel):
+    alloc: dict[str, dict[str, Any]] = {}
+    baseFeePerGas: str = "0x0"
+    blobGasUsed: str = "0x0"
+    coinbase: str = "0x3333333333333333333333333333333333333333"
+    config: dict[str, Any] = GenesisDataConfig().model_dump()
+    difficulty: str = "0x0"
+    excessBlobGas: str = "0x0"
+    extraData: str = (
+        "0x0000000000000000000000000000000000000000000000000000000000000000"
+    )
+    gasLimit: str = "0x47e7c4"
+    gasUsed: str = "0x0"
+    mixHash: str = "0x0000000000000000000000000000000000000000000000000000000000000000"
+    nonce: str = "0x0"
+    number: str = "0x0"
+    parentHash: str = (
+        "0x0000000000000000000000000000000000000000000000000000000000000000"
+    )
+    timestamp: str = "0x0"
+
+    model_config = ConfigDict(extra="forbid")
+
+
+def validate_genesis_data(genesis_data: GenesisDataTypedDict) -> None:
+    """
+    Validates the genesis data
+    """
+    try:
+        GenesisData(**genesis_data)
+    except ValidationError as e:
+        raise PyGethValueError(f"genesis_data validation failed: {e}")
+    except TypeError as e:
+        raise PyGethValueError(f"error while validating genesis_data: {e}")
+
+    """
+    Validates the genesis data config field
+    """
+    genesis_data_config = genesis_data.get("config", None)
+    if genesis_data_config:
+        try:
+            GenesisDataConfig(**genesis_data_config)
+        except ValidationError as e:
+            raise PyGethValueError(f"genesis_data config field validation failed: {e}")
+        except TypeError as e:
+            raise PyGethValueError(
+                f"error while validating genesis_data config field: {e}"
+            )
+
+
+def fill_default_genesis_data(
+    genesis_data: GenesisDataTypedDict,
+) -> GenesisData:
+    """
+    Fills in default values for the genesis data
+    """
+    try:
+        genesis_data_filled = GenesisData(**genesis_data)
+    except ValidationError as e:
+        raise PyGethValueError(
+            f"genesis_data validation failed while filling defaults: {e}"
+        )
+    except TypeError as e:
+        raise PyGethValueError(f"error while filling default genesis_data: {e}")
+
+    if genesis_data.get("config"):
+        try:
+            genesis_data_config_filled = GenesisDataConfig(**genesis_data["config"])
+        except ValidationError as e:
+            raise PyGethValueError(
+                f"genesis_data validation failed while filling config defaults: {e}"
+            )
+        except TypeError as e:
+            raise PyGethValueError(
+                f"error while filling default genesis_data config: {e}"
+            )
+
+        genesis_data_filled.config = genesis_data_config_filled.model_dump()
+
+    return genesis_data_filled