{"id":16346669,"url":"https://github.com/zillionare/core-types","last_synced_at":"2025-11-08T10:30:28.419Z","repository":{"id":54242884,"uuid":"446375092","full_name":"zillionare/core-types","owner":"zillionare","description":null,"archived":false,"fork":false,"pushed_at":"2023-11-19T02:53:22.000Z","size":1143,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-12-28T02:44:47.184Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zillionare.png","metadata":{"files":{"readme":"README.md","changelog":"HISTORY.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2022-01-10T10:23:08.000Z","updated_at":"2022-01-12T01:19:40.000Z","dependencies_parsed_at":"2023-11-19T03:26:37.743Z","dependency_job_id":null,"html_url":"https://github.com/zillionare/core-types","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zillionare%2Fcore-types","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zillionare%2Fcore-types/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zillionare%2Fcore-types/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zillionare%2Fcore-types/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zillionare","download_url":"https://codeload.github.com/zillionare/core-types/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":239550230,"owners_count":19657541,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-11T00:36:23.755Z","updated_at":"2025-11-08T10:30:28.343Z","avatar_url":"https://github.com/zillionare.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://pypi.python.org/pypi/zillionare_core_types\"\u003e\n    \u003cimg src=\"https://img.shields.io/pypi/v/zillionare_core_types.svg\"\n        alt = \"Release Status\"\u003e\n\u003c/a\u003e\n\u003ca href=\"#\"\u003e\n    \u003cimg src=\"https://github.com/zillionare/core-types/actions/workflows/release.yml/badge.svg\" alt=\"CI status\"/\u003e\n\u003c/a\u003e\n\u003c/p\u003e\n\n## 1. Usage\nTo use zillionare core types in a project\n\n```\n    from coretypes import Frame, FrameType\n```\n\n## 2. Features\n\n本模块提供了在 Zillionare 中的核心类型定义。主要有：\n\n1. 基础数据结构类的定义，比如时间帧类型 FrameType （对应于其它框架中可能使用的字符串 '1m', '1d'之类的定义）， 时间日期类型 Frame， 证券类型定义 FrameType 等。在几乎所有需要使用行情数据的地方，您都应该使用这些类型定义。\n2. 交易错误类型，比如 NocashError （现金不足以完成交易错误）等等。\n3. QuotesFetcher 接口定义。如果您要将其它数据源接入到 zillionare 中，就需要实现这个接口，按照定义返回相应的数据。一旦实现了此接口，就可以在 zillionare-omega 配置文件中配置接口，以例 omega 可以自动启用这个 adaptor 来获取数据。\n\n### 2.1. 基础数据结构定义\n\n基础数据结构定义中，共有两种类型。一种是用以静态类型检查使用的，通常 IDE，mypy 这样一些工具会利用它，以检测编码错误，或者提供自动完成。比如， BarsArray 就是这样一个类型，我们可以用它来声明一个行情函数的返回值类型。它的特点时，以目前的 Python 版本（截止到 Python3.8) 来看，类型信息无法在运行时访问到。\n\n另一类则是运行时类型，比如 FrameType 等。\n\n#### 2.1.1. FrameType\n行情数据都是按帧进行封装的，比如，每 1 分钟为一个单位，封装了高开低收、成交量等信息。这样的单位常常还有 5 分钟，15 分钟，日线等等。 FrameType 列举了在 Zillionare 中常用的帧类型。在其它软件中，您可能看到`unit`或者`peroid`、周期等说法。当然，可能 FrameType 是最精准的一个词。\n\nZillionare 提供了以下对应帧类型：\n\n| 周期      | 字符串 | 类型              | 数值 |\n| --------- | ------ | ----------------- | ---- |\n| 年线      | 1Y     | FrameType.YEAR    | 10   |\n| 季线      | 1Q     | FrameType.QUARTER | 9    |\n| 月线      | 1M     | FrameType.MONTH   | 8    |\n| 周线      | 1W     | FrameType.WEEK    | 7    |\n| 日线      | 1D     | FrameType.DAY     | 6    |\n| 60 分钟线 | 60m    | FrameType.MIN60   | 5    |\n| 30 分钟线 | 30m    | FrameType.MIN30   | 4    |\n| 15 分钟线 | 15m    | FrameType.MIN15   | 3    |\n| 5 分钟线  | 5m     | FrameType.MIN5    | 2    |\n| 分钟线    | 1m     | FrameType.MIN1    | 1    |\n\n\nFrameType还提供了 `\u003c`, `\u003c=`, `\u003e=`, `\u003e`等比较运算。\n\n#### 2.1.2. SecurityType\n常见的证券交易品种定义。\n\n| 类型                 | 值           | 说明      |\n| -------------------- | ------------ | --------- |\n| SecurityType.STOCK   | stock        | 股票类型  |\n| SecurityType.INDEX   | index        | 指数类型  |\n| SecurityType.ETF     | etf          | ETF基金   |\n| SecurityType.FUND    | fund         | 基金      |\n| SecurityType.LOF     | lof，LOF基金 |           |\n| SecurityType.FJA     | fja          | 分级A基金 |\n| SecurityType.FJB     | fjb          | 分级B基金 |\n| SecurityType.BOND    | bond         | 债券基金  |\n| SecurityType.STOCK_B | stock_b      | B股       |\n| SecurityType.UNKNOWN | unknown      | 未知品种  |\n\n它的一个用法是，在我们查询证券列表中，有哪些股票类型的代码时：\n\n```python\nsecs = await Security.select().types(SecurityType.STOCK).eval()\nprint(secs)\n```\n\n#### 2.1.3. MarketType\n\n市场类型。Zillionare支持的类型为上交所`XSHG`和`XSHE`\n\n| 类型            | 值   | 说明   |\n| --------------- | ---- | ------ |\n| MarketType.XSHG | XSHG | 上交所 |\n| MarketType.XSHE | XSHE | 深交所 |\n\n#### 2.1.4. bars_dtype\n在zillionare中，我们一般使用 Numpy Structured Array来存储行情数据，以使用numpy的许多性能算法进行运算。同时，它也比pandas.DataFrame更省内存，在小数据集（\u003c50万条）时，多数运算（但不是每一种运算）会有更高的性能。\n\n要使用 Numpy Structured Array来表示行情数据，就需要定义定段列表。 [bars_dtype](api/#coretypes.types.bars_dtype)就是这样的列表，它包括了字段（frame, open, high, low, close, volume, amount, factor)。\n\n```python\nbars_dtype = np.dtype(\n    [\n        (\"frame\", \"datetime64[s]\"),\n        (\"open\", \"f4\"),\n        (\"high\", \"f4\"),\n        (\"low\", \"f4\"),\n        (\"close\", \"f4\"),\n        (\"volume\", \"f8\"),\n        (\"amount\", \"f8\"),\n        (\"factor\", \"f4\"),\n    ]\n)\n```\n\n#### 2.1.5. bars_dtype_with_code\n\n在 `bars_dtype`基础上增加了`code`字段，以用于同时存取多个证券的行情的情况。\n\n```python\nbars_dtype_with_code = np.dtype(\n    [\n        (\"code\", \"O\"),\n        (\"frame\", \"datetime64[s]\"),\n        (\"open\", \"f4\"),\n        (\"high\", \"f4\"),\n        (\"low\", \"f4\"),\n        (\"close\", \"f4\"),\n        (\"volume\", \"f8\"),\n        (\"amount\", \"f8\"),\n        (\"factor\", \"f4\"),\n    ]\n)\n```\n\n#### 2.1.6. bars_cols、bars_with_limit_dtype, bars_with_limit_cols\n\n即定义在`bars_dtype`中的字段列表。有时候我们需要在numpy与pandas dataframe之间进行转换时，往往需要这个变量的值。\n\n`bars_with_limit_dtype`提供了带涨跌停报价的行情数据类型。\n\n`bars_with_limit_cols`提供了定义在`bars_with_limit_dtype`中的字段名列表。\n\n#### 2.1.7. BarsArray\n可用此静态类型作为行情数据（常用变量名 `bars`)的type hint，对应于`bars_dtype`。\n\n#### 2.1.8. BarsWithLimitArray\n同`BarsArray`，但带涨跌停报价，对应于`bars_with_limit_array`。\n\n#### 2.1.9. BarsPanel\n对应于`bars_dtype_with_code`的type hint类型。\n\n#### 2.1.10. xrxd_info_dtype\n除权除息信息类型\n\n#### 2.1.11. security_info_dtype\n定义了证券列表的字段\n\n### 2.2. Trade Errors\n\n在coretypes.errors.trade中，定义了交易中常常可能出现的异常类型。在TradeClient, TraderServer和Backtesting Server间常常都需要使用它。\n\n我们把Trade Errors分为客户端错误 `coretypes.errors.trade.client.*`, `coretypes.errors.trade.server.*`, `coretypes.errors.trade.entrust.*`三种类型，分别表明客户端编码、传参错误；服务器内部错误和交易类型错误。\n\n!!! Tips\n    对开发者而言，如果需要将此类异常传入到客户端，需要通过 [TraderError.as_json](api/#coretypes.errors.trade.base.TradeError.as_json)将其串行化后再通过网络发送，在客户端则可以通过[TraderError.from_json](api/#coretypes.errors.trade.base.TradeError.from_json)将其恢复。\n\n    为方便查错，服务器在生成TradeError时，可以传入`with_stack=True`，这样生成的TraderError(及子类)中，将包含调用栈信息（在`stack`属性中），以方便查错。\n\n```python\ndef foo():\n    try:\n        raise TraderError(\"mock error\", with_stack=True)\n    except TradeError as e:\n        print(e.stack)\n```\n\n### 2.3. QuotesFetcher\n\nZillionare目前只适配了聚宽的数据源，但我们通过 QuotesFetcher 让您可以自行适配其它数据源。\n\n你需要实现定义在 [QuotesFetcher](/api/#coretypes.quote_fetcher.QuotesFetcher)中的接口，然后在omega的配置文件中，加载您的实现。\n\n具体实现可以参考 [omega-jqadaptor](https://github.com/zillionare/omega_jqadaptor)\n\n配置可以参见[omega-config](https://github.com/zillionare/omega/blob/master/omega/config/defaults.yaml)\n\n```yaml\n# defaults.yaml\n\nquotes_fetchers:\n  - impl: jqadaptor    # there must be a create_instance method in this module\n    account: ${JQ_ACCOUNT}\n    password: ${JQ_PASSWORD}\n```\n\n## 3. Credits\n\n本项目使用[ppw](https://zillionare.github.io/python-project-wizard/)创建，并遵循ppw定义的代码风格和质量规范。\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzillionare%2Fcore-types","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzillionare%2Fcore-types","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzillionare%2Fcore-types/lists"}