https://github.com/zillionare/core-types
https://github.com/zillionare/core-types
Last synced: 9 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/zillionare/core-types
- Owner: zillionare
- License: mit
- Created: 2022-01-10T10:23:08.000Z (over 4 years ago)
- Default Branch: main
- Last Pushed: 2023-11-19T02:53:22.000Z (over 2 years ago)
- Last Synced: 2024-12-28T02:44:47.184Z (over 1 year ago)
- Language: Python
- Size: 1.09 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Changelog: HISTORY.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
## 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 提供了以下对应帧类型：
| 周期 | 字符串 | 类型 | 数值 |
| --------- | ------ | ----------------- | ---- |
| 年线 | 1Y | FrameType.YEAR | 10 |
| 季线 | 1Q | FrameType.QUARTER | 9 |
| 月线 | 1M | FrameType.MONTH | 8 |
| 周线 | 1W | FrameType.WEEK | 7 |
| 日线 | 1D | FrameType.DAY | 6 |
| 60 分钟线 | 60m | FrameType.MIN60 | 5 |
| 30 分钟线 | 30m | FrameType.MIN30 | 4 |
| 15 分钟线 | 15m | FrameType.MIN15 | 3 |
| 5 分钟线 | 5m | FrameType.MIN5 | 2 |
| 分钟线 | 1m | FrameType.MIN1 | 1 |
FrameType还提供了 `<`, `<=`, `>=`, `>`等比较运算。
#### 2.1.2. SecurityType
常见的证券交易品种定义。
| 类型 | 值 | 说明 |
| -------------------- | ------------ | --------- |
| SecurityType.STOCK | stock | 股票类型 |
| SecurityType.INDEX | index | 指数类型 |
| SecurityType.ETF | etf | ETF基金 |
| SecurityType.FUND | fund | 基金 |
| SecurityType.LOF | lof，LOF基金 | |
| SecurityType.FJA | fja | 分级A基金 |
| SecurityType.FJB | fjb | 分级B基金 |
| SecurityType.BOND | bond | 债券基金 |
| SecurityType.STOCK_B | stock_b | B股 |
| SecurityType.UNKNOWN | unknown | 未知品种 |
它的一个用法是，在我们查询证券列表中，有哪些股票类型的代码时：
```python
secs = await Security.select().types(SecurityType.STOCK).eval()
print(secs)
```
#### 2.1.3. MarketType
市场类型。Zillionare支持的类型为上交所`XSHG`和`XSHE`
| 类型 | 值 | 说明 |
| --------------- | ---- | ------ |
| MarketType.XSHG | XSHG | 上交所 |
| MarketType.XSHE | XSHE | 深交所 |
#### 2.1.4. bars_dtype
在zillionare中，我们一般使用 Numpy Structured Array来存储行情数据，以使用numpy的许多性能算法进行运算。同时，它也比pandas.DataFrame更省内存，在小数据集（<50万条）时，多数运算（但不是每一种运算）会有更高的性能。
要使用 Numpy Structured Array来表示行情数据，就需要定义定段列表。 [bars_dtype](api/#coretypes.types.bars_dtype)就是这样的列表，它包括了字段（frame, open, high, low, close, volume, amount, factor)。
```python
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`字段，以用于同时存取多个证券的行情的情况。
```python
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](api/#coretypes.errors.trade.base.TradeError.as_json)将其串行化后再通过网络发送，在客户端则可以通过[TraderError.from_json](api/#coretypes.errors.trade.base.TradeError.from_json)将其恢复。
为方便查错，服务器在生成TradeError时，可以传入`with_stack=True`，这样生成的TraderError(及子类)中，将包含调用栈信息（在`stack`属性中），以方便查错。
```python
def foo():
try:
raise TraderError("mock error", with_stack=True)
except TradeError as e:
print(e.stack)
```
### 2.3. QuotesFetcher
Zillionare目前只适配了聚宽的数据源，但我们通过 QuotesFetcher 让您可以自行适配其它数据源。
你需要实现定义在 [QuotesFetcher](/api/#coretypes.quote_fetcher.QuotesFetcher)中的接口，然后在omega的配置文件中，加载您的实现。
具体实现可以参考 [omega-jqadaptor](https://github.com/zillionare/omega_jqadaptor)
配置可以参见[omega-config](https://github.com/zillionare/omega/blob/master/omega/config/defaults.yaml)
```yaml
# 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](https://zillionare.github.io/python-project-wizard/)创建，并遵循ppw定义的代码风格和质量规范。