# 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 MainnetGethProcess
>>> geth = MainnetGethProcess()
>>> geth.start()
```
Or in dev mode 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. You can use the following interfaces to query whether these are ready.
```python
>>> geth.wait_for_rpc(timeout=30) # wait up to 30 seconds for the RPC connection to open
>>> geth.is_rpc_ready
True
>>> geth.wait_for_ipc(timeout=30) # wait up to 30 seconds for the IPC socket to open
>>> geth.is_ipc_ready
True
```
## Installing specific versions of `geth`
> This feature is experimental and subject to breaking changes.
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.14.8
```
Or from python using the `install_geth` function.
```python
>>> from geth import install_geth
>>> install_geth('v1.14.8')
```
The installed binary can be found in the `$HOME/.py-geth` directory, under your
home directory. The `v1.14.8` binary would be located at
`$HOME/.py-geth/geth-v1.14.8/bin/geth`.
## About `DevGethProcess`
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, allocated 1 billion ether, and assigned as the coinbase.
- All APIs are enabled on both `rpc` and `ipc` interfaces.
- Networking is configured to not look for or connect to any peers.
- The `networkid` of `1234` is used.
- Verbosity is set to `5` (DEBUG)
- 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.
## 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_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_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.
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/48/42/3fe57a03e47523b181fd53383f4707ebef98fea8b3e22826faa5e128b4a3/py_geth-5.0.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 MainnetGethProcess\n>>> geth = MainnetGethProcess()\n>>> geth.start()\n```\n\nOr in dev mode 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. You can use the following interfaces to query whether these are ready.\n\n```python\n>>> geth.wait_for_rpc(timeout=30) # wait up to 30 seconds for the RPC connection to open\n>>> geth.is_rpc_ready\nTrue\n>>> geth.wait_for_ipc(timeout=30) # wait up to 30 seconds for the IPC socket to open\n>>> geth.is_ipc_ready\nTrue\n```\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.14.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.14.8\n```\n\nOr from python using the `install_geth` function.\n\n```python\n>>> from geth import install_geth\n>>> install_geth('v1.14.8')\n```\n\nThe installed binary can be found in the `$HOME/.py-geth` directory, under your\nhome directory. The `v1.14.8` binary would be located at\n`$HOME/.py-geth/geth-v1.14.8/bin/geth`.\n\n## About `DevGethProcess`\n\nThe `DevGethProcess` will run geth in `--dev` mode and is designed to facilitate testing.\nIn that regard, it is preconfigured as follows.\n\n- A single account is created, allocated 1 billion ether, and assigned as the coinbase.\n- All APIs are enabled on both `rpc` and `ipc` interfaces.\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- 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## 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_14_0\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_14_0 v1_14_2 v1_14_3\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": "5.0.0",
"project_urls": {
"Homepage": "https://github.com/ethereum/py-geth"
},
"split_keywords": [
"ethereum",
"go-ethereum",
"geth"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "76180e132c2f2b157aeb78906bae95d0740ca009101132e57ff8424237082cea",
"md5": "619dd9ec024fa6a707c62c01e88e0064",
"sha256": "bd2edaf8dcba4b3fdf4b33792da0340e114e411feff35b6ac7d58d19252c06b7"
},
"downloads": -1,
"filename": "py_geth-5.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "619dd9ec024fa6a707c62c01e88e0064",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8",
"size": 27689,
"upload_time": "2024-08-14T18:28:00",
"upload_time_iso_8601": "2024-08-14T18:28:00.935665Z",
"url": "https://files.pythonhosted.org/packages/76/18/0e132c2f2b157aeb78906bae95d0740ca009101132e57ff8424237082cea/py_geth-5.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "48423fe57a03e47523b181fd53383f4707ebef98fea8b3e22826faa5e128b4a3",
"md5": "33c0243c7e4acf15bcaa0254d0bf0351",
"sha256": "57368b52c6e1c74f2277a2a370c01ad4c73a021835b150619c02dd7bdab3d369"
},
"downloads": -1,
"filename": "py_geth-5.0.0.tar.gz",
"has_sig": false,
"md5_digest": "33c0243c7e4acf15bcaa0254d0bf0351",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8",
"size": 33950,
"upload_time": "2024-08-14T18:28:02",
"upload_time_iso_8601": "2024-08-14T18:28:02.802731Z",
"url": "https://files.pythonhosted.org/packages/48/42/3fe57a03e47523b181fd53383f4707ebef98fea8b3e22826faa5e128b4a3/py_geth-5.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-14 18:28:02",
"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
