简单的Python JsonRPC

一个小型库，用于与JsonRPC服务交互

包括一些辅助类，用于与各种加密货币守护程序交互，如bitcoind和litecoind

官方仓库： https://github.com/privex/python-jsonrpc

快速安装/使用

pip3 install privex-jsonrpc

from privex.jsonrpc import JsonRPC, RPCException
try:
    j = JsonRPC(hostname='api.example.com', port=443, ssl=True)
    # call JsonRPC methods as if they're part of the class. they return 'result' as dict/list/int/float/str
    j.list_all('first', 'second')    # 'params' as a list ['first', 'second']
    j.find(name='john')              # 'params' as a dict {name: 'john'}
except RPCException as e:   # raised when the result contains the key 'error' and it is not null/false
    log.exception('the rpc server returned an error: %s', str(e))
except:   # Any other exceptions (generally from the `requests` library) mean something is wrong with the server
    log.exception('something went wrong while communicating with the RPC server...')   

信息

此Python JsonRPC库由@someguy123在Privex Inc.开发，用于与各种JsonRPC服务交互，包括加密货币守护程序，如bitcoind。

它使用Python Requests库，包括一个单例请求会话，确保始终使用HTTP Keep-alive，保留cookie，以及其他一些提高性能的功能。

主要包括以下类

    JsonRPC        - The main universally-compatible class, works with most JsonRPC services without any modification.

    BitcoinRPC     - Constructor connects to 127.0.0.1:8332 by default. 
                     Includes a few pre-defined methods for interacting with `bitcoind` and similar daemons.

    LitecoinRPC    - Same as BitcoinRPC, except uses 127.0.0.1:9332 by default

    SteemEngineRPC - For interacting with SteemSmartContracts RPC (https://github.com/harpagon210/steemsmartcontracts)
                     Includes pre-defined methods for interacting with SSC RPC. 
                     Default host: https://api.steem-engine.com

    MoneroRPC      - For interacting with Monero Wallet RPC, includes various pre-defined methods to make things easier.

    ElectrumRPC    - For interacting with Electrum Wallet RPC, includes various pre-defined methods to make things easier.
                     Should work with Bitcoin Electrum, Electrum LTC, and others.

+===================================================+
|                 © 2019 Privex Inc.                |
|               https://www.privex.io               |
+===================================================+
|                                                   |
|        Python Simple JSON RPC library             |
|        License: X11/MIT                           |
|                                                   |
|        Core Developer(s):                         |
|                                                   |
|          (+)  Chris (@someguy123) [Privex]        |
|                                                   |
+===================================================+

Python JSON RPC - A simple library for interacting with JsonRPC services
Copyright (c) 2019    Privex Inc. ( https://www.privex.io )

安装

由于使用了参数和返回类型提示，我们建议您使用至少Python 3.4+。

使用pip从PyPi安装

您可以通过pip安装此软件包

pip3 install privex-jsonrpc

(替代) 从Git手动安装

如果您不想从PyPi安装（例如，对于尚未在PyPi上发布的开发版本），您可以直接从我们的Git仓库安装项目。

除非您有特定的原因要手动安装它，否则您应该像上面那样使用pip3正常安装。

选项1 - 使用pip从Github直接安装

pip3 install git+https://github.com/Privex/python-jsonrpc

选项2 - 克隆并手动安装

# Clone the repository from Github
git clone https://github.com/Privex/python-jsonrpc
cd python-jsonrpc

# RECOMMENDED MANUAL INSTALL METHOD
# Use pip to install the source code
pip3 install .

# ALTERNATIVE INSTALL METHOD
# If you don't have pip, or have issues with installing using it, then you can use setuptools instead.
python3 setup.py install

使用方法

从privex.jsonrpc导入您需要的类 - 所有类都通过init.py导出

基本使用

    from privex.jsonrpc import JsonRPC, RPCException
    try:
        j = JsonRPC(hostname='api.example.com', port=443, ssl=True)

        # Sends a POST request to https://api.example.com with the following data:
        # {id: 1, jsonrpc: '2.0', method: 'list_all', params: ['my first parameter']}
        data = j.list_all('my first parameter')    # returns: ['some', 'result', 'data', 'returned']
        print(data[0])    # prints 'some'

        # Sends a POST request to https://api.example.com with the following data:
        # {id: 2, jsonrpc: '2.0', method: 'find', params: {name: 'john'}}
        data = j.find(name='john')    # returns: {name: 'john', username: 'john123', created_at: '2019-01-01 00:00:00'}
        print(data['username'])       # prints 'john123'

        # If your JsonRPC call is not valid as a method name, use .call(method, *params, **args)
        # positional params are converted to a list, keyworg args are converted to a dict
        j.call('invalid-python.methodname', '1st param', '2nd param')
        j.call('some.find.func', name='john', user='john123')

    except RPCException as e:
        # RPCException is raised when the result contains the key 'error' and it is not null/false
        log.exception('the rpc server returned an error: %s', str(e))
    except:
        # Any other exceptions (generally from the `requests` library) mean something is wrong with the server
        log.exception('something went wrong while communicating with the RPC server...')    

即使方法未定义，您仍然可以使用它！只是您不会获得任何参数的IDE提示。

对于完整的参数文档，当您尝试使用类时，IDE如PyCharm甚至Visual Studio Code应该显示我们的PyDoc注释。

对于PyCharm，按键盘上的F1键，并将光标放在类上，以查看完整的功能文档，包括返回类型、参数和一般使用信息。您还可以在方法的大括号内（包括构造函数的大括号）按CMD-P键，以查看您可以使用的参数。

或者，只需查看privex/jsonrpc/目录下的文件——大多数方法和构造函数都有足够的PyDoc注释。

日志记录

默认情况下，此包将任何 >=WARNING 的内容记录到控制台。您可以通过调整privex.jsonrpc记录器实例来覆盖此设置。

我们建议您查看我们的Python包Python Loghelper，它使管理您的日志配置变得容易，并将其复制到其他日志实例，例如此实例。

# Without LogHelper
import logging
l = logging.getLogger('privex.jsonrpc')
l.setLevel(logging.ERROR)

# With LogHelper (pip3 install privex-loghelper)
from privex.loghelper import LogHelper
# Set up logging for **your entire app**. In this case, log only messages >=error
lh = LogHelper('myapp', handler_level=logging.ERROR)
lh.add_file_handler('test.log')      # Log messages to the file `test.log` in the current directory
lh.copy_logger('privex.jsonrpc')     # Easily copy your logging settings to any other module loggers
log = lh.get_logger()                # Grab your app's logging instance, or use logging.getLogger('myapp')
log.error('Hello World')

贡献

我们非常乐意接受拉取请求，并处理向我们报告的任何问题。

以下是一些重要信息

报告问题

• 对于错误报告，您应包括以下信息
  • 在测试privex-jsonrpc和requests的版本 - 使用pip3 freeze
    • 如果不是通过PyPi发布安装，则测试问题时使用的git修订版本号 - git log -n1
  • 您的python3版本 - python3 -V
  • 您的操作系统和操作系统版本（例如Ubuntu 18.04，Debian 7）
• 对于功能请求/更改
  • 请避免提出需要新依赖的建议。这个工具被设计为轻量级，不包含外部依赖。
  • 清楚地解释您想添加的功能/更改
  • 解释为什么这个功能/更改对我们或工具的其他用户有用
  • 请注意，添加复杂或我们认为对我们工具的使用不必要的功能/更改可能不会被添加（但我们可能接受PR）

拉取请求

• 我们将欣然接受仅添加代码注释或README更改的PR
• 在贡献代码时请使用4个空格，而不是制表符
• 您可以使用Python 3.4+中的功能（我们为我们的项目运行Python 3.7+）
  • 需要尚未发布于最新稳定版Ubuntu Server LTS（目前为Ubuntu 18.04 Bionic）的Python版本的特性将不予接受。
• 在标题和描述中清楚地说明您拉取请求的目的
  • 您做了哪些更改？
  • 为什么您要做出这些更改？
• 请确保代码贡献得到适当的注释——我们不会接受未注释或高度简短的代码行更改。

贡献的法定声明

没有人愿意阅读充满法律文字的长文档，所以我们将重要部分总结在这里。

如果您向Privex创建/拥有的项目（例如代码或文档）贡献了您创建/拥有的内容，那么您可能会自动授予我们使用您的内容的不受限制的权利，无论我们项目适用的开源许可证如何。

如果您不想授予我们您内容的不受限制的使用权，请确保将您的内容放置在单独的文件中，确保在文件开头（例如代码注释）或其包含的文件夹（例如名为LICENSE的文件）中清楚地显示您的内容许可证。

您应在您的拉取请求或问题中让我们知道您已包含受不同许可证许可的文件，以便我们可以确保没有可能阻止我们接受您的贡献的许可证冲突。

如果您想阅读完整的法律文本，它应包含为privex_contribution_agreement.txt。

许可证

本项目采用 X11 / MIT 许可证。请参阅 LICENSE 文件以获取详细信息。

以下是重要内容

• 如果您修改、分发或复制本项目的部分或全部内容，则必须包含/显示许可协议和版权声明（LICENSE）。
• 未经我们许可，您不能使用我们的名字来推广/支持您的产品。然而，您可以声明您的产品使用了本项目的部分或全部内容。

感谢阅读！

如果本项目对您有所帮助，请考虑从 Privex 购买 VPS 或专用服务器 - 价格低至每月仅 US$8（我们接受加密货币！）获取 VPS 或专用服务器。