basic structure in place now

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.

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.

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'``.

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.

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.

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

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.

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.

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.

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.

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

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

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.

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):

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