Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/carver/web3utils.py

Convenience tools for web3.py
https://github.com/carver/web3utils.py

ethereum web3 web3py

Last synced: 26 days ago
JSON representation

Convenience tools for web3.py

Awesome Lists containing this project

README 

        

# 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 [email protected]/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}

```