Developer Notes

Installation:

• Python2.7 is required

pip install -r requirements.txt

That will try to install the requirements in your current environment.

NOTE: If you have not setup a virtualenv this will most likely try to install dependencies globally and might require more privileges.

How to contribute

We accept pull requests. Fork the repository and send your PR!

dev_requirements

To install the dependencies necessary for development (testing, ...), run:

pip install -r dev_requirements.txt

Coding

• You should try to write code compatible with Python3 (see http://www.diveintopython3.net/porting-code-to-python-3-with-2to3.html).
• Your code should pass PEP8 check.
• Use absolute path for import (eg. from pyethereum import utils)
• Use rlp.utils.decode_hex and rlp.utils.encode_hex instead of .decode('hex') and .encode('hex')
• Use utils.is_numeric() and utils.is_string() instead of isinstance()
• Use utils.to_string() instead str()
• Use rlp.utils.ascii_chr() instead chr()
• Use utils.safe_ord() instead ord()
• Use // instead / to divide integer
• Use bytes for every hard coded string. It is not enough to add b before every string, because in Py2, 'foo'[0] == 'f' and in Py3, b'foo'[0] == 102, so everywhere use in_to_bytes(data[i]) instead of data[i] (see https://github.com/ethereum/pyethereum/commit/72331f81e42e11e8c3d2f584f5d49befb4ec3722#diff-a353fb065c72ecea2d0526509dd51d41L7)

Testing

pytest is used for testing

In order to run tests, you need to prepare the fixtures-submodule (not necessary when using bootstrap):

git submodule init
git submodule update --recursive

then run the tests either by calling py.test (or behave for a set of older tests) consecutively or by calling tox (which will do both).

In order to update the fixtures-submodule:

git submodule status
cd fixtures/
git pull origin develop
cd ..
git commit -m 'updated fixtures submodule'

Tips for testing with the VM:

1. You can get traces for a transaction using the API and ethclient, e.g.: bin/pyethclient trace 522f583b94cb3a16deca41404ef404c2c1b3484070af2ec7971bc4e1a17c556e
2. Use the -s modifier to see the log output of tests, e.g. py.test -s tests/test_vm.py
3. You can customize the level of VM logging detail by modifying PBLogger in processblock.py

Logging:

Please use the logging module for logging.

For basic, verbose logging functionality, the following is sufficient (adjust level to your needs)::

import logging

logging.basicConfig(format='[%(asctime)s] %(name)s %(levelname)s %(message)s', level=logging.DEBUG)
logger = logging.getLogger(__name__)

If you need a more advanced setup, have a look at the python docs

Easy Debugging:

The eth.py script, understands a command line flag for easy debugging, e.g.:

pyethereum/eth.py -L pyethereum.wire:DEBUG,:INFO ...<other args>

will set the log-level for wire to DEBUG and the root logger to INFO.

pyethereum/eth.py -L :DEBUG ...<other args>

logs everything to the console.

Monkey patching

bin/pyeth tries to import a module named pyethereum/monkeypatch.py. You can use monkey patching to temporarily introduce alternate control flow e.g.

"Monkey Patch Example"

import pyethereum.packeter
pyethereum.packeter.Packeter.CLIENT_VERSION += '/YourName'

# set processblock log details
import pyethereum.processblock as pb
pb.pblogger.log_state_delta = True
pb.pblogger.log_ops = True

# write failed blocks to disc
import pyethereum.utils as utils
orig_verify = pb.verify

def log_verify(block, parent):
   res = orig_verify(block, parent)
   if not res:
        pb.logger.debug('### VERIFICATION FAILED ### %r', e)
        f = os.path.join(utils.data_dir, 'badblock.log')
        open(f, 'w').write(str(block.hex_serialize()))
        print block.hex_serialize()
    return res
pb.verify = log_verify

# import other patches
import blockfetcherpatch

Installation with Buildout

You can have dependencies managed by buildout - a buildout.cfg is already included in the project.

Bootstrap:

In order to do so, you'll need to bootstrap the project (needs only be done once). On systems that provide curl you can use the following handy one-liner (no curl_ ?):

curl http://downloads.buildout.org/2/bootstrap.py | python

Build and run:

Build the project via bin/buildout and run the client via bin/eth.

This will install dependencies in a virtualenv, provide you with a scoped python interpreter (bin/python) and make all console_scripts available in the bin directory.

develop.cfg

Instead of only running bin/buildout, there is an extending buildout configuration for development purposes (it will install the dev_requirements, prepare tests, etc...). It is an executable .cfg file:

./develop.cfg

will run the extended buildout.

Hints:

console-scripts

If you follow the buildout way, some of the commands in this README will change, since buildout installs the dependencies as well as pyethereum's console_scripts in the bin/-directory. For example, instead of running the cli client with:

pyethereum/eth.py # it will become
bin/eth

same goes for behave which becomes bin/behave.

no curl

If your system has wget and not curl you can also use wget -O - in place of curl. Otherwise download the bootstrap script into the project folder and call python bootstrap.py. (If you get setuptools issue, try python bootstrap.py -v 2.1.1)

buildout default.cfg

To prevent buildout from cluttering your working directory with an eggs/ directory, you should consider using a ~/.buildout/default.cfg:

export "BDIR=$HOME/.buildout"
mkdir -p $BDIR/eggs $BDIR/extends $BDIR/cache
echo "[buildout]" >> $BDIR/default.cfg
echo "eggs-directory = $BDIR/eggs" >> $BDIR/default.cfg
echo "download-cache = $BDIR/cache" >> $BDIR/default.cfg
echo "extends-cache = $BDIR/extends" >> $BDIR/default.cfg

After doing that, cleaning your clone with git clean -xfd and redoing the Bootstrap part is recommended.