chronaxis.runner

这是大多数应用只需要调用的执行入口。先用load_analysis_plan读取配置，再用AnalysisRunner.validate检查声明、AnalysisRunner.explain查看将用哪些信号，最后AnalysisRunner.run实际读取数据并计算。run返回的AnalysisResult可逐行读取，也可write到可复用的结果目录；用with语句保证文件和游标及时关闭。

这是模块参考。日常调用先查公开API索引；下划线对象和嵌套函数供维护者查阅。签名来自固定源码，公开类构造签名经实际Python接口核对。

相关类型

AnalysisError、AnalysisPlan、ExecutionPlan、ExtensionRegistry

对象导航

from dataclasses import replace
from .planning.plan import AnalysisPlan
from .planning.models import ExecutionPlan
from .planning.reports import validate_analysis_plan, explain_analysis_plan
from .results.errors import AnalysisError
from .results.spool import _cleanup_owner

AnalysisRunner

配置单次分析的执行器。backend可覆盖计划设置；run创建独立资源，返回需关闭的AnalysisResult。通常复用执行器，分别管理每次结果。

AnalysisRunner(backend=None, *, extensions=None)

源码：src/chronaxis/runner.py:23（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。

AnalysisRunner.__init__

选择是否覆盖计划后端，不读取任何来源或配置文件。

AnalysisRunner.__init__(backend=None, *, extensions=None)

参数

返回说明

None；初始化实例状态。

异常说明

TypeError：backend非文本且不是None，或extensions不是ExtensionRegistry且不是None。ValueError：backend文本不在auto、reference、numpy中。构造器还未接收计划；注册对象是否与计划相同，在validate/explain/run调用时检查。

本函数直接报告的具体错误：

• TypeError：AnalysisRunner backend需要auto、reference、numpy或None。
• ValueError：AnalysisRunner仅支持auto、reference与numpy后端。
• TypeError：extensions需要宿主建立的ExtensionRegistry。

源码：src/chronaxis/runner.py:30（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。

AnalysisRunner.backend

读取构造时的覆盖选择，不表示某个尚未运行计划的实际后端。

AnalysisRunner.backend

装饰器：property。

读取属性，不使用调用括号。

参数说明

无。

返回说明

None/auto/reference/numpy。

异常说明

无。

源码：src/chronaxis/runner.py:52（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。

AnalysisRunner._effective_plan

保留原声明身份，只为明确覆盖创建内部执行视图。

AnalysisRunner._effective_plan(plan, process_count=None)

参数

返回说明

原plan或仅执行选项不同的新view。

异常说明

TypeError为非计划/执行声明；不重新解析配置或复制原输入行。

本函数直接报告的具体错误：

• TypeError：AnalysisRunner需要load_analysis_plan或AnalysisPlan.from_dict构建的计划。

源码：src/chronaxis/runner.py:59（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。

AnalysisRunner.validate

报告声明是否合法及执行路径是否已接入，不提前读取数据。

AnalysisRunner.validate(plan, *, process_count=None)

参数

返回说明

同一共享ValidationReport，保留实际字段/范围未验警告。

异常说明

TypeError：plan不是AnalysisPlan或其execution不是合法执行模型。正常计划的静态问题通过ValidationReport.errors返回，执行能力看execution_ready；不读取输入，不能把空errors当作实际日志已验证。

ValueError：process_count显式覆盖不是正原生int（含bool），或Runner与计划没有共享同一个ExtensionRegistry实例。注册对象按身份比较，即使声明内容相同也不能换成另一个对象；这些错误在返回报告之前直接抛出。本方法不接收extensions参数，需在创建Runner时传入计划所用的注册对象。支持范围错误在validate/explain的校验报告中返回，run拒绝执行并抛AnalysisError。

副作用说明

无来源I/O或目录创建。

调用示例

"""共享注册实例的最小示例；仅校验并解释，不运行分析。"""
# 从手册根目录（包含 examples 子目录）运行。
# 此教学配置只使用内置算子；空注册对象用于演示同一实例的传递。
from chronaxis import AnalysisRunner, load_analysis_plan
from chronaxis.extensions import ExtensionRegistry

registry = ExtensionRegistry()
plan = load_analysis_plan("examples/calculation-minimal.yaml", extensions=registry)
runner = AnalysisRunner(extensions=registry)
validation = runner.validate(plan)
explanation = runner.explain(plan)
print(validation.valid, validation.execution_ready)
print(type(explanation).__name__)
# 预期输出：True True，随后为 ExplainReport。

源码：src/chronaxis/runner.py:80（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。

AnalysisRunner.explain

列出真实依赖、各节点后端、历史需求及声明预算，不启动分析。

AnalysisRunner.explain(plan, *, process_count=None)

参数

返回说明

ExplainReport，plan_identity保原声明身份。

异常说明

TypeError：plan不是AnalysisPlan或其execution类型不符。手工破坏带有明确类型的引用可能引发AttributeError/KeyError；重新使用from_dict/load_analysis_plan构造合法计划。函数不打开CSV/DBC，不测量实际耗时或内存。

ValueError：process_count显式覆盖不是正原生int（含bool），或Runner与计划没有共享同一个ExtensionRegistry实例。注册对象按身份比较，即使声明内容相同也不能换成另一个对象；这些错误在返回报告之前直接抛出。本方法不接收extensions参数，需在创建Runner时传入计划所用的注册对象。支持范围错误在validate/explain的校验报告中返回，run拒绝执行并抛AnalysisError。

副作用说明

不读取CSV/DBC，也不测量实耗。

源码：src/chronaxis/runner.py:91（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。

AnalysisRunner.run

验证后执行一次真实分析，输入全关才返回独立AnalysisResult。

AnalysisRunner.run(plan, work_dir=None, *, process_count=None)

参数

返回说明

analysis_complete的AnalysisResult，由调用者close/上下文管理，write另行发布。

异常说明

TypeError：plan不是AnalysisPlan，或其执行声明类型错误。ValueError：显式process_count不是正整数（含bool），或AnalysisRunner与计划未共享同一个扩展注册。

AnalysisError：计划校验未通过、无法执行，或分析运行失败。运行失败被包装时可通过异常的__cause__读取原错误；原AnalysisError及直接校验错误的__cause__可能为空。附加清理信息在__notes__中（若有）。加载配置时的PlanValidationError另有diagnostics，不能假定所有AnalysisError都有此属性。

KeyboardInterrupt和SystemExit原样传播。清理持续失败时，从捕获的异常读取getattr(exc, "runner_cleanup_owner", None)；如果存在恢复对象，排除资源故障后调用该对象.close()重试。未附此属性不表示分析成功；仍须处理原异常。

副作用说明

创建本次新暂存；扫描来源一次、后续仅回读新history，不自动删除或发布文件。

调用示例

"""从YAML配置执行分析并逐行读取结果；输入为配置路径，可选结果输出目录。"""
import argparse
from pathlib import Path

from chronaxis import AnalysisRunner, load_analysis_plan, validate_analysis_plan


def main():
    """检查配置后执行，显式关闭游标和结果。返回None；配置/执行错误保留异常链。"""
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument('plan', nargs='?', type=Path, default=Path(__file__).parent / 'analysis.yaml')
    parser.add_argument('--output', type=Path, help='可复用的正式输出目录；省略则只打印结果')
    args = parser.parse_args()
    plan = load_analysis_plan(args.plan)
    report = validate_analysis_plan(plan)
    if not report.valid or not report.execution_ready:
        raise RuntimeError(report)
    with AnalysisRunner().run(plan) as result:
        rows = result.iter_calculations()
        try:
            for row in rows:
                print(row.calculation_id, row.value, row.unit, row.status, row.reason)
        finally:
            rows.close()
        if args.output is not None:
            manifest = result.write(args.output)
            print(manifest)


if __name__ == '__main__':
    main()

源码：src/chronaxis/runner.py:103（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。