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

geth/__init__.py

@@ -14,10 +14,20 @@ from .mixins import (
 )
 from .process import (
     DevGethProcess,
-    LiveGethProcess,
     MainnetGethProcess,
-    RopstenGethProcess,
+    SepoliaGethProcess,
     TestnetGethProcess,
 )
 
 __version__ = __version("py-geth")
+
+__all__ = (
+    "install_geth",
+    "get_geth_version",
+    "InterceptedStreamsMixin",
+    "LoggingMixin",
+    "MainnetGethProcess",
+    "SepoliaGethProcess",
+    "TestnetGethProcess",
+    "DevGethProcess",
+)

geth/accounts.py

@@ -1,6 +1,24 @@
+from __future__ import (
+    annotations,
+)
+
 import os
 import re
 
+from typing_extensions import (
+    Unpack,
+)
+
+from geth.exceptions import (
+    PyGethValueError,
+)
+from geth.types import (
+    GethKwargsTypedDict,
+)
+from geth.utils.validation import (
+    validate_geth_kwargs,
+)
+
 from .utils.proc import (
     format_error_message,
 )
@@ -9,29 +27,36 @@ from .wrapper import (
 )
 
 
-def get_accounts(data_dir, **geth_kwargs):
+def get_accounts(
+    **geth_kwargs: Unpack[GethKwargsTypedDict],
+) -> tuple[str, ...] | tuple[()]:
     """
     Returns all geth accounts as tuple of hex encoded strings
 
-    >>> geth_accounts()
+    >>> get_accounts(data_dir='some/data/dir')
     ... ('0x...', '0x...')
     """
-    command, proc = spawn_geth(
-        dict(data_dir=data_dir, suffix_args=["account", "list"], **geth_kwargs)
-    )
+    validate_geth_kwargs(geth_kwargs)
+
+    if not geth_kwargs.get("data_dir"):
+        raise PyGethValueError("data_dir is required to get accounts")
+
+    geth_kwargs["suffix_args"] = ["account", "list"]
+
+    command, proc = spawn_geth(geth_kwargs)
     stdoutdata, stderrdata = proc.communicate()
 
     if proc.returncode:
-        if "no keys in store" in stderrdata.decode("utf-8"):
+        if "no keys in store" in stderrdata.decode():
             return tuple()
         else:
-            raise ValueError(
+            raise PyGethValueError(
                 format_error_message(
                     "Error trying to list accounts",
                     command,
                     proc.returncode,
-                    stdoutdata,
-                    stderrdata,
+                    stdoutdata.decode(),
+                    stderrdata.decode(),
                 )
             )
     accounts = parse_geth_accounts(stdoutdata)
@@ -41,8 +66,8 @@ def get_accounts(data_dir, **geth_kwargs):
 account_regex = re.compile(b"([a-f0-9]{40})")
 
 
-def create_new_account(data_dir, password, **geth_kwargs):
-    """
+def create_new_account(**geth_kwargs: Unpack[GethKwargsTypedDict]) -> str:
+    r"""
     Creates a new Ethereum account on geth.
 
     This is useful for testing when you want to stress
@@ -57,11 +82,11 @@ def create_new_account(data_dir, password, **geth_kwargs):
     If geth process is already running you can create new
     accounts using
     `web3.personal.newAccount()
-    <https://github.com/ethereum/go-ethereum/wiki/JavaScript-Console#personalnewaccount>_`
-    RPC API.
+    <https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-personal>_`
 
+    RPC API.
 
-    Example py.test fixture for tests:
+    Example pytest fixture for tests:
 
     .. code-block:: python
 
@@ -92,59 +117,85 @@ def create_new_account(data_dir, password, **geth_kwargs):
             account = create_new_account(data_dir, DEFAULT_PASSWORD_PATH)
             return account
 
-    :param data_dir: Geth data fir path - where to keep "keystore" folder
-    :param password: Path to a file containing the password
-        for newly created account
-    :param geth_kwargs: Extra command line arguments password to geth
+    :param \**geth_kwargs:
+        Command line arguments to pass to geth. See below:
+
+    :Required Keyword Arguments:
+        * *data_dir* (``str``) --
+          Geth datadir path - where to keep "keystore" folder
+        * *password* (``str`` or ``bytes``) --
+          Password to use for the new account, either the password as bytes or a str
+          path to a file containing the password.
+
     :return: Account as 0x prefixed hex string
+    :rtype: str
     """
-    if os.path.exists(password):
-        geth_kwargs["password"] = password
+    if not geth_kwargs.get("data_dir"):
+        raise PyGethValueError("data_dir is required to create a new account")
+
+    if not geth_kwargs.get("password"):
+        raise PyGethValueError("password is required to create a new account")
 
-    command, proc = spawn_geth(
-        dict(data_dir=data_dir, suffix_args=["account", "new"], **geth_kwargs)
-    )
+    password = geth_kwargs.get("password")
 
-    if os.path.exists(password):
+    geth_kwargs.update({"suffix_args": ["account", "new"]})
+    validate_geth_kwargs(geth_kwargs)
+
+    if isinstance(password, str):
+        if not os.path.exists(password):
+            raise PyGethValueError(f"Password file not found at path: {password}")
+    elif not isinstance(password, bytes):
+        raise PyGethValueError(
+            "Password must be either a str (path to a file) or bytes"
+        )
+
+    command, proc = spawn_geth(geth_kwargs)
+
+    if isinstance(password, str):
         stdoutdata, stderrdata = proc.communicate()
     else:
         stdoutdata, stderrdata = proc.communicate(b"\n".join((password, password)))
 
     if proc.returncode:
-        raise ValueError(
+        raise PyGethValueError(
             format_error_message(
                 "Error trying to create a new account",
                 command,
                 proc.returncode,
-                stdoutdata,
-                stderrdata,
+                stdoutdata.decode(),
+                stderrdata.decode(),
             )
         )
 
     match = account_regex.search(stdoutdata)
     if not match:
-        raise ValueError(
+        raise PyGethValueError(
             format_error_message(
                 "Did not find an address in process output",
                 command,
                 proc.returncode,
-                stdoutdata,
-                stderrdata,
+                stdoutdata.decode(),
+                stderrdata.decode(),
             )
         )
 
-    return b"0x" + match.groups()[0]
+    return "0x" + match.groups()[0].decode()
+
 
+def ensure_account_exists(**geth_kwargs: Unpack[GethKwargsTypedDict]) -> str:
+    if not geth_kwargs.get("data_dir"):
+        raise PyGethValueError("data_dir is required to get accounts")
 
-def ensure_account_exists(data_dir, **geth_kwargs):
-    accounts = get_accounts(data_dir, **geth_kwargs)
+    validate_geth_kwargs(geth_kwargs)
+    accounts = get_accounts(**geth_kwargs)
     if not accounts:
-        account = create_new_account(data_dir, **geth_kwargs)
+        account = create_new_account(**geth_kwargs)
     else:
         account = accounts[0]
     return account
 
 
-def parse_geth_accounts(raw_accounts_output):
+def parse_geth_accounts(raw_accounts_output: bytes) -> tuple[str, ...]:
     accounts = account_regex.findall(raw_accounts_output)
-    return tuple(b"0x" + account for account in accounts)
+    accounts_set = set(accounts)  # remove duplicates
+    return tuple("0x" + account.decode() for account in accounts_set)

geth/chain.py

@@ -1,7 +1,23 @@
+from __future__ import (
+    annotations,
+)
+
 import json
 import os
+import subprocess
 import sys
 
+from typing_extensions import (
+    Unpack,
+)
+
+from geth.exceptions import (
+    PyGethValueError,
+)
+from geth.types import (
+    GenesisDataTypedDict,
+)
+
 from .utils.encoding import (
     force_obj_to_text,
 )
@@ -9,12 +25,16 @@ from .utils.filesystem import (
     ensure_path_exists,
     is_same_path,
 )
+from .utils.validation import (
+    fill_default_genesis_data,
+    validate_genesis_data,
+)
 from .wrapper import (
-    spawn_geth,
+    get_geth_binary_path,
 )
 
 
-def get_live_data_dir():
+def get_live_data_dir() -> str:
     """
     `py-geth` needs a base directory to store it's chain data.  By default this is
     the directory that `geth` uses as it's `datadir`.
@@ -46,124 +66,89 @@ def get_live_data_dir():
         )
 
     else:
-        raise ValueError(
-            (
-                f"Unsupported platform: '{sys.platform}'.  Only darwin/linux2/win32 are"
-                " supported.  You must specify the geth datadir manually"
-            )
+        raise PyGethValueError(
+            f"Unsupported platform: '{sys.platform}'.  Only darwin/linux2/win32 are"
+            " supported.  You must specify the geth datadir manually"
         )
     return data_dir
 
 
-def get_ropsten_data_dir():
+def get_sepolia_data_dir() -> str:
     return os.path.abspath(
         os.path.expanduser(
             os.path.join(
                 get_live_data_dir(),
-                "ropsten",
+                "sepolia",
             )
         )
     )
 
 
-def get_default_base_dir():
+def get_default_base_dir() -> str:
     return get_live_data_dir()
 
 
-def get_chain_data_dir(base_dir, name):
+def get_chain_data_dir(base_dir: str, name: str) -> str:
     data_dir = os.path.abspath(os.path.join(base_dir, name))
     ensure_path_exists(data_dir)
     return data_dir
 
 
-def get_genesis_file_path(data_dir):
+def get_genesis_file_path(data_dir: str) -> str:
     return os.path.join(data_dir, "genesis.json")
 
 
-def is_live_chain(data_dir):
+def is_live_chain(data_dir: str) -> bool:
     return is_same_path(data_dir, get_live_data_dir())
 
 
-def is_ropsten_chain(data_dir):
-    return is_same_path(data_dir, get_ropsten_data_dir())
+def is_sepolia_chain(data_dir: str) -> bool:
+    return is_same_path(data_dir, get_sepolia_data_dir())
 
 
 def write_genesis_file(
-    genesis_file_path,
-    overwrite=False,
-    nonce="0xdeadbeefdeadbeef",
-    timestamp="0x0",
-    parentHash="0x0000000000000000000000000000000000000000000000000000000000000000",
-    extraData=None,
-    gasLimit="0x47d5cc",
-    difficulty="0x01",
-    mixhash="0x0000000000000000000000000000000000000000000000000000000000000000",
-    coinbase="0x3333333333333333333333333333333333333333",
-    alloc=None,
-    config=None,
-    clique_period: int = 5,
-    clique_epoch: int = 30000,
-):
+    genesis_file_path: str,
+    overwrite: bool = False,
+    **genesis_data: Unpack[GenesisDataTypedDict],
+) -> None:
     if os.path.exists(genesis_file_path) and not overwrite:
-        raise ValueError(
-            "Genesis file already present.  call with `overwrite=True` to overwrite this file"  # noqa: E501
+        raise PyGethValueError(
+            "Genesis file already present. Call with "
+            "`overwrite=True` to overwrite this file"
         )
 
-    if alloc is None:
-        alloc = {}
-
-    if config is None:
-        config = {
-            "homesteadBlock": 0,
-            "eip150Block": 0,
-            "eip155Block": 0,
-            "eip158Block": 0,
-            "byzantiumBlock": 0,
-            "constantinopleBlock": 0,
-            "petersburgBlock": 0,
-            "istanbulBlock": 0,
-            "berlinBlock": 0,
-            "londonBlock": 0,
-            "shanghaiBlock": 0,
-            "daoForkBlock": 0,
-            "daoForSupport": True,
-            # Using the Ethash consensus algorithm is deprecated
-            # Instead, use the Clique consensus algorithm
-            # https://geth.ethereum.org/docs/interface/private-network
-            "clique": {"period": clique_period, "epoch": clique_epoch},
-        }
-
-    # Assign a signer (coinbase) to the genesis block for Clique
-    extraData = (
-        bytes("0x" + "0" * 64 + coinbase[2:] + "0" * 130, "ascii")
-        if extraData is None
-        else extraData
-    )
-
-    genesis_data = {
-        "nonce": nonce,
-        "timestamp": timestamp,
-        "parentHash": parentHash,
-        "extraData": extraData,
-        "gasLimit": gasLimit,
-        "difficulty": difficulty,
-        "mixhash": mixhash,
-        "coinbase": coinbase,
-        "alloc": alloc,
-        "config": config,
-    }
+    validate_genesis_data(genesis_data)
+    # use GenesisData model to fill defaults
+    filled_genesis_data_model = fill_default_genesis_data(genesis_data)
 
     with open(genesis_file_path, "w") as genesis_file:
-        genesis_file.write(json.dumps(force_obj_to_text(genesis_data)))
+        genesis_file.write(
+            json.dumps(force_obj_to_text(filled_genesis_data_model.model_dump()))
+        )
 
 
-def initialize_chain(genesis_data, data_dir, **geth_kwargs):
+def initialize_chain(genesis_data: GenesisDataTypedDict, data_dir: str) -> None:
+    validate_genesis_data(genesis_data)
+    # init with genesis.json
     genesis_file_path = get_genesis_file_path(data_dir)
     write_genesis_file(genesis_file_path, **genesis_data)
-    command, proc = spawn_geth(
-        dict(data_dir=data_dir, suffix_args=["init", genesis_file_path], **geth_kwargs)
+    init_proc = subprocess.Popen(
+        (
+            get_geth_binary_path(),
+            "--datadir",
+            data_dir,
+            "init",
+            genesis_file_path,
+        ),
+        stdin=subprocess.PIPE,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
     )
-    stdoutdata, stderrdata = proc.communicate()
-
-    if proc.returncode:
-        raise ValueError(f"Error: {stdoutdata + stderrdata}")
+    stdoutdata, stderrdata = init_proc.communicate()
+    init_proc.wait()
+    if init_proc.returncode:
+        raise PyGethValueError(
+            "Error initializing genesis.json: \n"
+            f"    stdout={stdoutdata.decode()}\n"
+            f"    stderr={stderrdata.decode()}"
+        )

geth/exceptions.py

@@ -1,23 +1,61 @@
-import textwrap
+from __future__ import (
+    annotations,
+)
 
-from .utils.encoding import (
-    force_text,
+import codecs
+import textwrap
+from typing import (
+    Any,
 )
 
 
-def force_text_maybe(value):
-    if value is not None:
-        return force_text(value, "utf8")
+def force_text_maybe(value: bytes | bytearray | str | None) -> str | None:
+    if isinstance(value, (bytes, bytearray)):
+        return codecs.decode(value, "utf8")
+    elif isinstance(value, str) or value is None:
+        return value
+    else:
+        raise PyGethTypeError(f"Unsupported type: {type(value)}")
+
+
+class PyGethException(Exception):
+    """
+    Exception mixin inherited by all exceptions of py-geth
+
+    This allows::
+
+        try:
+            some_call()
+        except PyGethException:
+            # deal with py-geth exception
+        except:
+            # deal with other exceptions
+    """
 
+    user_message: str | None = None
 
-DEFAULT_MESSAGE = "An error occurred during execution"
+    def __init__(
+        self,
+        *args: Any,
+        user_message: str | None = None,
+    ):
+        super().__init__(*args)
+
+        # Assign properties of PyGethException
+        self.user_message = user_message
 
 
 class GethError(Exception):
-    message = DEFAULT_MESSAGE
+    message = "An error occurred during execution"
 
     def __init__(
-        self, command, return_code, stdin_data, stdout_data, stderr_data, message=None
+        self,
+        command: list[str],
+        return_code: int,
+        stdin_data: str | bytes | bytearray | None = None,
+        stdout_data: str | bytes | bytearray | None = None,
+        stderr_data: str | bytes | bytearray | None = None,
+        message: str | None = None,
     ):
         if message is not None:
             self.message = message
@@ -27,10 +65,9 @@ class GethError(Exception):
         self.stderr_data = force_text_maybe(stderr_data)
         self.stdout_data = force_text_maybe(stdout_data)
 
-    def __str__(self):
+    def __str__(self) -> str:
         return textwrap.dedent(
-            (
-                f"""
+            f"""
         {self.message}
         > command: `{" ".join(self.command)}`
         > return code: `{self.return_code}`
@@ -39,5 +76,41 @@ class GethError(Exception):
         > stdout:
         {self.stderr_data}
         """
-            )
         ).strip()
+
+
+class PyGethGethError(PyGethException, GethError):
+    def __init__(
+        self,
+        *args: Any,
+        **kwargs: Any,
+    ):
+        GethError.__init__(*args, **kwargs)
+
+
+class PyGethAttributeError(PyGethException, AttributeError):
+    pass
+
+
+class PyGethKeyError(PyGethException, KeyError):
+    pass
+
+
+class PyGethTypeError(PyGethException, TypeError):
+    pass
+
+
+class PyGethValueError(PyGethException, ValueError):
+    pass
+
+
+class PyGethOSError(PyGethException, OSError):
+    pass
+
+
+class PyGethNotImplementedError(PyGethException, NotImplementedError):
+    pass
+
+
+class PyGethFileNotFoundError(PyGethException, FileNotFoundError):
+    pass

geth/genesis.json

@@ -1,12 +1,29 @@
 {
-    "nonce": "0xdeadbeefdeadbeef",
+    "config": {
+        "ethash": {},
+        "homesteadBlock": 0,
+        "eip150Block": 0,
+        "eip155Block": 0,
+        "eip158Block": 0,
+        "byzantiumBlock": 0,
+        "constantinopleBlock": 0,
+        "petersburgBlock": 0,
+        "istanbulBlock": 0,
+        "berlinBlock": 0,
+        "londonBlock": 0,
+        "arrowGlacierBlock": 0,
+        "grayGlacierBlock": 0,
+        "terminalTotalDifficulty": 0,
+        "terminalTotalDifficultyPassed": true,
+        "shanghaiTime": 0,
+        "cancunTime": 0
+    },
+    "nonce": "0x0",
     "timestamp": "0x0",
     "parentHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
-    "extraData": "0x686f727365",
-    "gasLimit": "0x2fefd8",
-    "difficulty": "0x400",
-    "mixhash": "0x0000000000000000000000000000000000000000000000000000000000000000",
-    "coinbase": "0x3333333333333333333333333333333333333333",
-    "alloc": {
-   }
+    "extraData": "0x0000000000000000000000000000000000000000000000000000000000000000",
+    "gasLimit": "0x47e7c4",
+    "difficulty": "0x0",
+    "mixHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
+    "alloc": {}
 }