Metadata-Version: 2.4
Name: emtl
Version: 0.3.0b2
Summary: 东方财富自动交易接口
Home-page: https://github.com/riiy/emtl
Author: Riiy
Author-email: riiyzhou@gmail.com
License: MIT
Project-URL: Documentation, https://emtl.readthedocs.io/
Project-URL: Changelog, https://emtl.readthedocs.io/page/changelog.html
Project-URL: Issue Tracker, https://github.com/riiy/emtl/issues
Keywords: autotrade,trade,东方财富,股票,交易,交易机器人
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Utilities
Requires-Python: >=3.11,<3.14
Description-Content-Type: text/x-rst
License-File: LICENSE
License-File: AUTHORS.rst
Requires-Dist: rsa==4.9
Requires-Dist: requests==2.33.1
Requires-Dist: Pillow==13.0.0
Requires-Dist: cryptography==50.0.2
Provides-Extra: ddddocr
Requires-Dist: ddddocr==1.4.11; extra == "ddddocr"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

========
项目简介
========



东方财富自动交易接口 Python 库，MIT 许可证。

**文档语言：简体中文。** API 名称、Python 代码及命令保留原始英文标识。
Read the Docs 是规范文档站点，GitHub Pages 仅为镜像。

安装与支持范围
==============

当前 ``master`` 的 OCR v1 实现支持 **Linux / CPython 3.11、3.12、3.13**
（``Requires-Python >=3.11,<3.14``）；其他平台及 PyPy 尚未验证。
默认使用冻结的微型 CNN（Pillow + Python 标准库），不会安装 ddddOCR、
NumPy、ONNX Runtime 或 OpenCV。需要旧 OCR 时仅在 Python 3.11 上
安装 ``emtl[ddddocr]`` 并设置环境变量
``EMTL_OCR_ENGINE=ddddocr``；显式选择失败不会静默回退。
OCR v1 已随 PR #32 合并，但尚未作为 ``0.3.0b2`` 发布；已发行的
``0.3.0b1`` 仍采用旧 OCR，仅支持 Python 3.11。
具体体积与性能门槛及证据参见
``docs/refactor/reports/OCR-v1-acceptance.md``。

内部 Alpha ``0.3.0a1`` 未对外发布；``0.3.0b1`` 已于
2026-11-10 发布为 Beta。下一候选 ``0.3.0b2`` 仍处于发布准备阶段，
Tag、Release 与 PyPI 上传均须单独授权。正式版 ``0.3.0`` 需 Beta
观察后的独立批准。以下命令安装已公开的稳定版本，**不会** 自动安装 Beta::

    python -m pip install emtl

如需获取开发中的源码，可从仓库安装，但源码不等于已验证的正式发布版本::

    python -m pip install https://github.com/riiy/emtl/archive/master.zip

Python 接口
===========

emtl 提供两套兼容边界不同的接口：

- **旧模块级函数**：如 ``emtl.login()`` 和 ``emtl.create_order()``。
  这些函数复用进程级 Session 和认证令牌，保留历史行为，**不保证多账户隔离**。
- **``emtl.TradingClient``**：同步、显式绑定账户的客户端，独立管理
  Session、Cookie 和 token。使用完毕须在 ``finally`` 中调用 ``close()``；
  当前不支持 ``with`` 或异步接口。

对于 ``TradingClient``，交易 POST 开始尝试后若结果无法确定，
将抛出 ``emtl.errors.TradeOutcomeUnknown``。 **不得据此自动重发订单**。
旧模块级函数不具备这项新异常契约。离线测试也不能证明真实券商已受理或成交。

命令行 ``emt`` 与 ``python -m emtl`` 当前只负责解析参数，
**不会** 实际登录、查询或提交交易。

文档
====

- `在线文档 <https://emtl.readthedocs.io/>`_
- `安装说明 <https://emtl.readthedocs.io/page/installation.html>`_
- `使用指南 <https://emtl.readthedocs.io/page/usage.html>`_
- `API 参考 <https://emtl.readthedocs.io/page/reference/emtl.html>`_
- `发布与维护 <https://emtl.readthedocs.io/page/releasing.html>`_

以上页面由 Read the Docs 提供，GitHub Pages 只是镜像。
站点由原英文项目切换为中文时，需要同步调整 Read the Docs 项目的语言设置；
本仓库不会自动修改该远端设置。

开发与测试
==========

开发及 CI 覆盖 CPython 3.11、3.12、3.13。自动测试只使用合成账户和禁网环境，
不连接真实券商，也不验证真实下单、撤单或成交结果。
SDK 不自动重试、重发或补偿订单。

在隔离测试环境中运行（完整离线验证需额外配置系统级禁网）::

    python -m pip install -r ci/requirements.txt
    tox

``tox -e docs`` 生成 HTML；在线外链检查 ``tox -e linkcheck``
独立执行，不属于离线测试。

问题反馈
========

- `GitHub Issues <https://github.com/riiy/emtl/issues>`_
- `Telegram 讨论组 <https://t.me/em_trade_lib>`_

请勿在公开讨论中提交密码、验证码、Cookie、令牌、账户标识或交易记录。
安全与交易风险报告请遵循 ``SECURITY.md`` 的私密联系说明。

变更记录（Changelog）
============================

0.3.0b2 (OCR v1 Beta 候选；尚未发布)
----------------------------------------------------------------------------------

* 将已合并的 PR #32 的冻结微型 CNN + Pillow 设为默认 OCR；
  旧 ``ddddocr==1.4.11`` 调整为仅 Python 3.11 可用的可选 extra，
  引擎选择错误不静默回退。
* 保留四位数字验证码字符串及前导零；Python 支持范围扩至
  Linux CPython 3.11、3.12、3.13，不变更旧版交易接口签名。
* 冻结模型的一次性独立准确率验收为 96/100，前导零 10/10；
  目标 CPU P95 低于 1000 ms。参见 ``docs/refactor/reports/OCR-v1-acceptance.md``。
* 20 MB 安装体积门槛仅适用于目标机器源码编译 Pillow 的部署；
  普通用户安装官方 Wheel 允许超过该值。
* 此版本尚未创建 Tag、Release 或上传 PyPI，须完成精确 SHA 的
  master CI、发行包审计、独立 Review 和单独发布审批。

0.3.0b1 (2026-11-10 已发布的 PyPI Beta)
----------------------------------------------------------------

* 2026-11-10 已完成受控 Beta 发布；当时仅覆盖 P0–P3 及
  Linux CPython 3.11，不包含后续 OCR v1 改动。
* 首轮仅验证 **Linux / CPython 3.11** （``Requires-Python >=3.11,<3.12``）；
  Windows、macOS、PyPy 和 Python 3.12+ 不在验证/支持范围内。
* 包含 P0–P3 的安全加固、兼容保留、``TradingClient`` 多账户隔离以及
  ``TradeOutcomeUnknown`` / ``BrokerHTTPError`` 异常契约。
* 固定依赖仍为 ``rsa==4.9``、``requests==2.33.1``、
  ``ddddocr==1.4.11``、``cryptography==50.0.2``；
  Requests/cryptography 已进行定向安全修复和无网络兼容性验证。
* CLI ``emt`` 及 ``python -m emtl`` 仍只解析参数，不执行交易。
  不保证真实券商协议或实际成交；遇到交易结果不确定时不得自动重发订单。
* 仅提供中文 RST + Sphinx + HTML 文档；PyPI Beta 采用显式预发布安装。
  旧版 ``0.2.6`` 不具备本轮 P0–P3 保护，不能当作默认安全回退版本。

0.3.0a1 (未发布的内部 Alpha；目标正式版 0.3.0)
------------------------------------------------------------

* 保留旧版包级函数、CLI 签名、参数、退出码及成功响应结构；
  P0 已取消 CLI 凭证回显。
* 移除 SDK 中的敏感日志和 root logger 重配置，
  使用合成替身及系统级禁网隔离自动测试和 CI。
* P2 新增独立账户 ``TradingClient``，独立管理 HTTP/认证状态，
  同一账户在单进程内串行，不同账户允许并发。
* P3 为显式客户端增加 ``emtl.errors.TradeOutcomeUnknown``
  与 ``BrokerHTTPError``。Unknown 不代表成交或拒绝，不得自动重发；
  旧模块级接口异常行为保持不变。
* 已批准的支持目标缩小为 Linux / CPython 3.11
  （``Requires-Python >=3.11,<3.12``）；
  保留 ``ddddocr==1.4.11`` 及已批准的运行时依赖固定版本。
* 增加发布产物安装验证与受人工审批保护的发布流程。
  自动化测试未验证真实券商协议或实际交易。
* 计划 PyPI Beta ``0.3.0b1``，必须另行批准上传；
  正式版 ``0.3.0`` 需 Beta 后单独决策。
  尚未承诺发布日期或生产可用性。

0.1.0 (2024-04-14)
------------------

* 首次发布至 PyPI。

0.1.1 (2024-04-16)
------------------

* 移除 Python 3.8、3.9 和 PyPy 的旧支持声明。

0.1.2 (2024-04-18)
------------------

* 新增登录、资产和持仓查询。

0.1.3 (2024-04-19)
------------------

* 更新文档主题。

0.1.5 (2024-04-24)
------------------

* 更新登录参考说明。

0.1.7 (2024-04-27)
------------------

* 新增下单接口（当时名称为 insert_order）。

0.1.8 (2024-04-30)
------------------

* 删除 macOS Actions。

0.2.0 (2024-05-21)
------------------

* 补齐当时的全部方法。

0.2.1 (2024-05-29)
------------------

* 增加向 PyPI 的自动部署功能（历史记录）。

0.2.2 (2024-07-11)
------------------

* 将 ``insert_order`` 替换为 ``create_order``。

P0 安全基线（历史记录，已纳入 0.3.0b1）
----------------------------------------------------------------------------------

* 删除敏感日志输出，不再重新配置宿主应用的 root logger。
* 用隔离的离线测试替代真实交易测试，移除 CI 账户凭证注入。
* 经明确批准，CLI 不再回显凭证，参数与退出码不变。
* 将离线测试迁移到仓库根目录的 ``tests/``；
  淘汰不安全的 ``pytest --pyargs emtl`` 测试入口。
