Axiolune Python SDK

用领域函数读取股票、基金、指数、债券、期货、期权、外汇与宏观数据，返回可以直接组合研究的 pandas 表格。常规数据读取不需要初始化数据目录或创建客户端。

中文使用手册 · English documentation · 完整 API 与参数

第一次读取

import axiolune as ax

matches = ax.stock.search(query="茅台", market="CN")
print(matches)

prices = ax.stock.history(
    symbols="600519.SH",
    start="2026-09-01",
    end="2026-09-30",
    adjustment="none",
)
print(prices[["symbol", "date", "close", "currency"]].head())

symbols 使用带市场后缀的代码；start、end 是包含边界的日期。adjustment="none" 表示不复权。调用会访问真实数据来源；返回值和空表取决于来源及所选范围。每列含义、单位、可选值与默认值见 stock.history。

不知道填什么时

print(ax.search("净值"))
print(ax.help("fund.history", language="zh"))
contract = ax.describe("stock.history")
print(contract["parameters"])
print(contract["output"])

发现与帮助操作不取网络数据。每个操作有独立参数页，列出必填项、格式、默认值、枚举、参数依赖、输出字段与实际留存结果。证券和指标示例不代表动态全集；先查相应目录再选值。

从表格组合研究

安装研究功能 pip install "axiolune[research]" 后，复用上一步的价格表：

close = ax.research.prices(prices, field="close")
average = ax.research.sma(close, window=5)
returns = ax.research.returns(close, periods=1)
print(average.tail())
print(returns.tail())

矩阵以日期为行、证券为列；收益率为小数比例，缺失值保持缺失。继续使用 完整组合教程、指标、模型、回测、组合风险和报告手册。研究结果取决于实际输入与明确的交易、费用和时间假设。

安装与功能选择

当前产品版本 / Product version: 0.6.0 · 待发布到 PyPI / Awaiting PyPI publication。

以下为发布后的标准索引安装方式，公共索引目前尚不能取得本版本。 These are the standard commands after publication; this version is not yet available from the public index.

pip install axiolune
uv pip install axiolune
uv add axiolune

基础安装包含常规取数、Arrow/pandas 与 Excel；Python >=3.12,<3.14。不同安装器择一使用，pip/uv pip 面向环境，uv add 面向项目。首次解析选择所用索引与 Python/平台/依赖约束允许的最新正常版本；已有环境和 uv.lock 不会自动追新。 Core installation includes routine data retrieval, Arrow/pandas and Excel. Choose one workflow: pip/uv pip manages an environment; uv add manages a project. Initial resolution chooses the latest normal release permitted by the index and environment constraints, without automatically upgrading existing environments or lockfiles.

按需组合 / Combine capabilities

pip install "axiolune[local]"
uv pip install "axiolune[research,plot,team]"
uv add "axiolune[documents,ocr]"

可同时选择多个 extras；其下层依赖自动包含。data 和 team 的依赖已含基础安装，保留兼容别名；all 仅用于需要全部可选依赖的环境。 Select multiple extras; their dependencies are included automatically. data and team retain compatibility aliases with dependencies already in the core. Choose all only when every optional dependency is needed.

升级 / Upgrade

pip install -U axiolune
uv pip install --upgrade axiolune

升级时保留所需 extras，例如 pip install -U "axiolune[research,plot]"。普通重复 install 不等于升级。uv 项目更新锁文件后再同步： Retain required extras during upgrades. An ordinary repeated install is not an upgrade request. For uv projects:

uv lock --upgrade-package axiolune
uv sync

uv.lock 保留已解析版本；升级仍遵守 pyproject.toml 的版本范围。 uv.lock retains resolved versions; upgrades remain subject to pyproject.toml constraints.

使用独立虚拟环境。Windows 用 py -3.13 -m venv .venv，Linux/macOS 用 python3.13 -m venv .venv；或统一使用 uv venv --python 3.13。不激活时用 .venv/Scripts/python -m pip（Windows）、.venv/bin/python -m pip（Linux/macOS），或 uv pip install --python .venv axiolune。uv 项目同时声明完整 Python 范围：uv init --python ">=3.12,<3.14" my-research 后 uv add axiolune。 Use an isolated environment and its own interpreter. Python 3.12 is also supported. uv projects manage their environment automatically.

可选系统依赖：Linux OCR 需要 OpenGL/GLib（Debian/Ubuntu：libgl1 libglib2.0-0）；macOS 的 ml-advanced/all 需要 brew install libomp。server 不自动部署 PostgreSQL；OCR 模型权重另行准备。Windows x64、Linux x86_64/glibc ≥ 2.28、macOS Intel ≥ 13 / Apple Silicon ≥ 14 是完整依赖目标；实际平台执行记录须分别查看，历史 a34 结果仍属于 a34。 Optional system libraries: OpenGL/GLib for Linux OCR and libomp for macOS advanced tree models. server does not provision PostgreSQL; OCR weights are separate. Historical a34 execution records remain a34 evidence.

依赖与版本唯一来源为 SDK pyproject.toml 和根 VERSION；安装/升级命令不固定版本号。需要精确复现时才显式使用 ==。 The SDK pyproject.toml and root VERSION are authoritative. Version pins are reserved for explicit reproduction.

本地输入与持久研究

需要导入文件、快照、本地 SQL 或研究声明时使用 Client；一般数据读取仍直接使用领域函数。

import axiolune as ax

with ax.Client(data_root="./research-data") as client:
    result = client.inputs.import_file("prices.csv")
    print(result.to_pandas().head())

prices.csv 是调用者已有的本地文件。快照与 SQL 使用 axiolune[local]。offline=True 禁止新网络采集；默认允许读取。客户端的全部参数、预算与生命周期见 本地客户端。团队通过 ax.team.connect(endpoint, credential) 接入已有服务。

原始来源与升级

发布者特有字段使用 ax.source.search/describe/fetch/frame。先读来源合同，再传来源参数；普通行情优先使用股票、基金等领域函数。

0.7 为不兼容重构，旧顶层 Session、fetch/frame、Ticker/download、init/data/catalog/universe/sim 入口已撤下。迁移说明列出对应的新入口。历史观测记录保留其原始日期与 SDK 版本，不当作本版本重新执行的证据。

项目与贡献

由 Moonweave AI 维护，文档与公共操作合同随 SDK 一起生成。缺陷与改进请提交到 项目仓库，提供版本、最小复现、参数和脱敏后的来源错误。不要提交凭据、个人数据或未经允许分发的数据。

包使用 Apache-2.0，见 LICENSE。数据来源权利独立于代码许可证，见 THIRD_PARTY_NOTICES.md。