Providers

providers 是web3如何与区块链交谈。providers 接受JSON-RPC请求并返回响应。这通常通过将请求提交给基于HTTP或IPC套接字的服务器来完成。

如果已经能够地连接到以太坊节点，那么可以跳过 providers 部分的其余部分。

Choosing How to Connect to Your Node

大多数节点都有多种连接方式。如果尚未确定要使用哪种节点，请转到如何选择要使用的节点？

连接节点的最常用方法是：

1. IPC（使用本地文件系统：最快，最安全）
2. Websockets（远程工作，比HTTP更快）
3. HTTP（更多节点支持它）

如果不确定如何决定，请选择以下方式：

• 如果可以选择在与节点相同的计算机上运行Web3.py，请选择IPC。
• 如果必须连接到其他计算机上的节点，请使用Websockets。
• 如果节点不支持Websockets，请使用HTTP。

大多数节点都有 “关闭” 连接选项的方法。我们建议关闭所有未使用的连接选项。这提供了更安全的设置：它减少了恶意黑客可以试图窃取我们的以太币的方式。

确定连接后，可以使用 Provider 指定详细信息。Providers 是为所需类型的连接配置的Web3.py类。

参考：

• IPCProvider
• WebsocketProvider
• HTTPProvider

配置 provider 后，例如：

from web3 import Web3
my_provider = Web3.IPCProvider('/my/node/ipc/path')

然后就可以初始化Web3实例了，如下所示：

w3 = Web3(my_provider)

最后，我们已准备好开始使用Web3.py.

Automatic vs Manual Providers

如果未指定 providers，<font color=red>Web3</font> 对象将在几个标准位置查找以太坊节点。初始化时会发生自动检测：

from web3.auto import w3

# which is equivalent to:

from web3 import Web3
w3 = Web3()

有时，web3无法自动检测节点的位置。

• 如果不确定使用哪种连接方法，请参阅选择如何连接到节点。
• 如果知道连接方法，但不知道连接所需的其他信息（如IPC文件的路径），则需要在节点的配置中查找该信息。
• 如果不确定使用的是哪个节点，请参阅如何选择要使用的节点？

要深入了解自动检测的工作原理，请参阅：

How Automated Detection Works

Web3尝试按以下顺序连接到节点，使用它可以进行的第一个成功连接：

1. 由环境变量指定的连接，请参阅通过环境变量的 Provider。
2. IPCProvider，它查找几个IPC文件位置。
3. HTTPProvider，尝试连接到 <font color=blue>“http://localhost:8545”</font>
4. 无 - 如果没有提供者成功，仍然可以使用不需要连接的Web3 API，例如：
   • Type Conversions
   • Currency Conversions
   • Addresses
   • Working with Local Private Keys
   • etc.

Examples Using Automated Detection

一些节点提供超出标准的API。有时，跨节点以不同方式提供相同的信息。如果要编写跨多个节点工作的代码，可能需要查找连接到的节点类型。

例如，以下内容检索geth和parity的客户端enode端点：

from web3.auto import w3

connected = w3.isConnected()

if connected and w3.version.node.startswith('Parity'):
    enode = w3.parity.enode

elif connected and w3.version.node.startswith('Geth'):
    enode = w3.admin.nodeInfo['enode']

else:
    enode = None

Provider via Environment Variable

或者，可以在启动脚本之前设置环境变量 <font color=red>WEB3_PROVIDER_URI</font>，web3将首先查找该 provider。

此环境变量的有效格式为：

• file:///path/to/node/rpc-json/file.ipc
• http://192.168.1.2:8545
• https://node.ontheweb.com
• ws://127.0.0.1:8546

Auto-initialization Provider Shortcuts

常见 provider 有几个自动初始化快捷方式。

Infura Mainnet

要轻松连接到Infura Mainnet远程节点，如果在 https://infura.io/signup 上没有API密钥，请先注册免费的API密钥。

然后使用API密钥设置环境变量 <font color=red>INFURA_API_KEY</font>：

$ export INFURA_API_KEY=YourApiKey

>>> from web3.auto.infura import w3

# confirm that the connection succeeded
>>> w3.isConnected()
True

特别说明：现在不需要注册，直接就能连接上。这个有点强大，可以直接与以太坊主网进行交互。不过安全性需要考虑，特别是涉及到创建账户、密码安全、资金安全等方面的内容时。

Built In Providers

Web3 附带以下 providers，这些 providers 适用于连接到本地和远程JSON-RPC服务器。

HTTPProvider

class web3.providers.rpc.HTTPProvider(endpoint_uri[, request_kwargs])

此 provider 处理与基于HTTP或HTTPS的JSON-RPC服务器的交互。

• <font color=red>endpoint_uri</font> 应该是RPC端点的完整URI，例如 “https:// localhost:8545”。对于在端口80上运行的HTTP连接后面的RPC服务器和在端口443上运行的HTTPS连接，可以从URI中省略该端口。
• <font color=red>request_kwargs</font> 这应该是关键字参数的字典，它将被传递到 http/https 请求。

>>> from web3 import Web3
>>> web3 = Web3(Web3.HTTPProvider("http://127.0.0.1:8545"))

请注意，每个python进程只应创建一个HTTPProvider，因为HTTPProvider会回收底层TCP/IP网络连接，以获得更好的性能。

在引擎下，HTTPProvider使用python请求库来发出请求。如果想修改请求的方式，可以使用 <font color=red>request_kwargs</font> 来执行此操作。一个常见的用例是增加每个请求的超时。

>>> from web3 import Web3
>>> web3 = Web3(Web3.HTTPProvider("http://127.0.0.1:8545", request_kwargs={'timeout': 60}))

IPCProvider

class web3.providers.ipc.IPCProvider(ipc_path=None, testnet=False, timeout=10)

此 provider 处理与基于IPC Socket的JSON-RPC服务器的交互。

• <font color=red>ipc_path</font> 是IPC套接字的文件系统路径 :56

>>> from web3 import Web3
>>> web3 = Web3(Web3.IPCProvider("~/Library/Ethereum/geth.ipc"))

如果没有指定 <font color=red>ipc_path</font>，它将使用它可以从此列表中找到的第一个IPC文件：

• On Linux and FreeBSD:
  • <font color=red>~/.ethereum/geth.ipc</font>
  • <font color=red>~/.local/share/io.parity.ethereum/jsonrpc.ipc</font>
• On Mac OS:
  • <font color=red>~/Library/Ethereum/geth.ipc</font>
  • <font color=red>~/Library/Application Support/io.parity.ethereum/jsonrpc.ipc</font>
• On Windows:
  • <font color=red>\.\pipe\geth.ipc</font>
  • <font color=red>\.\pipe\jsonrpc.ipc</font>

WebsocketProvider

class web3.providers.websocket.WebsocketProvider(endpoint_uri[, websocket_kwargs])

此 provider 处理与基于WS或WSS的JSON-RPC服务器的交互。

• <font color=red>endpoint_uri</font> 应该是RPC端点的完整URI，例如'ws://localhost:8546'。
• <font color=red>websocket_kwargs</font> 这应该是关键字参数的字典，它将被传递到 ws/wss websocket 连接。

在引擎下，WebsocketProvider使用python websockets库来发出请求。如果您想修改请求的方式，可以使用websocket_kwargs来执行此操作。一个常见的用例是增加每个请求的超时。

>>> from web3 import Web3
>>> web3 = Web3(Web3.WebsocketProvider("http://127.0.0.1:8546", websocket_kwargs={'timeout': 60}))

EthereumTesterProvider

Warning

实验：该 provider 是实验性的。功能方面仍存在重大差距。但是，它是web3.providers.tester.EthereumTesterProvider的默认替代品，并且正在积极开发和支持。

class web3.providers.eth_tester.EthereumTesterProvider(eth_tester=None)

该 provider 与 <font color=red>eth-tester</font> 库集成。 <font color=red>eth_tester</font> 构造函数参数应该是 <font color=red>eth-tester</font> 库提供的 EthereumTester 类的实例。如果希望使用自定义eth-tester实例进行测试，请参阅 <font color=red>eth-tester</font> 库文档以获取详细信息。

>>> from web3 import Web3, EthereumTesterProvider
>>> w3 = Web3(EthereumTesterProvider())

需要注意的问题

# ModuleNotFoundError: No module named 'eth_tester'
# pip install eth_tester

EthereumTesterProvider (legacy)

Warning

不推荐使用：不推荐使用此 provider，而使用EthereumTesterProvider和新创建的eth-tester。

class web3.providers.tester.EthereumTesterProvider

此 provider 可用于测试。它使用由ethereum.tester模块支持的短暂区块链。

>>> from web3 import Web3
>>> from web3.providers.tester import EthereumTesterProvider
>>> w3 = Web3(EthereumTesterProvider())

需要注意的问题

# Exception: `TestRPCProvider` requires the `eth-testrpc` package to be installed
# pip install eth-testrpc

TestRPCProvider

Warning

不推荐使用：不推荐使用此 provider，而使用EthereumTesterProvider和新创建的eth-tester。

class web3.providers.eth_tester.TestRPCProvider

此 provider 可用于测试。它使用由 <font color=red>ethereum.tester</font> 模块支持的短暂区块链。此提供程序将比 <font color=red>EthereumTesterProvider</font> 慢，因为它使用HTTP服务器进行RPC交互。

AutoProvider

AutoProvider 是在没有任何 provider 的情况下初始化web3.Web3时使用的默认设置。很少有理由明确使用它。

Using Multiple Providers

Web3支持使用多个 providers。这对于希望跨不同 providers 委派请求的情况非常有用。要使用此功能，只需使用可迭代的 provider 实例实例化web3实例。

>>> from web3 import Web3, HTTPProvider
>>> from . import MySpecialProvider
>>> special_provider = MySpecialProvider()
>>> infura_provider = HTTPProvider('https://ropsten.infura.io')
>>> web3 = Web3([special_provider, infura_provider])

当web3有多个 providers 时，它将按顺序迭代它们，尝试RPC请求并返回它收到的第一个响应。任何无法响应请求的 providers 都必须抛出 <font color=red>web3.exceptions.CannotHandleRequest</font> 异常。

如果配置的 providers 都不能处理请求，则将抛出 <font color=red>web3.exceptions.UnhandledRequest</font> 异常。

项目源代码

项目源代码会逐步上传到 Github，地址为 https://github.com/windstamp/jsonrpc。

Contributor

1. Windstamp, https://github.com/windstamp

Reference

1. https://web3py.readthedocs.io/en/stable/
2. http://web3py.readthedocs.io
3. https://github.com/ethereum/web3.py
4. https://infura.io/signup