Package: py-geth
py-gethPython wrapper around runninggethas a subprocessSystem DependencyThis library requires thegethexecutable to be present.If managing your own bundled version of geth, set the path to the binary using theGETH_BINARYenvironment variable.InstallationInstallationpython-mpipinstallpy-gethQuickstartTo run geth connected to the mainnet>>>fromgethimportLiveGethProcess>>>geth=LiveGethProcess()>>>geth.start()Or a private local chain for testing.  These require you to give them a name.>>>fromgethimportDevGethProcess>>>geth=DevGethProcess('testing')>>>geth.start()By default theDevGethProcesssets up test chains in the defaultdatadirused bygeth.  If you would like to change the location for these test
chains, you can specify an alternativebase_dir.>>>geth=DevGethProcess('testing','/tmp/some-other-base-dir/')>>>geth.start()Each instance has a few convenient properties.>>>geth.data_dir"~/.ethereum">>>geth.rpc_port8545>>>geth.ipc_path"~/.ethereum/geth.ipc">>>geth.accounts['0xd3cda913deb6f67967b99d67acdfa1712c293601']>>>geth.is_aliveFalse>>>geth.is_runningFalse>>>geth.is_stoppedFalse>>>geth.start()>>>geth.is_aliveTrue# indicates that the subprocess hasn't exited>>>geth.is_runningTrue# indicates that `start()` has been called (but `stop()` hasn't)>>>geth.is_stoppedFalse>>>geth.stop()>>>geth.is_aliveFalse>>>geth.is_runningFalse>>>geth.is_stoppedTrueWhen testing it can be nice to see the logging output produced by thegethprocess.py-gethprovides a mixin class that can be used to log the stdout
and stderr output to a logfile.>>>fromgethimportLoggingMixin,DevGethProcess>>>classMyGeth(LoggingMixin,DevGethProcess):...pass>>>geth=MyGeth()>>>geth.start()All logs will be written to logfiles in./logs/in the current directory.The underlyinggethprocess 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.>>>geth.is_rpc_readyTrue>>>geth.wait_for_rpc(timeout=30)# wait up to 30 seconds for the RPC connection to open>>>geth.is_ipc_readyTrue>>>geth.wait_for_ipc(timeout=30)# wait up to 30 seconds for the IPC socket to open>>>geth.is_dag_generatedTrue>>>geth.is_miningTrue>>>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 ofgethThis feature is experimental and subject to breaking changes.Versions ofgethdating back to v1.11.0 can be installed usingpy-geth.
Seeinstall.pyfor
the current list of supported versions.Installation can be done via the command line:$python-mgeth.installv1.13.11Or from python using theinstall_gethfunction.>>>fromgethimportinstall_geth>>>install_geth('v1.13.11')The installed binary can be found in the$HOME/.py-gethdirectory, under your
home directory.  Thev1.13.11binary would be located at$HOME/.py-geth/geth-v1.13.11/bin/geth.AboutDevGethProcessTheDevGethProcessis 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 bothrpcandipcinterfaces.Account 0 is unlockedNetworking is configured to not look for or connect to any peers.Thenetworkidof1234is used.Verbosity is set to5(DEBUG)Mining is enabled with a single thread.The RPC interfacetriesto bind to 8545 but will find an open port if this
port is not available.The DevP2P interfacetriesto bind to 30303 but will find an open port if this
port is not available.GotchasIf you are running withminingenabled, which is default forDevGethProcess,
then you will likely need to generate theDAGmanually.  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:$gethmakedag0~/.ethashThis is especially important in CI environments like Travis-CI where your
process will likely timeout during generation.DevelopmentClone the repository:$gitclonegit@github.com:ethereum/py-geth.gitNext, run the following from the newly-createdpy-gethdirectory:$python-mpipinstall-e".[dev]"Running the testsYou can run the tests with:pytesttestsDeveloper SetupIf you would like to hack on py-geth, please check out theSnake Charmers
Tactical Manualfor information on how we do:TestingPull RequestsDocumentationWe usepre-committo maintain consistent code style. Once
installed, it will run automatically with every commit. You can also run it manually
withmake lint. If you need to make a commit that skips thepre-commitchecks, you
can do so withgit commit --no-verify.Development Environment SetupYou can set up your dev environment with:gitclonegit@github.com:ethereum/py-geth.gitcdpy-geth
virtualenv-ppython3venv
.venv/bin/activate
python-mpipinstall-e".[dev]"pre-commitinstallRelease setupTo release a new version:makereleasebump=$$VERSION_PART_TO_BUMP$$How to bumpversionThe version format for this repo is{major}.{minor}.{patch}for stable, and{major}.{minor}.{patch}-{stage}.{devnum}for unstable (stagecan be alpha or beta).To issue the next version in line, specify which part to bump,
likemake release bump=minorormake 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=stagewill switch to a stable.To issue an unstable version when the current version is stable, specify the
new version explicitly, likemake release bump="--new-version 4.0.0-alpha.1 devnum"Adding Support For New Geth VersionsThere is an automation script to facilitate adding support for new geth versions:update_geth.pyTo 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 thevin the versioning is
optional.$pythonupdate_geth.pyv1_10_9To introduce support for more than one version, pass in the versions in increasing order,
ending with the latest version.$pythonupdate_geth.pyv1_10_7v1_10_8v1_10_9Always 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.