diff --git a/docs/api.admin.rst b/docs/api.admin.rst new file mode 100644 index 0000000..482d104 --- /dev/null +++ b/docs/api.admin.rst @@ -0,0 +1,7 @@ +Admin API +====== + +.. py:class:: DB + +The ``web3.admin`` object exposes methods to interact with the RPC APIs under the +``admin_`` namespace. diff --git a/docs/api.db.rst b/docs/api.db.rst new file mode 100644 index 0000000..7d2a01d --- /dev/null +++ b/docs/api.db.rst @@ -0,0 +1,7 @@ +DB API +====== + +.. py:class:: DB + +The ``web3.db`` object exposes methods to interact with the RPC APIs under the +``db_`` namespace. diff --git a/docs/api.eth.rst b/docs/api.eth.rst new file mode 100644 index 0000000..bd91911 --- /dev/null +++ b/docs/api.eth.rst @@ -0,0 +1,17 @@ +Eth API +======= + +.. py:class:: Eth + +The ``web3.eth`` object exposes methods to interact with the RPC APIs under the +``eth_`` namespace. + +.. py::attribute:: Eth.defaultAccount + + The ethereum address that will be used as the default ``from`` address for + all transactions. This defaults to ``web3.eth.coinbase``. + +.. py::attribute:: Eth.defaultBlock + + The default block number that will be used for any RPC methods that accept + a block identifier. Defaults to ``'latest'``. diff --git a/docs/api.miner.rst b/docs/api.miner.rst new file mode 100644 index 0000000..b38c689 --- /dev/null +++ b/docs/api.miner.rst @@ -0,0 +1,7 @@ +Miner API +========= + +.. py:class:: DB + +The ``web3.miner`` object exposes methods to interact with the RPC APIs under +the ``miner_`` namespace. diff --git a/docs/api.personal.rst b/docs/api.personal.rst new file mode 100644 index 0000000..bbb806f --- /dev/null +++ b/docs/api.personal.rst @@ -0,0 +1,7 @@ +Personal API +============ + +.. py:class:: DB + +The ``web3.personal`` object exposes methods to interact with the RPC APIs +under the ``personal_`` namespace. diff --git a/docs/api.rst b/docs/api.rst new file mode 100644 index 0000000..33a405d --- /dev/null +++ b/docs/api.rst @@ -0,0 +1,153 @@ +Web3 API +======== + +.. contents:: :local: + + +.. py:class:: Web3(provider) + +Each ``web3`` instance exposes the following APIs. + +Providers +~~~~~~~~~ + +.. py:attribute:: Web3.RPCProvider + + Convenience API to access :py:class:`web3.providers.rpc.RPCProvider` + +.. py:attribute:: Web3.IPCProvider + + Convenience API to access :py:class:`web3.providers.rpc.IPCProvider` + +.. py:attribute:: Web3.TestRPCProvider + + Convenience API to access :py:class:`web3.providers.rpc.TestRPCProvider` + +.. py:method:: Web3.setProvider(provider) + + Updates the current web3 instance with the new provider. + +.. py:method:: Web3.sha3(value, encoding='hex') + + Returns the Keccak Sha3 of the given value. + + +Encoding and Decoding Helpers +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. py:staticmethod:: Web3.toHex(value) + + Returns the unpadded hexidecimal representation for the given + ``value``. This function supports the following types. + + * Booleans: Returns ``0x0`` or ``0x1`` + * Strings: Returns the string bytes in their hexidecimal representation. + * Integers: Returns the integer value in it's hexidecimal representation. + * Dictionaries: Returns the hexidecimal representation of the + dictionary converted to a JSON string. + +.. py:staticmethod:: Web3.toAscii(hex_value) + + Takes a hexidecimal value and returns it in its bytes representation. + +.. py:staticmethod:: Web3.toUtf8(value) + + Takes a hexidecimal value and returns it in its text representation. + +.. py:staticmethod:: Web3.fromAscii(value) + + Takes a byte string and returns its hexidecimal representation. + +.. py:staticmethod:: Web3.fromUtf8(value) + + Takes a text string and returns its hexidecimal representation. + +.. py:staticmethod:: Web3.toDecimal(value) + + Takes a hexidecimal value and returns it as its integer representation. + +.. py:staticmethod:: Web3.fromDecimal(value) + + Takes an integer value and returns its hexidecimal representation. + + +Currency Converstions +~~~~~~~~~~~~~~~~~~~~~ + +.. py:staticmethod:: Web3.toWei(value, unit) + + Takes a value in the given ``unit`` and returns it converted to Wei. + +.. py:staticmethod:: Web3.fromWei(value, unit) + + Takes a value in Wei and converts it to the given unit. + + .. note:: + + The return type of this function is a very high precision + ``decimal.Decimal`` value to ensure there are no rounding errors. + + +Addresses +~~~~~~~~~ + +.. py:staticmethod:: Web3.isAddress(value) + + Return boolean indicating whether the value passed in is a valid + hexidecimal encoded Ethereum address. + + * Allows for both ``0x`` prefixed and non-prefixed values. + * If the address contains mixed upper and lower cased characters this function also checks if the the address checksum is valid according to `EIP55`_ + + +.. py:staticmethod:: Web3.isChecksumAddress(address) + + Returns boolean as to whether the given address is checksummed according to + `EIP55`_ + +.. py:staticmethod:: Web3.toChecksumAddress(address) + + Returns the given address checksummed according to `EIP55`_ + + +RPC APIS +-------- + +Each ``web3`` instance also exposes these namespaced APIs. + + + +.. py:attribute:: Web3.eth + + See :doc:`./api.eth` + +.. py:attribute:: Web3.db + + See :doc:`./api.db` + +.. py:attribute:: Web3.shh + + See :doc:`./api.shh` + +.. py:attribute:: Web3.personal + + See :doc:`./api.personal` + +.. py:attribute:: Web3.version + + See :doc:`./api.version` + +.. py:attribute:: Web3.txpool + + See :doc:`./api.txpool` + +.. py:attribute:: Web3.miner + + See :doc:`./api.miner` + +.. py:attribute:: Web3.admin + + See :doc:`./api.admin` + + +.. _EIP55: https://github.com/ethereum/EIPs/issues/55 diff --git a/docs/api.shh.rst b/docs/api.shh.rst new file mode 100644 index 0000000..a132572 --- /dev/null +++ b/docs/api.shh.rst @@ -0,0 +1,7 @@ +SHH API +======= + +.. py:class:: DB + +The ``web3.shh`` object exposes methods to interact with the RPC APIs under the +``shh_`` namespace. diff --git a/docs/api.txpool.rst b/docs/api.txpool.rst new file mode 100644 index 0000000..756df16 --- /dev/null +++ b/docs/api.txpool.rst @@ -0,0 +1,7 @@ +TX Pool API +=========== + +.. py:class:: DB + +The ``web3.txpool`` object exposes methods to interact with the RPC APIs under +the ``txpool_`` namespace. diff --git a/docs/api.version.rst b/docs/api.version.rst new file mode 100644 index 0000000..3454c6a --- /dev/null +++ b/docs/api.version.rst @@ -0,0 +1,7 @@ +Version API +=========== + +.. py:class:: DB + +The ``web3.version`` object exposes methods to interact with the RPC APIs under +the ``version_`` namespace. diff --git a/docs/conventions.rst b/docs/conventions.rst new file mode 100644 index 0000000..5ccb6d0 --- /dev/null +++ b/docs/conventions.rst @@ -0,0 +1,16 @@ +Conventions +=========== + +The Web3 library follows the following conventions. + +Bytes vs Text +------------- + +* The term *bytes* is used to refer to the binary representation of a string. +* The term *text* is used to refer to unicode representations of strings. + +Hexidecimal Representations +--------------------------- + +* All hexidecimal values will be returned as text. +* All hexidecimal values will be ``0x`` prefixed. diff --git a/docs/index.rst b/docs/index.rst index 7bc54a1..987081d 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,9 @@ -Populus +Web3.py ======= -Populus is a smart contract development framework for the Ethereum blockchain. +Web3.py is a python library for interacting with Ethereum. It's API is derived +from the `Web3.js`_ Javascript API and should be familiar to anyone who has +used ``web3.js``. Contents @@ -12,15 +14,16 @@ Contents quickstart overview - tutorial - compile - testing - deploy - migrations - config - chain - release - modules + conventions + api + api.eth + api.db + api.shh + api.personal + api.version + api.txpool + api.miner + api.admin Indices and tables @@ -29,3 +32,6 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` + + +.. _Web3.js: https://github.com/ethereum/wiki/wiki/JavaScript-API diff --git a/docs/overview.rst b/docs/overview.rst index 61832b1..380caec 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -3,78 +3,4 @@ Overview .. contents:: :local: -Introduction ------------- - -The primary interface to populus is the command line command ``$ populus``. - - -Command Line Options --------------------- - -.. code-block:: shell - - $ populus - Usage: populus [OPTIONS] COMMAND [ARGS]... - - Populus - - Options: - -c, --config FILENAME Specify a populus configuration file to be used. No - other configuration files will be loaded - -h, --help Show this message and exit. - - Commands: - chain Manage and run ethereum blockchains. - compile Compile project contracts, storing their... - config Print the current project configuration - config:set Sets key/value pairs in the populus.ini... - config:unset Deletes the provided keys from the... - deploy Deploys the specified contracts to a chain. - init Generate project layout with an example... - makemigration Generate an empty migration. - migrate Run project migrations - - -Project Layout --------------- - -By default Populus expects a project to be layed out as follows. - -.. code-block:: shell - -    └── project root -    ├── build (automatically created during compilation) -    │   └── contracts.json -    ├── contracts -    | ├── MyContract.sol - | ├── .... -    └── tests -    ├── test_my_contract.py -    ├── test_some_other_tests.py - ├── .... -       └── .... - - -.. _init: - - -Initialize -~~~~~~~~~~ - -.. code-block:: shell - - $ populus init --help - Usage: populus init [OPTIONS] - - Generate project layout with an example contract. - - Options: - -h, --help Show this message and exit. - -Running ``$ populus init`` will initialize the current directory with the -default project layout that populus uses. - -* ``./contracts/`` -* ``./contracts/Greeter.sol`` -* ``./tests/test_greeter.py`` +TODO diff --git a/docs/quickstart.rst b/docs/quickstart.rst index 57a44ac..763724c 100644 --- a/docs/quickstart.rst +++ b/docs/quickstart.rst @@ -4,49 +4,14 @@ Quickstart .. contents:: :local: -System Dependencies -------------------- - -Populus depends on the following system dependencies. - -* `Solidity`_ : For contract compilation -* `Go Ethereum`_: For running test chains and contract deployment. - -In addition, populus needs some system dependencies to be able to install the -`PyEthereum`_ library. - -Debian, Ubuntu, Mint -~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: shell - - sudo apt-get install libssl-dev - - -Fedora, CentOS, RedHat -~~~~~~~~~~~~~~~~~~~~~~ - -.. code-block:: shell - - sudo yum install openssl-devel - - -OSX -~~~ - -.. code-block:: shell - - brew install pkg-config libffi autoconf automake libtool openssl - - Installation ------------ -Populus can be installed using ``pip`` as follows. +Web3.py can be installed using ``pip`` as follows. .. code-block:: shell - $ pip install populus + $ pip install web3 Installation from source can be done from the root of the project with the following command. @@ -56,102 +21,18 @@ following command. $ python setup.py install -Initializing a new project --------------------------- +The ``Web3`` object +------------------- -Populus can initialize your project using the ``$ populus init`` command. - -.. code-block:: shell - - $ populus init - Created Directory: ./contracts - Created Example Contract: ./contracts/Greeter.sol - Created Directory: ./tests - Created Example Tests: ./tests/test_greeter.py - - -Your project will now have a ``./contracts`` directory with a single Solidity -source file in it named ``Greeter.sol``, as well as a ``./tests`` directory -with a single test file named ``test_greeter.py``. - -Compiling your contracts ------------------------- - -Before you compile our project, lets take a look at the ``Greeter`` contract -that is generated as part of the project initialization. - - -.. code-block:: solidity - - contract Greeter { - string public greeting; - - function Greeter() { - greeting = "Hello"; - } - - function setGreeting(string _greeting) public { - greeting = _greeting; - } - - function greet() constant returns (string) { - return greeting; - } - } - -``Greeter`` is simple contract that is initialized with a default greeting of -the string ``'Hello'``. It exposes the ``greet`` function which returns -whatever string is set as the greeting, as well as a ``setGreeting`` function -which allows the greeting to be changed. - -You can now compile the contract using ``$ populus compile`` - - -.. code-block:: shell - - $ populus compile - ============ Compiling ============== - > Loading source files from: ./contracts - - > Found 1 contract source files - - contracts/Greeter.sol - - > Compiled 1 contracts - - Greeter - - > Wrote compiled assets to: ./build/contracts.json - - -Testing your contract ---------------------- - -Now that you have a basic contract you'll want to test that it behaves as -expected. The project should already have a test module named -``test_greeter.py`` located in the ``./tests`` directory that looks like the -following. +The common entrypoint for interacting with the Web3 library is the ``Web3`` +class. You will need to instantiate a web3 instance. .. code-block:: python - def test_greeter(chain): - greeter = chain.get_contract('Greeter') + >>> from web3 import Web, RPCProvider, IPCProvider + >>> web3 = Web3(RPCProvider(host='localhost', port='8545')) + # or for an IPC based connection + >>> web3 = Web3(IPCProvider()) - greeting = greeter.call().greet() - assert greeting == 'Hello' - - def test_custom_greeting(chain): - greeter = chain.get_contract('Greeter') - - set_txn_hash = greeter.transact().setGreeting('Guten Tag') - chain.wait.for_receipt(set_txn_hash) - - greeting = greeter.call().greet() - assert greeting == 'Guten Tag' - - -You should see two tests, one that tests the default greeting, and one that -tests that we can set a custom greeting. - - -.. _Go Ethereum: https://github.com/ethereum/go-ethereum/ -.. _Solidity: https://github.com/ethereum/solidity/ -.. _PyEthereum: https://github.com/ethereum/pyethereum/ +This ``web3`` instance will now allow you to interact with the Ethereum +blockchain. diff --git a/web3/main.py b/web3/main.py index 7f1a242..139d5ed 100644 --- a/web3/main.py +++ b/web3/main.py @@ -95,7 +95,7 @@ class Web3(object): if encoding == 'hex': hex_string = value else: - hex_string = encode_hex(value) + hex_string = to_hex(value) return self._requestManager.request_blocking('web3_sha3', [hex_string]) def isConnected(self): diff --git a/web3/utils/encoding.py b/web3/utils/encoding.py index 3716a54..50a0af8 100644 --- a/web3/utils/encoding.py +++ b/web3/utils/encoding.py @@ -6,8 +6,10 @@ from .types import ( is_string, is_boolean, is_object, + is_integer, ) from .string import ( + coerce_args_to_text, coerce_args_to_bytes, coerce_return_to_text, coerce_return_to_bytes, @@ -35,15 +37,16 @@ def encode_hex(value): return add_0x_prefix(codecs.encode(value, 'hex')) +@coerce_args_to_text def to_hex(value): """ - Auto converts any given value into it's hex representation. + Auto converts any supported value into it's hex representation. """ if is_boolean(value): return "0x1" if value else "0x0" if is_object(value): - return encode_hex(json.dumps(value)) + return encode_hex(json.dumps(value, sort_keys=True)) if is_string(value): if is_prefixed(value, '-0x'): @@ -53,7 +56,13 @@ def to_hex(value): else: return encode_hex(value) - return from_decimal(value) + if is_integer(value): + return from_decimal(value) + + raise TypeError( + "Unsupported type: '{0}'. Must be one of Boolean, Dictionary, String, " + "or Integer.".format(repr(type(value))) + ) def to_decimal(value): @@ -73,7 +82,7 @@ def to_decimal(value): def from_decimal(value): """ - Converts value to it's hex representation + Converts numeric value to it's hex representation """ if is_string(value): if is_0x_prefixed(value) or is_prefixed(value, '-0x'): @@ -81,5 +90,7 @@ def from_decimal(value): else: value = int(value) + # python2 longs end up with an `L` hanging off the end of their hexidecimal + # representation. result = hex(value).rstrip('L') return result