web3utils.py - Some sugar on top of web3.py

web3utils is a thin layer over web3.py with these features:

• immediate access to a web3 and eth object, if you have a standard setup
• shorter way to call contract functions
• autoset encoding of input value to web3.sha3(value), if type(value) == bytes

This handful of changes made for quicker shell usage and coding for me. I hope it does for you, too!

I intend to push these pieces upstream to web3.py, if they are open to it.

Setup

Note: web3utils requires Python 3

To use the web3utils library

pip install web3utils

To contribute to the web3utils library

git clone git@github.com/carver/web3utils.py.git
virtualenv -p python3 venv
. venv/bin/activate
pip install -r requirements-dev.txt
pip install -e .

Usage

Instant access to web3 and eth

Print your primary account balance, denominated in ether:

from web3utils import web3, eth

wei = eth.getBalance(eth.accounts[0])
balance = web3.fromWei(wei, 'ether')

print(balance)

Compare this to web3.py:

from web3 import Web3, IPCProvider

web3 = Web3(IPCProvider())

wei = web3.eth.getBalance(web3.eth.accounts[0])
balance = web3.fromWei(wei, 'ether')

print(balance)

It's a small imporvement, but nice at the command line.

Succinct contract access

Several important changes:

• quicker method calls like contract.owner() instead of contract.call().owner()
• encode all method argument strings as utf-8 (like Solidity)
• instead of returning "0x000..." on empty results, return None

Short contract calls will be assumed to be read-only (equivalent to .call() in web3.py), unless it is modified first.

Note that this will not prevent you from calling a method that tries to alter state. That state change will just never be sent to the rest of the network as a transaction.

You can switch back to a transaction like so:

contract.withdraw(amount, transact={'from': eth.accounts[1], 'gas': 100000, ...})

Which is equivalent to this web3.py approach:

contract.transact({'from': eth.accounts[1], 'gas': 100000, ...}).withdraw(amount)

Why is Python 3 required?

Short version

It turns out that the distinction between str and bytes is important. If you want to write code for the future (Ethereum), don't use a language from the past.

Long version

Interacting with the EVM requires clarity on the bits you're using. For example, a sha3 hash expects to receive a series of bytes to process. Calculating the sha3 hash of a string is (or should be) a Type Error; the hash algorithm doesn't know what to do with a series of characters, aka Unicode code points. As the caller, you need to know which thing you're calculating the hash of:

1. a series of bytes: b'[ c$o!\x91\xf1\x8f&u\xce\xdb\x8b(\x10.\x95tX'
2. the bytes represented by a string in hex format: '0x5b2063246f2191f18f2675cedb8b28102e957458'
3. the bytes generated by encoding a string using utf-8: Oops, these bytes cannot be read using utf-8
4. the bytes generated by encoding a string using utf-16: '⁛④Ⅿ\uf191⚏칵诛ဨ键塴'

Python 3 doesn't let you ignore a lot of these details. That's good, because precision with dealing with the EVM is critical. Ether is at stake.

If you are resistant -- I get it, I've been there. It is not intuitive for most people. But it's seriously worth it to learn about encoding if you're going to develop on top of Ethereum. Your money depends on it!

Wishlist

Filters can timeout and cause the following exception.

Instead, catch the exception in web3.py and notify watchers with an error (or even better, recreate the filter and pick up events where you left off)

Exception in thread Thread-22:8957
Traceback (most recent call last):
  File "/usr/lib/python2.7/threading.py", line 801, in __bootstrap_inner
    self.run()
  File "/usr/lib/python2.7/threading.py", line 754, in run
    self.__target(*self.__args, **self.__kwargs)
  File "/home/carver/filter_listener/venv/local/lib/python2.7/site-packages/web3/utils/filters.py", line 84, in _run
    changes = self.web3.eth.getFilterChanges(self.filter_id)
  File "/home/carver/filter_listener/venv/local/lib/python2.7/site-packages/web3/utils/functional.py", line 14, in inner
    value = fn(*args, **kwargs)
  File "/home/carver/filter_listener/venv/local/lib/python2.7/site-packages/web3/eth.py", line 312, in getFilterChanges
    "eth_getFilterChanges", [filter_id],
  File "/home/carver/filter_listener/venv/local/lib/python2.7/site-packages/web3/providers/manager.py", line 35, in request_blocking
    raise ValueError(response["error"])
ValueError: {u'message': u'filter not found', u'code': -32000}