zillionare-core-types 0.6.3

1. Usage

To use zillionare core types in a project

    from coretypes import Frame, FrameType

2. Features

本模块提供了在 Zillionare 中的核心类型定义。主要有：

1. 基础数据结构类的定义，比如时间帧类型 FrameType （对应于其它框架中可能使用的字符串 '1m', '1d'之类的定义）， 时间日期类型 Frame， 证券类型定义 FrameType 等。在几乎所有需要使用行情数据的地方，您都应该使用这些类型定义。
2. 交易错误类型，比如 NocashError （现金不足以完成交易错误）等等。
3. QuotesFetcher 接口定义。如果您要将其它数据源接入到 zillionare 中，就需要实现这个接口，按照定义返回相应的数据。一旦实现了此接口，就可以在 zillionare-omega 配置文件中配置接口，以例 omega 可以自动启用这个 adaptor 来获取数据。

2.1. 基础数据结构定义

基础数据结构定义中，共有两种类型。一种是用以静态类型检查使用的，通常 IDE，mypy 这样一些工具会利用它，以检测编码错误，或者提供自动完成。比如， BarsArray 就是这样一个类型，我们可以用它来声明一个行情函数的返回值类型。它的特点时，以目前的 Python 版本（截止到 Python3.8) 来看，类型信息无法在运行时访问到。

另一类则是运行时类型，比如 FrameType 等。

2.1.1. FrameType

行情数据都是按帧进行封装的，比如，每 1 分钟为一个单位，封装了高开低收、成交量等信息。这样的单位常常还有 5 分钟，15 分钟，日线等等。 FrameType 列举了在 Zillionare 中常用的帧类型。在其它软件中，您可能看到unit或者peroid、周期等说法。当然，可能 FrameType 是最精准的一个词。

Zillionare 提供了以下对应帧类型：

FrameType还提供了 <, <=, >=, >等比较运算。

2.1.2. SecurityType

常见的证券交易品种定义。

它的一个用法是，在我们查询证券列表中，有哪些股票类型的代码时：

secs = await Security.select().types(SecurityType.STOCK).eval()
print(secs)

2.1.3. MarketType

市场类型。Zillionare支持的类型为上交所XSHG和XSHE

2.1.4. bars_dtype

在zillionare中，我们一般使用 Numpy Structured Array来存储行情数据，以使用numpy的许多性能算法进行运算。同时，它也比pandas.DataFrame更省内存，在小数据集（<50万条）时，多数运算（但不是每一种运算）会有更高的性能。

要使用 Numpy Structured Array来表示行情数据，就需要定义定段列表。 bars_dtype就是这样的列表，它包括了字段（frame, open, high, low, close, volume, amount, factor)。

bars_dtype = np.dtype(
    [
        ("frame", "datetime64[s]"),
        ("open", "f4"),
        ("high", "f4"),
        ("low", "f4"),
        ("close", "f4"),
        ("volume", "f8"),
        ("amount", "f8"),
        ("factor", "f4"),
    ]
)

2.1.5. bars_dtype_with_code

在 bars_dtype基础上增加了code字段，以用于同时存取多个证券的行情的情况。

bars_dtype_with_code = np.dtype(
    [
        ("code", "O"),
        ("frame", "datetime64[s]"),
        ("open", "f4"),
        ("high", "f4"),
        ("low", "f4"),
        ("close", "f4"),
        ("volume", "f8"),
        ("amount", "f8"),
        ("factor", "f4"),
    ]
)

2.1.6. bars_cols、bars_with_limit_dtype, bars_with_limit_cols

即定义在bars_dtype中的字段列表。有时候我们需要在numpy与pandas dataframe之间进行转换时，往往需要这个变量的值。

bars_with_limit_dtype提供了带涨跌停报价的行情数据类型。

bars_with_limit_cols提供了定义在bars_with_limit_dtype中的字段名列表。

2.1.7. BarsArray

可用此静态类型作为行情数据（常用变量名 bars)的type hint，对应于bars_dtype。

2.1.8. BarsWithLimitArray

同BarsArray，但带涨跌停报价，对应于bars_with_limit_array。

2.1.9. BarsPanel

对应于bars_dtype_with_code的type hint类型。

2.1.10. xrxd_info_dtype

除权除息信息类型

2.1.11. security_info_dtype

定义了证券列表的字段

2.2. Trade Errors

在coretypes.errors.trade中，定义了交易中常常可能出现的异常类型。在TradeClient, TraderServer和Backtesting Server间常常都需要使用它。

我们把Trade Errors分为客户端错误 coretypes.errors.trade.client.*, coretypes.errors.trade.server.*, coretypes.errors.trade.entrust.*三种类型，分别表明客户端编码、传参错误；服务器内部错误和交易类型错误。

!!! Tips 对开发者而言，如果需要将此类异常传入到客户端，需要通过 TraderError.as_json将其串行化后再通过网络发送，在客户端则可以通过TraderError.from_json将其恢复。

为方便查错，服务器在生成TradeError时，可以传入`with_stack=True`，这样生成的TraderError(及子类)中，将包含调用栈信息（在`stack`属性中），以方便查错。

def foo():
    try:
        raise TraderError("mock error", with_stack=True)
    except TradeError as e:
        print(e.stack)

2.3. QuotesFetcher

Zillionare目前只适配了聚宽的数据源，但我们通过 QuotesFetcher 让您可以自行适配其它数据源。

你需要实现定义在 QuotesFetcher中的接口，然后在omega的配置文件中，加载您的实现。

具体实现可以参考 omega-jqadaptor

配置可以参见omega-config

# defaults.yaml

quotes_fetchers:
  - impl: jqadaptor    # there must be a create_instance method in this module
    account: ${JQ_ACCOUNT}
    password: ${JQ_PASSWORD}

3. Credits

本项目使用ppw创建，并遵循ppw定义的代码风格和质量规范。