SmartBus client Python wrapper

内容

smartbus-client-python

smartbus-client-python 是和声(广州)的实时媒体流程服务器IPSC专用的消息总线客户端的Python包装。

它用于向Python开发者提供SmartBus的客户端功能。

特点

  • 直接封装SmartBus的C语言实现客户端
  • 采用Python标准库的ctypes进行C语言动态/共享库的封装。所以安装时不需要进行编译，理论上同时支持多种Python（如pypy,ironpython,jython）运行时（只要目标Python运行时支持ctypes）
  • 完整的SmartBus客户端功能包装。其功能基本上与C语言实现客户端一对一。

参考

SmartBus C语言实现客户端 https://github.com/Hesong-OpenSource/smartbus-client-sdk

安装

访问 https://pypi.python.org/pypi/smartbus-client-python 获取包信息

通过 PYPI 在线安装
pip install smartbus-client-python
下载离线安装包

下载程序包，解压，然后执行:

python setup.py

注意

在安装好 Python 程序包之后，还需要下载目标平台的动态/共享库，并将DLL或者SO文件复制到运行目录。 访问 https://github.com/Hesong-OpenSource/smartbus-client-sdk 可下载库文件

smartbus

smartbus package

Subpackages
smartbus.ipcclient package
Submodules
smartbus.ipcclient.client module

smartbus 进程间通信客户端的Python接口类客户端类型

author:刘雪彦
date:2013-6-8
class smartbus.ipcclient.client.Client(username=None, password=None, extInfo=None, encoding='utf-8')

基类：builtins.object

SmartBus IPC 客户端类

这个类封装了 SmartBus IPC 客户端的一系列方法与事件

addr_expr
clientid
clienttype
connect(username=None, password=None)

连接服务器

参数:
  • username (str) – 连接用户名
  • password (str) – 连接密码
  • info (str) – 自定义连接信息
Exc:

如果连接失败，则抛出 ConnectError 异常
classmethod finalize()

释放库

get_addr_expr()
get_clientid()
get_clienttype()
get_unitid()
classmethod initialize(clientid, clienttype, onglobalconnect=None, libraryfile='libbusipccli.so', logging_option=(True, 10, 40))

初始化

这是一个类方法。调用其他方法前，必须首先使用这个方法初始化库。

参数:
  • clientid – 客户端ID。在同一个节点中，ID必须唯一。不得小于等于16
  • clienttype – 客户端类型。
  • onglobalconnect –
  • libraryfile –
..note:: 其搜索的目录次序为：
系统目录、../cdll/${system}/${machine}、 运行目录、当前目录、本文件目录
classmethod instance(username=None, password=None, extInfo=None)

返回该类型的实例

注解

由于一个进程只能有一个实例，所以可用该方法返回目前的实例。

invokeFlow(server, process, project, flow, parameters=, []isNeedReturn=True, timeout=30)

调用流程

参数:
  • server (int) – IPSC流程服务所在节点
  • process (int) – IPSC进程索引值，同时也是该IPSC进程的 smartbus client-id
  • project (str) – 流程项目名称
  • flow (str) – 流程名称
  • parameters (简单数据或者由简单数据组合成的int, float, str, bool , dict，或者它们的再组合数据类型。) – 流程传入参数
  • isNeedReturn (bool) – 是否需要流程返回值
  • timeout (int or float) – 等待流程返回超时值，单位为秒。
返回:

当需要等待流程返回值时，该返回值是 onInvokeFlowRespond() “流程返回事件”中对应的ID.
返回类型:

int
classmethod isInitialized()

判断是否初始化

返回:是否已经初始化
返回类型:bool
library
onConnectFail(unitId, errno)

连接失败事件

参数:
  • unitId (int) – 单元ID
  • errno (int) – 错误编码
onConnectSuccess(unitId)

连接成功事件

参数:unitId (int) – 单元ID
onDisconnect()

连接中断事件

onInvokeFlowAcknowledge(packInfo, project, invokeId, ack, msg)

收到流程执行回执事件

在调用流程之后，通过该回调函数类型获知流程调用是否成功

参数:
  • packInfo (smartbus.PackInfo) – 数据包信息
  • project (str) – 流程项目ID
  • invokeId (int) – 调用ID
  • ack (int) – 流程调用是否成功。1表示成功，其它请参靠考误码
  • msg (str) – 调用失败时的信息描述
onInvokeFlowError(packInfo, project, invokeId, errno)

流程调用错误事件

参数:
  • packInfo (smartbus.PackInfo) – 数据包信息
  • project (str) – 流程项目ID
  • invokeId (int) – 调用ID
  • errno (int) – 错误码
onInvokeFlowRespond(packInfo, project, invokeId, result)

收到流程返回数据事件

通过类类型的回调函数，获取被调用流程的“子项目结束”节点的返回值列表

参数:
  • packInfo (smartbus.PackInfo) – 数据包信息
  • project (str) – 流程项目ID
  • invokeId (int) – 调用ID
  • result (int) – 返回的数据。JSON数组格式
onInvokeFlowTimeout(packInfo, project, invokeId)

流程返回超时事件

参数:
  • packInfo (smartbus.PackInfo) – 数据包信息
  • project (str) – 流程项目ID
  • invokeId (int) – 调用ID
onReceiveText(packInfo, txt)

收到文本事件

参数:
  • packInfo (smartbus.PackInfo) – 数据包信息
  • txt (str) – 收到的文本
ping(dstUnitId, dstClientId, dstClientType, data, encoding=None)

发送PING命令

参数:
  • dstUnitId (int) – 目标的smartbus单元ID
  • dstClientId (int) – 目标的smartbus客户端ID
  • dstClientType (int) – 目标的smartbus客户端类型
  • data (str) – 要发送的数据
  • encoding (str) – 数据的编码。 默认值为None，表示使用 smartbus.ipcclient.client.Client.encoding
send(cmd, cmdType, dstUnitId, dstClientId, dstClientType, data, encoding=None)

发送数据

参数:
  • cmd – 命令
  • cmdType – 命令类型
  • dstUnitId – 目标节点ID
  • dstClientId – 目标客户端ID
  • dstClientType – 目标客户端类型
  • data – 待发送数据，可以是文本或者字节数组
  • encoding – 文本的编码。默认为该对象的 encoding 属性
sendNotify(server, process, project, title, mode, expires, param)

发送通知消息

参数:
  • server (int) – 目标IPSC服务器smartbus单元ID
  • process (int) – IPSC进程ID，同时也是该IPSC进程的 smartbus client-id
  • project (str) – 流程项目ID
  • title (str) – 通知的标示
  • mode (int) – 调用模式。目前无意义，一律使用0
  • expires (int, float) – 消息有效期。单位秒
  • param (str) – 消息数据
返回:

> 0 invoke_id，调用ID。< 0 表示错误。
返回类型:

int
unitid
Module contents

smartbus 进程通信客户端的Python接口类

date:2013-1-28
author:lxy@hesong.net
smartbus.netclient package
Submodules
smartbus.netclient.client module

smartbus 网络通信客户端的Python接口类客户端类型

author:刘雪彦
date:2013-6-8
class smartbus.netclient.client.Client(localClientId, localClientType, masterHost, masterPort, slaverHost=None, slaverPort=65535, authorUsr=None, authorPwd=None, extInfo=None, encoding='utf-8')

基类：builtins.object

SmartBus Network 客户端类

这个类封装了 SmartBus Network 客户端的一系列方法与事件

addr_expr
authorPwd

密码

authorUsr

登录名

connect()

连接到服务器

Exc:如果连接失败，则抛出 ConnectError 异常
dispose()

释放客户端

encoding

收/发字符串时使用的编码。默认为 utils.default_encoding。

extInfo

连接附加信息

classmethod finalize()

释放库

classmethod getUnitId()
classmethod initialize(unitid, onglobalconnect=None, libraryfile='libbusnetcli.so', logging_option=(True, 10, 40))

初始化

调用其他方法前，必须首先初始化库

:param unitid:单元ID。在所连接到的SmartBus服务器上，每个客户端进程的单元ID都必须是全局唯一的。 :param onglobalconnect:全局连接事件回调函数 :param libraryfile:库文件。如果不指定该参数，则加载时，会自动搜索库文件，其搜索的目录次序为：系统目录、../cdll/${system}/${machine}、 运行目录、当前目录、本文件目录。见 _c_smartbus_netcli_interface.lib_filename :param logging_option:

invokeFlow(server, process, project, flow, parameters=, []isNeedReturn=True, timeout=30)

调用流程

参数:
  • server (int) – IPSC流程服务所在节点
  • process (int) – IPSC进程索引值，同时也是该IPSC进程的 smartbus client-id
  • project (str) – 流程项目名称
  • flow (str) – 流程名称
  • parameters (简单数据或者由简单数据组合成的int, float, str, bool , dict，或者它们的再组合数据类型。) – 流程传入参数
  • isNeedReturn (bool) – 是否需要流程返回值
  • timeout (int or float) – 等待流程返回超时值，单位为秒。
返回:

当需要等待流程返回值时，该返回值是 onInvokeFlowRespond() “流程返回事件”中对应的ID.
返回类型:

int
classmethod isInitialized()
localClientId

客户端ID

localClientType

客户端类型

masterHost

SmartBus 服务主机名

masterPort

SmartBus 服务端口

onConnectFail(unitId, errno)

连接失败事件

参数:
  • unitId (int) – 单元ID
  • errno (int) – 错误码
onConnectSuccess(unitId)

连接成功事件

参数:unitId (int) – 单元ID
onDisconnect()

连接中断事件

onInvokeFlowAcknowledge(packInfo, project, invokeId, ack, msg)

收到流程执行回执事件

在调用流程之后，通过该回调函数类型获知流程调用是否成功

参数:
  • packInfo (smartbus.PackInfo) – 数据包信息
  • project (str) – 流程项目ID
  • invokeId (int) – 调用ID
  • ack (int) – 流程调用是否成功。1表示成功，其它请参靠考误码
  • msg (str) – 调用失败时的信息描述
onInvokeFlowError(packInfo, project, invokeId, errno)

流程调用错误事件

参数:
  • packInfo (smartbus.PackInfo) – 数据包信息
  • project (str) – 流程项目ID
  • invokeId (int) – 调用ID
  • errno (int) – 错误码
onInvokeFlowRespond(packInfo, project, invokeId, result)

收到流程返回数据事件

通过类类型的回调函数，获取被调用流程的“子项目结束”节点的返回值列表

参数:
  • packInfo (smartbus.PackInfo) – 数据包信息
  • project (str) – 流程项目ID
  • invokeId (int) – 调用ID
  • result (int) – 返回的数据。JSON数组格式
onInvokeFlowTimeout(packInfo, project, invokeId)

流程返回超时事件

参数:
  • packInfo (smartbus.PackInfo) – 数据包信息
  • project (str) – 流程项目ID
  • invokeId (int) – 调用ID
onReceiveText(packInfo, txt)

收到文本事件

参数:
  • packInfo (smartbus.PackInfo) – 数据包信息
  • txt (str) – 收到的文本
ping(dstUnitId, dstClientId, dstClientType, data, encoding=None)

发送PING命令

参数:
  • dstUnitId (int) – 目标的smartbus单元ID
  • dstClientId (int) – 目标的smartbus客户端ID
  • dstClientType (int) – 目标的smartbus客户端类型
  • data (str) – 要发送的数据
  • encoding (str) – 数据的编码。 默认值为None，表示使用 smartbus.netlient.client.Client.encoding
send(cmd, cmdType, dstUnitId, dstClientId, dstClientType, data, encoding=None)

发送数据

参数:
  • cmd – 命令
  • cmdType – 命令类型
  • dstUnitId – 目标节点ID
  • dstClientId – 目标客户端ID
  • dstClientType – 目标客户端类型
  • data – 待发送数据，可以是文本或者字节数组
  • encoding – 文本的编码。默认为该对象的 encoding 属性
sendNotify(server, process, project, title, mode, expires, param)

发送通知消息

参数:
  • server (int) – 目标IPSC服务器smartbus单元ID
  • process (int) – IPSC进程ID，同时也是该IPSC进程的 smartbus client-id
  • project (str) – 流程项目ID。None或者空表示不指明特定流程
  • title (str) – 通知的标示
  • mode (int) – 调用模式。目前无意义，一律使用0
  • expires (int, float) – 消息有效期。单位秒
  • param (str) – 消息数据
返回:

> 0 invoke_id，调用ID。< 0 表示错误。
返回类型:

int
slaverHost

SmartBus 从服务主机名

slaverPort

SmartBus 从服务端口

unitid

客户端的单元ID

Module contents

smartbus 网络通信客户端的Python接口类

date:2013-2-3
author:lxy@hesong.net
Submodules
smartbus.errors module

错误信息定义

date:2013-6-8
author:lxy@hesong.ent
exception smartbus.errors.AlreadyExistsError

基类：builtins.Exception

对象已经存在，无法再次新建

exception smartbus.errors.AlreadyInitializedError

基类：builtins.Exception

已经初始化，无法重复的初始化

exception smartbus.errors.InvokeFlowIdError

基类：builtins.Exception

收到调用流程的返回结果时，ID无法匹配

exception smartbus.errors.NotInitializedError

基类：builtins.Exception

尚未初始化，无法使用

exception smartbus.errors.SmartBusError(code, message)

基类：builtins.Exception

SmartBus 通信错误

code

SmartBus错误码

message

错误信息

smartbus.errors.check_restval(code, raise_if_err=True)

检查 SmartBus 客户端 C-API 的返回结果是否正确

参数:
  • code (int) – 要检查的返回结果编码
  • raise_if_err (bool) – 是否在发现错误时抛出异常。默认为真。
返回:

当 raise_if_err 为 True 时，无错误则返回 None，有错误则抛出错误异常； 当 raise_if_err 为 False 时，无错误则返回 None，有错误则返回错误异常实例。
smartbus.utils module

辅助功能 :date: 2013-3-4 :author: tanbro

smartbus.utils.default_encoding = 'utf-8'

默认编码

为 sys.getdefaultencoding() 的返回值

smartbus.utils.ifnone(a, b)

如果第一个参数为None，则返回第二个参数，否则返回第一个参数 :param a: 第一个参数 :param b: 第二个参数 :return: 如果 a 为 None，则返回 b，否则返回 a。

相当于：

def ifnone(a, b):
   if a is None:
       return b
   else:
       return a

例如：

v1 = 1
v2 = 2
ifnone(v1, v2)

那么，返回值为1。

如果：

v1 = None
v2 = 2
ifnone(v1, v2)

那么，返回值为2。

smartbus.utils.unicode

str 的别名

smartbus.utils.to_bytes(s, encoding='utf-8')

将 str 转为 bytes

参数:
  • s (str, unicode, bytes, None) – 要转换的字符串
  • encoding – 编码，默认为系统编码。
smartbus.utils.to_unicode(s, encoding='utf-8')

将 str 转为 unicode

参数:
  • s (str, unicode, bytes, None) – 要转换的字符串
  • encoding – 编码，默认为系统编码。
smartbus.utils.to_str(s, encoding='utf-8')

将 unicode 或者 bytes 转为系统 str

Module contents

smartbus 的Python封装

包括 net 与 ipc 客户端的Python类型封装

date:2013-7-14
author:刘雪彦