reorganize and document providers

docs/index.rst

@@ -17,6 +17,7 @@ Contents
     filters
     contracts
     managers
+    providers
     web3.main
     web3.eth
     web3.db

docs/providers.rst

@@ -0,0 +1,54 @@
+Providers
+========
+
+.. py:module:: web3.providers
+
+
+Providers are in control of the actual interactions with the blockchain.
+
+
+.. py:currentmodule:: web3.providers.rpc
+
+
+RPCProvider
+-----------
+
+.. py:class:: RPCProvider(host="127.0.0.1", port=8545, path="/", ssl=False, connection_timeout=10, network_timeout=10)
+
+    This provider handles interaction with an HTTP or HTTPS based JSON-RPC
+    server.
+
+
+.. py:currentmodule:: web3.providers.ipc
+
+
+IPCProvider
+-----------
+
+.. py:class:: IPCProvider(ipc_path=None, testnet=False):
+
+    This provider handles interaction with an IPC Socket based JSON-RPC
+    server.
+
+
+.. py:currentmodule:: web3.providers.tester
+
+
+EthereumTesterProvider
+----------------------
+
+.. py:class:: EthereumTesterProvider():
+
+    This provider can be used for testing.  It uses an ephemeral blockchain
+    backed by the ``ethereum.tester`` module.
+
+
+TestRPCProvider
+---------------
+
+.. py:class:: TestRPCProvider():
+
+    This provider can be used for testing.  It uses an ephemeral blockchain
+    backed by the ``ethereum.tester`` module.  This provider will be slower
+    than the ``EthereumTesterProvider`` since it uses an HTTP server for RPC
+    interactions with.

docs/quickstart.rst

@@ -13,6 +13,13 @@ Web3.py can be installed using ``pip`` as follows.
 
    $ pip install web3
 
+Or to install with support for the ``TestRPCProvider`` and
+``EthereumTesterProvider`` you can use this install command.
+
+.. code-block:: shell
+
+   $ pip install web3[Tester]
+
 Installation from source can be done from the root of the project with the
 following command.
 

web3/__init__.py

@@ -6,9 +6,14 @@ from web3.main import Web3
 from web3.providers.rpc import (
     RPCProvider,
     KeepAliveRPCProvider,
-    TestRPCProvider,
 )
-from web3.providers.ipc import IPCProvider
+from web3.providers.tester import (
+    TestRPCProvider,
+    EthereumTesterProvider,
+)
+from web3.providers.ipc import (
+    IPCProvider,
+)
 
 __version__ = pkg_resources.get_distribution("web3").version
 
@@ -16,7 +21,8 @@ __all__ = [
     "__version__",
     "Web3",
     "RPCProvider",
-    "TestRPCProvider",
     "KeepAliveRPCProvider",
     "IPCProvider",
+    "TestRPCProvider",
+    "EthereumTesterProvider",
 ]

web3/main.py

@@ -15,9 +15,14 @@ from web3.iban import Iban
 from web3.providers.rpc import (
     RPCProvider,
     KeepAliveRPCProvider,
-    TestRPCProvider,
 )
-from web3.providers.ipc import IPCProvider
+from web3.providers.tester import (
+    TestRPCProvider,
+    EthereumTesterProvider,
+)
+from web3.providers.ipc import (
+    IPCProvider,
+)
 from web3.providers.manager import (
     RequestManager,
     DelegatedSigningManager,
@@ -55,6 +60,7 @@ class Web3(object):
     KeepAliveRPCProvider = KeepAliveRPCProvider
     IPCProvider = IPCProvider
     TestRPCProvider = TestRPCProvider
+    EthereumTesterProvider = EthereumTesterProvider
 
     # Managers
     RequestManager = RequestManager

web3/providers/rpc.py

@@ -1,5 +1,4 @@
 import contextlib
-import gevent
 from geventhttpclient import HTTPClient
 import logging
 
@@ -161,6 +160,7 @@ class KeepAliveRPCProvider(JSONBaseProvider):
         response = self.client.post(self.path, body=request_data)
         response_body = response.read()
         return response_body
+<<<<<<< Updated upstream
 
 
 def is_testrpc_available():
@@ -195,3 +195,5 @@ class TestRPCProvider(RPCProvider):
         self.thread = gevent.spawn(self.server.serve_forever)
 
         super(TestRPCProvider, self).__init__(host, str(port), *args, **kwargs)
+=======
+>>>>>>> Stashed changes