stream-python-sdk 0.2

Stream Python SDK
==============

Stream Python SDK实现了Stream 日志操作接口，基于此SDK能方便快速地实现Python应用程序来对订阅日志进行相关操作。

支持的功能
----------

日志操作接口
^^^^^^^^^^^^

* Get Subscription Position —— 获取订阅日志位置
* Get Logs —— 获取指定订阅日志

接口实现
--------

在调用对象操作接口前需要生成一个stream_client.StreamClient类的实例。且在调用操作接口时，都有可能抛出异常，可以使用'stream.exceptions.ServiceException'捕获stream服务器异常错误，使用'stream.exceptions.ClientException'捕获stream客户端异常错误。

stream_client.StreamClient对象实例化

使用举例

::

client = stream_client.StreamClient(
access_key_id="string",
access_key_secret="string"
)

参数说明

* access_key_id(string) -- 访问凭证ID。
* access_key_secret(string) -- 访问凭证密钥。

stream_client.StreamClient可能引发的所有异常类型

在程序运行过程中，如果遇到错误，Python SDK会抛出相应的异常。所有异常均属于StreamException类，其下分为两个子类：ClientException、ServiceException。在调用Python SDK接口的时候，捕捉这些异常并打印必要的信息有利于定位问题。

ClientException
:::::::::::::::

ClientException包含SDK客户端的异常。比如，上传对象时对象名为空，就会抛出该异常。
ClientException类下有如下子类，用于细分客户端异常：

.. list-table::
:widths: 5 10
:header-rows: 1

* - 类名
- 抛出异常的原因
* - InvalidParameter
- 传入的参数非法
* - SerializationError
- 上传对象序列化失败
* - ConnectionError
- 连接服务端异常
* - ConnectionTimeout
- 连接服务端超时

ServiceException
::::::::::::::::

ServiceException包含Stream服务器返回的异常。当Stream服务器返回4xx或5xx的HTTP错误码时，Python SDK会将Stream Server的响应转换为ServiceException。
ServiceException类下有如下子类，用于细分Stream服务器返回的异常：

.. list-table::
:widths: 5 10
:header-rows: 1

* - 类名
- 抛出异常的原因
* - BadRequestError
- 服务端返回HTTP 400响应
* - ForbiddenError
- 服务端返回HTTP 403响应
* - NotFoundError
- 服务端返回HTTP 404响应
* - MethodNotAllowedError
- 服务端返回HTTP 405响应
* - ConflictError
- 服务端返回HTTP 409响应
* - LengthRequiredError
- 服务端返回HTTP 411响应
* - RequestedRangeNotSatisfiableError
- 服务端返回HTTP 416响应
* - InternalServerErrorError
- 服务端返回HTTP 500响应
* - NotImplementedError
- 服务端返回HTTP 501响应
* - ServiceUnavailableError
- 服务端返回HTTP 503响应

stream_client.StreamClient的使用和异常处理的示例代码

::

try:
resp = stream_client.StreamClient.XXX(
subscription_name=subscription_name,
position_type=position_type
)
except stream.exceptions.ServiceException as e:
print (
'ServiceException: %s\n'
'message: %s\n'
) % (
e,
e.message # 错误描述信息
)
except stream.exceptions.ClientException as e:
print (
'ClientException: %s\n'
'message: %s\n'
) % (
e,
e.message # 客户端错误信息
)

日志操作接口
^^^^^^^^^^^^

Get Subscription Position
:::::::::::::

使用举例

::

resp = client.get_subscription_position(
subscription_name=topic_name,
position_type=position_type
)

参数说明

* subscription_name(string) -- 订阅主题名称。
* position_type(string) -- 获取位置类型。

返回值举例

::

{
"position": "dGVzdDIw33YxMjE1MTkwMy5kZWZhdWx0LXdtM3pxOjEw"
}

返回值说明
返回值为字典类型

* position(string) -- 日志位置。


Get Logs
:::::::::::::::::::::::

使用举例

::

resp = client.get_logs(
subscription_name=topic_name,
logs_position=logs_position,
limit=limit
)

参数说明

* subscription_name(string) -- 订阅主题名称。
* logs_position(string) -- 日志位置。
* limit(int) -- 获取日志条数限制。

返回值举例

::

{
"subscription_logs": [
{
"timestamp": 1482467113427,
"message": "ksjfkajfkasfs"
}
],
"count": 1,
"next_position": "dGVzdDIwMTYxMjE1MTkwMy5kZWZhdWx0LXdtM3pxOjEx",
"reached_ending": false
}