Merge pull request #136 from pipermerriam/piper/re-organize-providers…

…-and-document-providers

reorganize and document providers

conftest.py

@@ -2,8 +2,10 @@
 
 import gevent
 
-from web3.providers.tester import EthereumTesterProvider
-from web3.providers.rpc import TestRPCProvider
+from web3.providers.tester import (
+    EthereumTesterProvider,
+    TestRPCProvider,
+)
 from web3.main import Web3
 
 

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.
 

tests/eth-module/test_eth_sign.py

@@ -6,7 +6,6 @@
 
 from ethereum.utils import privtoaddr
 
-from web3.providers.rpc import TestRPCProvider
 from web3.utils.crypto import (
     sha3 as _sha3,
 )

tests/providers/conftest.py

@@ -3,7 +3,14 @@
 from gevent import socket
 
 from web3.providers.ipc import IPCProvider
-from web3.providers.rpc import TestRPCProvider, RPCProvider, KeepAliveRPCProvider
+
+from web3.providers.rpc import (
+    RPCProvider,
+    KeepAliveRPCProvider,
+)
+from web3.providers.tester import (
+    TestRPCProvider,
+)
 
 
 def get_open_port():

tests/providers/test_testrpc_provider.py

@@ -2,7 +2,7 @@
 from gevent import socket
 
 from web3.providers.manager import RequestManager
-from web3.providers.rpc import (
+from web3.providers.tester import (
     TestRPCProvider,
     is_testrpc_available,
 )

web3/__init__.py

@@ -6,17 +6,23 @@
 from web3.providers.rpc import (
     RPCProvider,
     KeepAliveRPCProvider,
+)
+from web3.providers.tester import (
     TestRPCProvider,
+    EthereumTesterProvider,
+)
+from web3.providers.ipc import (
+    IPCProvider,
 )
-from web3.providers.ipc import IPCProvider
 
 __version__ = pkg_resources.get_distribution("web3").version
 
 __all__ = [
     "__version__",
     "Web3",
     "RPCProvider",
-    "TestRPCProvider",
     "KeepAliveRPCProvider",
     "IPCProvider",
+    "TestRPCProvider",
+    "EthereumTesterProvider",
 ]

web3/main.py

@@ -15,9 +15,14 @@
 from web3.providers.rpc import (
     RPCProvider,
     KeepAliveRPCProvider,
+)
+from web3.providers.tester import (
     TestRPCProvider,
+    EthereumTesterProvider,
+)
+from web3.providers.ipc import (
+    IPCProvider,
 )
-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,37 +160,3 @@ def make_request(self, method, params):
         response = self.client.post(self.path, body=request_data)
         response_body = response.read()
         return response_body
-
-
-def is_testrpc_available():
-    try:
-        import testrpc  # noqa: F401
-        return True
-    except ImportError:
-        return False
-
-
-class TestRPCProvider(RPCProvider):
-    def __init__(self, host="127.0.0.1", port=8545, *args, **kwargs):
-        if not is_testrpc_available():
-            raise Exception("`TestRPCProvider` requires the `eth-testrpc` package to be installed")
-        from gevent.pywsgi import WSGIServer
-        from testrpc.server import get_application
-
-        try:
-            logger = kwargs.pop('logger')
-        except KeyError:
-            logger = logging.getLogger('testrpc')
-
-        application = get_application()
-
-        self.server = WSGIServer(
-            (host, port),
-            application,
-            log=logger,
-            error_log=logger,
-        )
-
-        self.thread = gevent.spawn(self.server.serve_forever)
-
-        super(TestRPCProvider, self).__init__(host, str(port), *args, **kwargs)

web3/providers/tester.py

@@ -1,8 +1,11 @@
 import logging
 
+import gevent
+
 from testrpc.rpc import RPCMethods
 
 from .base import BaseProvider  # noqa: E402
+from .rpc import RPCProvider  # noqa: E402
 
 
 logger = logging.getLogger(__name__)
@@ -47,3 +50,29 @@ def make_request(self, method, params):
 
     def isConnected(self):
         return True
+
+
+class TestRPCProvider(RPCProvider):
+    def __init__(self, host="127.0.0.1", port=8545, *args, **kwargs):
+        if not is_testrpc_available():
+            raise Exception("`TestRPCProvider` requires the `eth-testrpc` package to be installed")
+        from gevent.pywsgi import WSGIServer
+        from testrpc.server import get_application
+
+        try:
+            logger = kwargs.pop('logger')
+        except KeyError:
+            logger = logging.getLogger('testrpc')
+
+        application = get_application()
+
+        self.server = WSGIServer(
+            (host, port),
+            application,
+            log=logger,
+            error_log=logger,
+        )
+
+        self.thread = gevent.spawn(self.server.serve_forever)
+
+        super(TestRPCProvider, self).__init__(host, str(port), *args, **kwargs)