# py-geth
[](https://discord.gg/GHryRvPB84)
[](https://circleci.com/gh/ethereum/py-geth)
[](https://badge.fury.io/py/py-geth)
[](https://pypi.python.org/pypi/py-geth)
Python wrapper around running `geth` as a subprocess
## System Dependency
This library requires the `geth` executable to be present.
> If managing your own bundled version of geth, set the path to the binary using the `GETH_BINARY` environment variable.
## Installation
Installation
```bash
python -m pip install py-geth
```
## Quickstart
To run geth connected to the mainnet
```python
>>> from geth import LiveGethProcess
>>> geth = LiveGethProcess()
>>> geth.start()
```
Or a private local chain for testing. These require you to give them a name.
```python
>>> from geth import DevGethProcess
>>> geth = DevGethProcess('testing')
>>> geth.start()
```
By default the `DevGethProcess` sets up test chains in the default `datadir`
used by `geth`. If you would like to change the location for these test
chains, you can specify an alternative `base_dir`.
```python
>>> geth = DevGethProcess('testing', '/tmp/some-other-base-dir/')
>>> geth.start()
```
Each instance has a few convenient properties.
```python
>>> geth.data_dir
"~/.ethereum"
>>> geth.rpc_port
8545
>>> geth.ipc_path
"~/.ethereum/geth.ipc"
>>> geth.accounts
['0xd3cda913deb6f67967b99d67acdfa1712c293601']
>>> geth.is_alive
False
>>> geth.is_running
False
>>> geth.is_stopped
False
>>> geth.start()
>>> geth.is_alive
True # indicates that the subprocess hasn't exited
>>> geth.is_running
True # indicates that `start()` has been called (but `stop()` hasn't)
>>> geth.is_stopped
False
>>> geth.stop()
>>> geth.is_alive
False
>>> geth.is_running
False
>>> geth.is_stopped
True
```
When testing it can be nice to see the logging output produced by the `geth`
process. `py-geth` provides a mixin class that can be used to log the stdout
and stderr output to a logfile.
```python
>>> from geth import LoggingMixin, DevGethProcess
>>> class MyGeth(LoggingMixin, DevGethProcess):
... pass
>>> geth = MyGeth()
>>> geth.start()
```
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.
```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
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
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`.
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.14
```
Or from python using the `install_geth` function.
```python
>>> from geth import install_geth
>>> install_geth('v1.13.14')
```
The installed binary can be found in the `$HOME/.py-geth` directory, under your
home directory. The `v1.13.14` binary would be located at
`$HOME/.py-geth/geth-v1.13.14/bin/geth`.
## About `DevGethProcess`
The `DevGethProcess` is designed to facilitate testing. In that regard, it is
preconfigured as follows.
- A single account is created and allocated 1 billion ether.
- 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:
```shell
$ git clone git@github.com:ethereum/py-geth.git
```
Next, run the following from the newly-created `py-geth` directory:
```sh
$ python -m pip install -e ".[dev]"
```
### Running the tests
You can run the tests with:
```sh
pytest tests
```
## Developer Setup
If you would like to hack on py-geth, please check out the [Snake Charmers
Tactical Manual](https://github.com/ethereum/snake-charmers-tactical-manual)
for information on how we do:
- Testing
- Pull Requests
- Documentation
We use [pre-commit](https://pre-commit.com/) to maintain consistent code style. Once
installed, it will run automatically with every commit. You can also run it manually
with `make lint`. If you need to make a commit that skips the `pre-commit` checks, you
can do so with `git commit --no-verify`.
### Development Environment Setup
You can set up your dev environment with:
```sh
git clone git@github.com:ethereum/py-geth.git
cd py-geth
virtualenv -p python3 venv
. venv/bin/activate
python -m pip install -e ".[dev]"
pre-commit install
```
### Release setup
To release a new version:
```sh
make release bump=$$VERSION_PART_TO_BUMP$$
```
#### How to bumpversion
The version format for this repo is `{major}.{minor}.{patch}` for stable, and
`{major}.{minor}.{patch}-{stage}.{devnum}` for unstable (`stage` can be alpha or beta).
To issue the next version in line, specify which part to bump,
like `make release bump=minor` or `make release bump=devnum`. This is typically done from the
main branch, except when releasing a beta (in which case the beta is released from main,
and the previous stable branch is released from said branch).
If you are in a beta version, `make release bump=stage` will switch to a stable.
To issue an unstable version when the current version is stable, specify the
new version explicitly, like `make release bump="--new-version 4.0.0-alpha.1 devnum"`
## Adding Support For New Geth Versions
There is an automation script to facilitate adding support for new geth versions: `update_geth.py`
To add support for a geth version, run the following line from the py-geth directory, substituting
the version for the one you wish to add support for. Note that the `v` in the versioning is
optional.
```shell
$ python update_geth.py v1_10_9
```
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
```
Always review your changes before committing as something may cause this existing pattern to change at some point.
It is best to compare the git difference with a previous commit that introduced support for a new geth version to make
sure everything looks good.
Raw data
{
"_id": null,
"home_page": "https://github.com/ethereum/py-geth",
"name": "py-geth",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.8",
"maintainer_email": null,
"keywords": "ethereum go-ethereum geth",
"author": "The Ethereum Foundation",
"author_email": "snakecharmers@ethereum.org",
"download_url": "https://files.pythonhosted.org/packages/cc/4b/3229e00852ac771a942feb8e3676d5203508ef8dea72dbf7f5cf444c7b1e/py-geth-4.4.0.tar.gz",
"platform": null,
"description": "# py-geth\n\n[](https://discord.gg/GHryRvPB84)\n[](https://circleci.com/gh/ethereum/py-geth)\n[](https://badge.fury.io/py/py-geth)\n[](https://pypi.python.org/pypi/py-geth)\n\nPython wrapper around running `geth` as a subprocess\n\n## System Dependency\n\nThis library requires the `geth` executable to be present.\n\n> If managing your own bundled version of geth, set the path to the binary using the `GETH_BINARY` environment variable.\n\n## Installation\n\nInstallation\n\n```bash\npython -m pip install py-geth\n```\n\n## Quickstart\n\nTo run geth connected to the mainnet\n\n```python\n>>> from geth import LiveGethProcess\n>>> geth = LiveGethProcess()\n>>> geth.start()\n```\n\nOr a private local chain for testing. These require you to give them a name.\n\n```python\n>>> from geth import DevGethProcess\n>>> geth = DevGethProcess('testing')\n>>> geth.start()\n```\n\nBy default the `DevGethProcess` sets up test chains in the default `datadir`\nused by `geth`. If you would like to change the location for these test\nchains, you can specify an alternative `base_dir`.\n\n```python\n>>> geth = DevGethProcess('testing', '/tmp/some-other-base-dir/')\n>>> geth.start()\n```\n\nEach instance has a few convenient properties.\n\n```python\n>>> geth.data_dir\n\"~/.ethereum\"\n>>> geth.rpc_port\n8545\n>>> geth.ipc_path\n\"~/.ethereum/geth.ipc\"\n>>> geth.accounts\n['0xd3cda913deb6f67967b99d67acdfa1712c293601']\n>>> geth.is_alive\nFalse\n>>> geth.is_running\nFalse\n>>> geth.is_stopped\nFalse\n>>> geth.start()\n>>> geth.is_alive\nTrue # indicates that the subprocess hasn't exited\n>>> geth.is_running\nTrue # indicates that `start()` has been called (but `stop()` hasn't)\n>>> geth.is_stopped\nFalse\n>>> geth.stop()\n>>> geth.is_alive\nFalse\n>>> geth.is_running\nFalse\n>>> geth.is_stopped\nTrue\n```\n\nWhen testing it can be nice to see the logging output produced by the `geth`\nprocess. `py-geth` provides a mixin class that can be used to log the stdout\nand stderr output to a logfile.\n\n```python\n>>> from geth import LoggingMixin, DevGethProcess\n>>> class MyGeth(LoggingMixin, DevGethProcess):\n... pass\n>>> geth = MyGeth()\n>>> geth.start()\n```\n\nAll logs will be written to logfiles in `./logs/` in the current directory.\n\nThe underlying `geth` process can take additional time to open the RPC or IPC\nconnections, as well as to start mining if it needs to generate the DAG. You\ncan use the following interfaces to query whether these are ready.\n\n```python\n>>> geth.is_rpc_ready\nTrue\n>>> geth.wait_for_rpc(timeout=30) # wait up to 30 seconds for the RPC connection to open\n>>> geth.is_ipc_ready\nTrue\n>>> geth.wait_for_ipc(timeout=30) # wait up to 30 seconds for the IPC socket to open\n>>> geth.is_dag_generated\nTrue\n>>> geth.is_mining\nTrue\n>>> geth.wait_for_dag(timeout=600) # wait up to 10 minutes for the DAG to generate.\n```\n\n> The DAG functionality currently only applies to the DAG for epoch 0.\n\n## Installing specific versions of `geth`\n\n> This feature is experimental and subject to breaking changes.\n\nVersions of `geth` dating back to v1.11.0 can be installed using `py-geth`.\nSee [install.py](https://github.com/ethereum/py-geth/blob/main/geth/install.py) for\nthe current list of supported versions.\n\nInstallation can be done via the command line:\n\n```bash\n$ python -m geth.install v1.13.14\n```\n\nOr from python using the `install_geth` function.\n\n```python\n>>> from geth import install_geth\n>>> install_geth('v1.13.14')\n```\n\nThe installed binary can be found in the `$HOME/.py-geth` directory, under your\nhome directory. The `v1.13.14` binary would be located at\n`$HOME/.py-geth/geth-v1.13.14/bin/geth`.\n\n## About `DevGethProcess`\n\nThe `DevGethProcess` is designed to facilitate testing. In that regard, it is\npreconfigured as follows.\n\n- A single account is created and allocated 1 billion ether.\n- All APIs are enabled on both `rpc` and `ipc` interfaces.\n- Account 0 is unlocked\n- Networking is configured to not look for or connect to any peers.\n- The `networkid` of `1234` is used.\n- Verbosity is set to `5` (DEBUG)\n- Mining is enabled with a single thread.\n- The RPC interface *tries* to bind to 8545 but will find an open port if this\n port is not available.\n- The DevP2P interface *tries* to bind to 30303 but will find an open port if this\n port is not available.\n\n## Gotchas\n\nIf you are running with `mining` enabled, which is default for `DevGethProcess`,\nthen you will likely need to generate the `DAG` manually. If you do not, then\nit will auto-generate the first time you run the process and this takes a\nwhile.\n\nTo generate it manually:\n\n```sh\n$ geth makedag 0 ~/.ethash\n```\n\nThis is especially important in CI environments like Travis-CI where your\nprocess will likely timeout during generation.\n\n## Development\n\nClone the repository:\n\n```shell\n$ git clone git@github.com:ethereum/py-geth.git\n```\n\nNext, run the following from the newly-created `py-geth` directory:\n\n```sh\n$ python -m pip install -e \".[dev]\"\n```\n\n### Running the tests\n\nYou can run the tests with:\n\n```sh\npytest tests\n```\n\n## Developer Setup\n\nIf you would like to hack on py-geth, please check out the [Snake Charmers\nTactical Manual](https://github.com/ethereum/snake-charmers-tactical-manual)\nfor information on how we do:\n\n- Testing\n- Pull Requests\n- Documentation\n\nWe use [pre-commit](https://pre-commit.com/) to maintain consistent code style. Once\ninstalled, it will run automatically with every commit. You can also run it manually\nwith `make lint`. If you need to make a commit that skips the `pre-commit` checks, you\ncan do so with `git commit --no-verify`.\n\n### Development Environment Setup\n\nYou can set up your dev environment with:\n\n```sh\ngit clone git@github.com:ethereum/py-geth.git\ncd py-geth\nvirtualenv -p python3 venv\n. venv/bin/activate\npython -m pip install -e \".[dev]\"\npre-commit install\n```\n\n### Release setup\n\nTo release a new version:\n\n```sh\nmake release bump=$$VERSION_PART_TO_BUMP$$\n```\n\n#### How to bumpversion\n\nThe version format for this repo is `{major}.{minor}.{patch}` for stable, and\n`{major}.{minor}.{patch}-{stage}.{devnum}` for unstable (`stage` can be alpha or beta).\n\nTo issue the next version in line, specify which part to bump,\nlike `make release bump=minor` or `make release bump=devnum`. This is typically done from the\nmain branch, except when releasing a beta (in which case the beta is released from main,\nand the previous stable branch is released from said branch).\n\nIf you are in a beta version, `make release bump=stage` will switch to a stable.\n\nTo issue an unstable version when the current version is stable, specify the\nnew version explicitly, like `make release bump=\"--new-version 4.0.0-alpha.1 devnum\"`\n\n## Adding Support For New Geth Versions\n\nThere is an automation script to facilitate adding support for new geth versions: `update_geth.py`\n\nTo add support for a geth version, run the following line from the py-geth directory, substituting\nthe version for the one you wish to add support for. Note that the `v` in the versioning is\noptional.\n\n```shell\n$ python update_geth.py v1_10_9\n```\n\nTo introduce support for more than one version, pass in the versions in increasing order,\nending with the latest version.\n\n```shell\n$ python update_geth.py v1_10_7 v1_10_8 v1_10_9\n```\n\nAlways review your changes before committing as something may cause this existing pattern to change at some point.\nIt is best to compare the git difference with a previous commit that introduced support for a new geth version to make\nsure everything looks good.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "py-geth: Run Go-Ethereum as a subprocess",
"version": "4.4.0",
"project_urls": {
"Homepage": "https://github.com/ethereum/py-geth"
},
"split_keywords": [
"ethereum",
"go-ethereum",
"geth"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3c9f7ea1741c5eb80a99540f17a22562455d41da2237e0ac9435e6ac6e576887",
"md5": "42cf6fbb103aa00bba7226fd1a47f483",
"sha256": "ae8771b028c68f6710e6434d2aa1310ce2ba3cc9099d244d9bb5a9e340786a92"
},
"downloads": -1,
"filename": "py_geth-4.4.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "42cf6fbb103aa00bba7226fd1a47f483",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8",
"size": 24379,
"upload_time": "2024-03-27T18:49:40",
"upload_time_iso_8601": "2024-03-27T18:49:40.897729Z",
"url": "https://files.pythonhosted.org/packages/3c/9f/7ea1741c5eb80a99540f17a22562455d41da2237e0ac9435e6ac6e576887/py_geth-4.4.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "cc4b3229e00852ac771a942feb8e3676d5203508ef8dea72dbf7f5cf444c7b1e",
"md5": "f6cab65fb0148f08c9ac27e2e79c70de",
"sha256": "c08d84f6dad4f86a9b8ffd74c0a0f160d600db0ee45dfc2a66d5e13522aeb039"
},
"downloads": -1,
"filename": "py-geth-4.4.0.tar.gz",
"has_sig": false,
"md5_digest": "f6cab65fb0148f08c9ac27e2e79c70de",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8",
"size": 30465,
"upload_time": "2024-03-27T18:49:42",
"upload_time_iso_8601": "2024-03-27T18:49:42.545462Z",
"url": "https://files.pythonhosted.org/packages/cc/4b/3229e00852ac771a942feb8e3676d5203508ef8dea72dbf7f5cf444c7b1e/py-geth-4.4.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-27 18:49:42",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ethereum",
"github_project": "py-geth",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"circle": true,
"tox": true,
"lcname": "py-geth"
}
JSON
