Metadata-Version: 2.4
Name: emtl
Version: 0.3.0b1
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 :: Implementation :: CPython
Classifier: Topic :: Utilities
Requires-Python: >=3.11,<3.12
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: ddddocr==1.4.11
Requires-Dist: cryptography==50.0.2
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: requires-dist
Dynamic: requires-python
Dynamic: summary

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



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

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

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

计划中的下一个正式版本 ``0.3.0`` 仅以 **Linux / CPython 3.11**
为验证和支持目标（``Requires-Python >=3.11,<3.12``）。
Windows、macOS、PyPy 及 Python 3.12+ 尚未验证。
当前固定 ``ddddocr==1.4.11``；升级 OCR 需要另行批准的脱敏图像回归测试。

内部 Alpha ``0.3.0a1`` 未对外发布；当前准备的 Beta 候选为
``0.3.0b1``，**尚未获准上传 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 项目的语言设置；
本仓库不会自动修改该远端设置。

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

开发使用 CPython 3.11。自动测试只使用合成账户和禁网环境，
不连接真实券商，也不验证真实下单、撤单或成交结果。
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.0b1 (准备中的 PyPI Beta；尚未发布)
----------------------------------------------------------------

* 候选状态：准备受控 Beta；只有完成独立 Review、最终 master CI、产物审计
  和明确的上传授权后，才能公开发布；尚无发布日期。
* 首轮仅验证 **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 安全基线（未发布）
------------------------------------

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