py-geth 4.2.0__tar.gz → 5.2.0__tar.gz

{py-geth-4.2.0 → py_geth-5.2.0}/LICENSE

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2016-2023 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

{py-geth-4.2.0 → py_geth-5.2.0}/MANIFEST.in

@@ -1,6 +1,7 @@
 include LICENSE
 include README.md
 
+recursive-include scripts *
 recursive-include tests *
 
 global-include *.pyi
@@ -12,3 +13,4 @@ prune venv*
 
 include geth/default_blockchain_password
 include geth/genesis.json
+include geth/py.typed

{py-geth-4.2.0/py_geth.egg-info → py_geth-5.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.2
 Name: py-geth
-Version: 4.2.0
+Version: 5.2.0
 Summary: py-geth: Run Go-Ethereum as a subprocess
 Home-page: https://github.com/ethereum/py-geth
 Author: The Ethereum Foundation
@@ -16,29 +16,48 @@ Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.8, <4
 Description-Content-Type: text/markdown
 License-File: LICENSE
+Requires-Dist: eval_type_backport>=0.1.0; python_version < "3.10"
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: requests>=2.23
 Requires-Dist: semantic-version>=2.6.0
+Requires-Dist: types-requests>=2.0.0
+Requires-Dist: typing-extensions>=4.0.1
 Provides-Extra: dev
 Requires-Dist: build>=0.9.0; extra == "dev"
-Requires-Dist: bumpversion>=0.5.3; extra == "dev"
+Requires-Dist: bump_my_version>=0.19.0; extra == "dev"
 Requires-Dist: ipython; extra == "dev"
+Requires-Dist: mypy==1.10.0; extra == "dev"
 Requires-Dist: pre-commit>=3.4.0; extra == "dev"
-Requires-Dist: requests>=2.20; extra == "dev"
 Requires-Dist: tox>=4.0.0; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Requires-Dist: wheel; extra == "dev"
-Requires-Dist: towncrier<22,>=21; extra == "dev"
+Requires-Dist: towncrier<25,>=24; extra == "dev"
 Requires-Dist: flaky>=3.2.0; extra == "dev"
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-xdist>=2.4.0; extra == "dev"
 Provides-Extra: docs
-Requires-Dist: towncrier<22,>=21; extra == "docs"
+Requires-Dist: towncrier<25,>=24; extra == "docs"
 Provides-Extra: test
 Requires-Dist: flaky>=3.2.0; extra == "test"
 Requires-Dist: pytest>=7.0.0; extra == "test"
 Requires-Dist: pytest-xdist>=2.4.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
 
 # py-geth
 
@@ -57,8 +76,6 @@ This library requires the `geth` executable to be present.
 
 ## Installation
 
-Installation
-
 ```bash
 python -m pip install py-geth
 ```
@@ -68,12 +85,12 @@ python -m pip install py-geth
 To run geth connected to the mainnet
 
 ```python
->>> from geth import LiveGethProcess
->>> geth = LiveGethProcess()
+>>> from geth import MainnetGethProcess
+>>> geth = MainnetGethProcess()
 >>> geth.start()
 ```
 
-Or a private local chain for testing.  These require you to give them a name.
+Or in dev mode for testing.  These require you to give them a name.
 
 ```python
 >>> from geth import DevGethProcess
@@ -138,83 +155,57 @@ and stderr output to a logfile.
 All logs will be written to logfiles in `./logs/` in the current directory.
 
 The underlying `geth` process can take additional time to open the RPC or IPC
-connections, as well as to start mining if it needs to generate the DAG.  You
-can use the following interfaces to query whether these are ready.
+connections. You can use the following interfaces to query whether these are ready.
 
 ```python
->>> geth.is_rpc_ready
-True
 >>> geth.wait_for_rpc(timeout=30)  # wait up to 30 seconds for the RPC connection to open
->>> geth.is_ipc_ready
+>>> geth.is_rpc_ready
 True
 >>> geth.wait_for_ipc(timeout=30)  # wait up to 30 seconds for the IPC socket to open
->>> geth.is_dag_generated
-True
->>> geth.is_mining
+>>> geth.is_ipc_ready
 True
->>> geth.wait_for_dag(timeout=600)  # wait up to 10 minutes for the DAG to generate.
 ```
 
-> The DAG functionality currently only applies to the DAG for epoch 0.
-
 ## Installing specific versions of `geth`
 
 > This feature is experimental and subject to breaking changes.
 
-Versions of `geth` dating back to v1.11.0 can be installed using `py-geth`.
+Versions of `geth` dating back to v1.14.0 can be installed using `py-geth`.
 See [install.py](https://github.com/ethereum/py-geth/blob/main/geth/install.py) for
 the current list of supported versions.
 
 Installation can be done via the command line:
 
 ```bash
-$ python -m geth.install v1.13.10
+$ python -m geth.install v1.14.12
 ```
 
 Or from python using the `install_geth` function.
 
 ```python
 >>> from geth import install_geth
->>> install_geth('v1.13.10')
+>>> install_geth('v1.14.12')
 ```
 
 The installed binary can be found in the `$HOME/.py-geth` directory, under your
-home directory.  The `v1.13.10` binary would be located at
-`$HOME/.py-geth/geth-v1.13.10/bin/geth`.
+home directory.  The `v1.14.12` binary would be located at
+`$HOME/.py-geth/geth-v1.14.12/bin/geth`.
 
 ## About `DevGethProcess`
 
-The `DevGethProcess` is designed to facilitate testing.  In that regard, it is
-preconfigured as follows.
+The `DevGethProcess` will run geth in `--dev` mode and is designed to facilitate testing.
+In that regard, it is preconfigured as follows.
 
-- A single account is created and allocated 1 billion ether.
+- A single account is created, allocated 1 billion ether, and assigned as the coinbase.
 - All APIs are enabled on both `rpc` and `ipc` interfaces.
-- Account 0 is unlocked
 - Networking is configured to not look for or connect to any peers.
 - The `networkid` of `1234` is used.
 - Verbosity is set to `5` (DEBUG)
-- Mining is enabled with a single thread.
 - The RPC interface *tries* to bind to 8545 but will find an open port if this
   port is not available.
 - The DevP2P interface *tries* to bind to 30303 but will find an open port if this
   port is not available.
 
-## Gotchas
-
-If you are running with `mining` enabled, which is default for `DevGethProcess`,
-then you will likely need to generate the `DAG` manually.  If you do not, then
-it will auto-generate the first time you run the process and this takes a
-while.
-
-To generate it manually:
-
-```sh
-$ geth makedag 0 ~/.ethash
-```
-
-This is especially important in CI environments like Travis-CI where your
-process will likely timeout during generation.
-
 ## Development
 
 Clone the repository:
@@ -297,14 +288,14 @@ the version for the one you wish to add support for. Note that the `v` in the ve
 optional.
 
 ```shell
-$ python update_geth.py v1_10_9
+$ python update_geth.py v1_14_0
 ```
 
 To introduce support for more than one version, pass in the versions in increasing order,
 ending with the latest version.
 
 ```shell
-$ python update_geth.py v1_10_7 v1_10_8 v1_10_9
+$ python update_geth.py v1_14_0 v1_14_2 v1_14_3
 ```
 
 Always review your changes before committing as something may cause this existing pattern to change at some point.

{py-geth-4.2.0 → py_geth-5.2.0}/README.md

@@ -15,8 +15,6 @@ This library requires the `geth` executable to be present.
 
 ## Installation
 
-Installation
-
 ```bash
 python -m pip install py-geth
 ```
@@ -26,12 +24,12 @@ python -m pip install py-geth
 To run geth connected to the mainnet
 
 ```python
->>> from geth import LiveGethProcess
->>> geth = LiveGethProcess()
+>>> from geth import MainnetGethProcess
+>>> geth = MainnetGethProcess()
 >>> geth.start()
 ```
 
-Or a private local chain for testing.  These require you to give them a name.
+Or in dev mode for testing.  These require you to give them a name.
 
 ```python
 >>> from geth import DevGethProcess
@@ -96,83 +94,57 @@ and stderr output to a logfile.
 All logs will be written to logfiles in `./logs/` in the current directory.
 
 The underlying `geth` process can take additional time to open the RPC or IPC
-connections, as well as to start mining if it needs to generate the DAG.  You
-can use the following interfaces to query whether these are ready.
+connections. You can use the following interfaces to query whether these are ready.
 
 ```python
->>> geth.is_rpc_ready
-True
 >>> geth.wait_for_rpc(timeout=30)  # wait up to 30 seconds for the RPC connection to open
->>> geth.is_ipc_ready
+>>> geth.is_rpc_ready
 True
 >>> geth.wait_for_ipc(timeout=30)  # wait up to 30 seconds for the IPC socket to open
->>> geth.is_dag_generated
-True
->>> geth.is_mining
+>>> geth.is_ipc_ready
 True
->>> geth.wait_for_dag(timeout=600)  # wait up to 10 minutes for the DAG to generate.
 ```
 
-> The DAG functionality currently only applies to the DAG for epoch 0.
-
 ## Installing specific versions of `geth`
 
 > This feature is experimental and subject to breaking changes.
 
-Versions of `geth` dating back to v1.11.0 can be installed using `py-geth`.
+Versions of `geth` dating back to v1.14.0 can be installed using `py-geth`.
 See [install.py](https://github.com/ethereum/py-geth/blob/main/geth/install.py) for
 the current list of supported versions.
 
 Installation can be done via the command line:
 
 ```bash
-$ python -m geth.install v1.13.10
+$ python -m geth.install v1.14.12
 ```
 
 Or from python using the `install_geth` function.
 
 ```python
 >>> from geth import install_geth
->>> install_geth('v1.13.10')
+>>> install_geth('v1.14.12')
 ```
 
 The installed binary can be found in the `$HOME/.py-geth` directory, under your
-home directory.  The `v1.13.10` binary would be located at
-`$HOME/.py-geth/geth-v1.13.10/bin/geth`.
+home directory.  The `v1.14.12` binary would be located at
+`$HOME/.py-geth/geth-v1.14.12/bin/geth`.
 
 ## About `DevGethProcess`
 
-The `DevGethProcess` is designed to facilitate testing.  In that regard, it is
-preconfigured as follows.
+The `DevGethProcess` will run geth in `--dev` mode and is designed to facilitate testing.
+In that regard, it is preconfigured as follows.
 
-- A single account is created and allocated 1 billion ether.
+- A single account is created, allocated 1 billion ether, and assigned as the coinbase.
 - All APIs are enabled on both `rpc` and `ipc` interfaces.
-- Account 0 is unlocked
 - Networking is configured to not look for or connect to any peers.
 - The `networkid` of `1234` is used.
 - Verbosity is set to `5` (DEBUG)
-- Mining is enabled with a single thread.
 - The RPC interface *tries* to bind to 8545 but will find an open port if this
   port is not available.
 - The DevP2P interface *tries* to bind to 30303 but will find an open port if this
   port is not available.
 
-## Gotchas
-
-If you are running with `mining` enabled, which is default for `DevGethProcess`,
-then you will likely need to generate the `DAG` manually.  If you do not, then
-it will auto-generate the first time you run the process and this takes a
-while.
-
-To generate it manually:
-
-```sh
-$ geth makedag 0 ~/.ethash
-```
-
-This is especially important in CI environments like Travis-CI where your
-process will likely timeout during generation.
-
 ## Development
 
 Clone the repository:
@@ -255,14 +227,14 @@ the version for the one you wish to add support for. Note that the `v` in the ve
 optional.
 
 ```shell
-$ python update_geth.py v1_10_9
+$ python update_geth.py v1_14_0
 ```
 
 To introduce support for more than one version, pass in the versions in increasing order,
 ending with the latest version.
 
 ```shell
-$ python update_geth.py v1_10_7 v1_10_8 v1_10_9
+$ python update_geth.py v1_14_0 v1_14_2 v1_14_3
 ```
 
 Always review your changes before committing as something may cause this existing pattern to change at some point.

{py-geth-4.2.0 → py_geth-5.2.0}/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",
+)

py_geth-5.2.0/geth/accounts.py

@@ -0,0 +1,201 @@
+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,
+)
+from .wrapper import (
+    spawn_geth,
+)
+
+
+def get_accounts(
+    **geth_kwargs: Unpack[GethKwargsTypedDict],
+) -> tuple[str, ...] | tuple[()]:
+    """
+    Returns all geth accounts as tuple of hex encoded strings
+
+    >>> get_accounts(data_dir='some/data/dir')
+    ... ('0x...', '0x...')
+    """
+    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():
+            return tuple()
+        else:
+            raise PyGethValueError(
+                format_error_message(
+                    "Error trying to list accounts",
+                    command,
+                    proc.returncode,
+                    stdoutdata.decode(),
+                    stderrdata.decode(),
+                )
+            )
+    accounts = parse_geth_accounts(stdoutdata)
+    return accounts
+
+
+account_regex = re.compile(b"([a-f0-9]{40})")
+
+
+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
+    interaction (transfers) between Ethereum accounts.
+
+    This command communicates with ``geth`` command over
+    terminal interaction. It creates keystore folder and new
+    account there.
+
+    This function only works against offline geth processes,
+    because geth builds an account cache when starting up.
+    If geth process is already running you can create new
+    accounts using
+    `web3.personal.newAccount()
+    <https://geth.ethereum.org/docs/interacting-with-geth/rpc/ns-personal>_`
+
+    RPC API.
+
+    Example pytest fixture for tests:
+
+    .. code-block:: python
+
+        import os
+
+        from geth.wrapper import DEFAULT_PASSWORD_PATH
+        from geth.accounts import create_new_account
+
+
+        @pytest.fixture
+        def target_account() -> str:
+            '''Create a new Ethereum account on a running Geth node.
+
+            The account can be used as a withdrawal target for tests.
+
+            :return: 0x address of the account
+            '''
+
+            # We store keystore files in the current working directory
+            # of the test run
+            data_dir = os.getcwd()
+
+            # Use the default password "this-is-not-a-secure-password"
+            # as supplied in geth/default_blockchain_password file.
+            # The supplied password must be bytes, not string,
+            # as we only want ASCII characters and do not want to
+            # deal encoding problems with passwords
+            account = create_new_account(data_dir, DEFAULT_PASSWORD_PATH)
+            return account
+
+    :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 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")
+
+    password = geth_kwargs.get("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 PyGethValueError(
+            format_error_message(
+                "Error trying to create a new account",
+                command,
+                proc.returncode,
+                stdoutdata.decode(),
+                stderrdata.decode(),
+            )
+        )
+
+    match = account_regex.search(stdoutdata)
+    if not match:
+        raise PyGethValueError(
+            format_error_message(
+                "Did not find an address in process output",
+                command,
+                proc.returncode,
+                stdoutdata.decode(),
+                stderrdata.decode(),
+            )
+        )
+
+    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")
+
+    validate_geth_kwargs(geth_kwargs)
+    accounts = get_accounts(**geth_kwargs)
+    if not accounts:
+        account = create_new_account(**geth_kwargs)
+    else:
+        account = accounts[0]
+    return account
+
+
+def parse_geth_accounts(raw_accounts_output: bytes) -> tuple[str, ...]:
+    accounts = account_regex.findall(raw_accounts_output)
+    accounts_set = set(accounts)  # remove duplicates
+    return tuple("0x" + account.decode() for account in accounts_set)