web3utils 0.1.3

Convenience tools for web3.py

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

web3utils is a thin layer over [web3.py](https://github.com/pipermerriam/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 [e-mail]/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](https://github.com/ethereum/wiki/wiki/Ethereum-Contract-ABI#argument-encoding))
* 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](https://www.joelonsoftware.com/2003/10/08/the-absolute-minimum-every-software-developer-absolutely-positively-must-know-about-unicode-and-character-sets-no-excuses/)
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}
```