chronaxis.sources.text_can_decode
按需解码新ASC/CSV原帧，并接到既有数值归一化核心。
CANTextDecodeRead消费显式CANTextSpec与本次需要的SignalDefinition，逐个交付 DecodedCANRecord；未知ID、未选中和非数据帧仍保原记录，仅所需帧调用cantools。 DBC沿用decode_choices=False/allow_truncated=True参数，但新入口先严格核已选帧长度； 已定义报文解码失败直接定位，不冒充未知ID。pack_text_records输出既有SignalSeries。 完整读取核对全部原帧时间；按需ASC仅核所需通道/ID的连续顺序，并同次统计来源范围。 文件不重读；DBC加载和临时对象先付预算。 解析文件逐个关闭，失败/取消保原错误及必要恢复owner；纯BLF串行复用显式解码政策。
这是模块参考。日常调用先查公开API索引；下划线对象和嵌套函数供维护者查阅。签名来自固定源码，公开类构造签名经实际Python接口核对。
相关类型
ASCRead、ASCSpec、BLFRead、BLFSpec、CANCSVRead、CANTextError、CANTextSourceRef、CANTextSpec、Path、RawCANRecord、ResourceBudget、ResultClosedError、SignalDefinition、_UntimedBLFRecord
对象导航
| 对象 | 用途 |
|---|---|
DecodedCANRecord |
保留一条原帧及本次所需原信号值；非decoded记录的values必须为空。 |
DecodedCANRecord.__post_init__ |
核记录冻结结构。 |
DecodedCANRecord._from_bound_values |
用本次绑定已经解析的字段名建立内部记录，其余检查与公开构造相同。 |
DecodedCANRecord._validate |
检查固定记录，内部已绑定键只核成员关系。 |
CANTextDecodeRead |
拥有单次DBC和逐文件解析器；EOF后保有限元数据到显式close。 |
CANTextDecodeRead.__init__ |
只核声明并预约固定费用。 |
CANTextDecodeRead.closed |
查看本对象负责的资源是否已经全部关闭。 |
CANTextDecodeRead.exhausted |
区别真实全文件EOF与提前close。 |
CANTextDecodeRead.metadata |
取得本次读取使用的DBC及其相关记录。 |
CANTextDecodeRead.prepare_metadata |
只初始化一次DBC，供计算在首帧前取得周期。 |
CANTextDecodeRead._start |
一次加载并核所需定位/单位。 |
CANTextDecodeRead._decode |
给本条原帧分类并按需解码。 |
CANTextDecodeRead.__iter__ |
迭代同次读取。 |
CANTextDecodeRead._time_selected |
判断此帧是否属于所需通道与ID；不解码、不改时间。 |
CANTextDecodeRead.__next__ |
逐条返回原始报文和本次请求的解码信号值。 |
CANTextDecodeRead._blf_observation |
接收BLF投影前已核的范围和顺序事实。 |
CANTextDecodeRead.close |
关闭自有解析器及DBC状态，可重试。 |
CANTextDecodeRead.__enter__ |
建立显式资源上下文。 |
CANTextDecodeRead.__exit__ |
保原业务错误并收尾。 |
pack_text_records |
把有限已解码原帧交给现有数值核心，不再次解码或重复DBC缩放。 |
导入与重导出来源（展开）
from dataclasses import dataclass
from decimal import Decimal
from hashlib import file_digest
from pathlib import Path
from ..dbc_loading import load_dbc_file
from ..core.binding import SignalDefinition
from ..core.validation import require_identifier
from ..execution.history import _metadata_bytes
from ..legacy.records import field_to_dict
from ..legacy.decode_policy import check_decode_length, decode_serial_frame
from ..legacy.worker import _field_metadata
from ..results.budget import ResourceBudget, _reserve_owned_ram, _release_owned_ram, _cleanup_owner
from ..results.errors import ResultClosedError
from .asc import ASCSpec, ASCRead
from .blf import BLFSpec, BLFRead, _UntimedBLFRecord
from .raw_csv import CANCSVRead
from .raw_can import RawCANRecord, CANTextError
from .can_spec import can_field_from_key
from .models import freeze_metadata
from .packing import pack_decoded
from .text_can_ref import CANTextSourceRef
from .text_can_spec import CANTextSpecDecodedCANRecord
保留一条原帧及本次所需原信号值；非decoded记录的values必须为空。
class DecodedCANRecord属性与数据字段
| 名称 | 数据类型 | 必填 | 省略时的值 | 用途、取值和效果 |
|---|---|---|---|---|
source |
str | 是 | 无 | 当前来源名称。 |
input_index |
int | 是 | 无 | 原输入列表位置。 |
sequence |
int | 是 | 无 | 全部文件连续的原帧序号，不仅是参与计算的序号。 |
raw |
RawCANRecord | _UntimedBLFRecord | 是 | 无 | 保留原帧；无时间需求的BLF记录明确不提供时间。 |
values |
tuple[tuple[str, int | float | bool | None], ...] | 是 | 无 | 规范CAN字段键到DBC物理值。 |
status |
str | 是 | 无 | decoded：已用DBC解码；unknown：DBC中找不到该报文；unselected：本次未选择解码该报文；non_data：远程帧或错误帧，不按普通数据帧解码。解析错误会报错，不改记为unknown。 |
frame_values |
tuple[tuple[str, int | float | bool | None], ...] | 否 | () | 显式重建所需原物理字段。 |
frame_layout |
tuple[tuple[str, int], ...] | 否 | () | 当次复用选择器的原始码值。 |
源码：src/chronaxis/sources/text_can_decode.py:39（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。
DecodedCANRecord.__post_init__
核记录冻结结构。
DecodedCANRecord.__post_init__()参数：无显式参数。
参数说明
无。
返回说明
返回None，不返回额外的计算值。
异常说明
来源、位置、状态或值结构非法。
本函数直接报告的具体错误：
ValueError：解码CAN记录结构或状态非法。ValueError：未解码原帧不能携带信号值。ValueError：未解码原帧不能伪造重建值。TypeError：解码值需要规范字段键及原生数值/None。ValueError：解码CAN字段重复。ValueError：重建物理值或布局结构非法。
源码：src/chronaxis/sources/text_can_decode.py:51（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。
DecodedCANRecord._from_bound_values
用本次绑定已经解析的字段名建立内部记录，其余检查与公开构造相同。
DecodedCANRecord._from_bound_values(source, input_index, sequence, raw, values, status, frame_values, frame_layout, known_fields)装饰器：classmethod。
参数
| 名称 | 数据类型 | 必填 | 省略时的值 | 用途、取值和效果 |
|---|---|---|---|---|
source |
str | 是 | 无 | 位置或关键字。当前记录所属的来源名称。 |
input_index |
int | 是 | 无 | 位置或关键字。原始输入文件的非负序号。 |
sequence |
int | 是 | 无 | 位置或关键字。当前来源跨文件的原始记录非负序号，用于保持记录顺序。 |
raw |
RawCANRecord | _UntimedBLFRecord | 是 | 无 | 位置或关键字。已读取的原始记录；无需时间的BLF逐消息任务可以传入内部无时间记录。 |
values |
tuple[tuple[str, int | float | bool | None], ...] | 是 | 无 | 位置或关键字。本次所需信号的规范字段键与解码值；键必须属于known_fields且不重复，未解码状态必须为空。 |
status |
str | 是 | 无 | 位置或关键字。当前记录的处理状态：decoded、unknown、unselected或non_data；非decoded状态不得携带解码值。 |
frame_values |
tuple[tuple[str, int | float | bool | None], ...] | 是 | 无 | 位置或关键字。仅在请求重建报文时保留的信号名称与物理值；不需要重建时为空。 |
frame_layout |
tuple[tuple[str, int], ...] | 是 | 无 | 位置或关键字。仅在请求重建报文时保留的多路复用信号名称与原始整数编码；不需要重建时为空。 |
known_fields |
frozenset[str] | set[str] | 是 | 无 | 位置或关键字。当前绑定或有界批次已解析过的规范字段键集合；这里只复用键解析，仍检查成员、重复键、类型及记录结构。 |
返回说明
新的冻结DecodedCANRecord，不持有额外的绑定副本。
异常说明
字段不在当前绑定中、值类型或记录结构不合法时拒绝。 外部构造仍调用完整字段解析；此入口只供同次解码结果复用绑定检查。
源码：src/chronaxis/sources/text_can_decode.py:57（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。
DecodedCANRecord._validate
检查固定记录，内部已绑定键只核成员关系。
DecodedCANRecord._validate(known_fields)参数
| 名称 | 数据类型 | 必填 | 省略时的值 | 用途、取值和效果 |
|---|---|---|---|---|
known_fields |
frozenset[str] | set[str] | None | 是 | 无 | 位置或关键字。内部读取或有界块中已解析的规范字段键；非None时复用键解析并核成员及重复键，None使公开构造完整解析每个键。 |
返回说明
None。
异常说明
非法结构、未知字段、重复键或无值状态携带数据。
源码：src/chronaxis/sources/text_can_decode.py:76（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。
CANTextDecodeRead
拥有单次DBC和逐文件解析器；EOF后保有限元数据到显式close。
CANTextDecodeRead(spec, budget, signals, *, check_cancel=None, database_context=None, classify_unselected=True, cycle_fields=(), metadata_fields=(), integrity=True, trace=True, retain_source_time=True, selected_ids=None, time_frame_ids=None, emit_frame_ids=None, blf_time_scope='source', legacy_blf_decode=False, serial_blf_policy=None, post_decode_frame_ids=None)源码：src/chronaxis/sources/text_can_decode.py:109（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。
CANTextDecodeRead.__init__
只核声明并预约固定费用。
CANTextDecodeRead.__init__(spec, budget, signals, *, check_cancel=None, database_context=None, classify_unselected=True, cycle_fields=(), metadata_fields=(), integrity=True, trace=True, retain_source_time=True, selected_ids=None, time_frame_ids=None, emit_frame_ids=None, blf_time_scope='source', legacy_blf_decode=False, serial_blf_policy=None, post_decode_frame_ids=None)参数
| 名称 | 数据类型 | 必填 | 省略时的值 | 用途、取值和效果 |
|---|---|---|---|---|
spec |
CANTextSpec | 是 | 无 | 位置或关键字。ASC或原始CSV文本CAN来源配置，包括输入格式与DBC设置。 |
budget |
ResourceBudget | 是 | 无 | 位置或关键字。当前读取共用的资源额度管理器，解码和保留数据前先预约所需资源。 |
signals |
tuple[SignalDefinition, ...] | 是 | 无 | 位置或关键字。实际需要的信号定义，根据明确字段定位选择解码后的信号。 |
check_cancel |
Callable[[], None] | None | 否 | None | 仅关键字。可选的无参取消检查函数。需要终止时由它抛出异常；None表示不额外调用取消检查。 |
database_context |
FrameDBCContext | None | 否 | None | 仅关键字。本次已加载的DBC上下文；提供时借用数据库，None按读取流程加载所需DBC。 |
classify_unselected |
bool | 否 | True | 仅关键字。是否检查未选报文的分类信息；关闭时在确认报文不相关后尽早跳过。 |
cycle_fields |
tuple[LegacyCANField, ...] | 否 | () | 仅关键字。需要读取DBC周期的字段定位集合；初始化时读取元数据，不逐帧读取DBC。 |
metadata_fields |
tuple[LegacyCANField, ...] | 否 | () | 仅关键字。仅请求驱动信号的DBC候选声明，默认空tuple；用于确认实际帧身份，不请求信号值，也不增加普通样本或值解码。 |
integrity |
bool | 否 | True | 仅关键字。是否执行本对象的额外内容摘要或认证核验；False仍保留结构、类型、预算及必要文件变化检查。 |
trace |
bool | 否 | True | 仅关键字。是否保存此功能的详细来源或输入追溯；False在生成处跳过，不能先构造再隐藏。 |
retain_source_time |
bool | 否 | True | 仅关键字。是否保留导出实际需要的源时间坐标；关闭时不额外保留源时间副本。 |
selected_ids |
tuple[int, ...] | None | 否 | None | 仅关键字。需要处理的报文ID；默认None读取全部记录。仅在不需要完整原帧和来源时间的消息分析路径使用：原始CSV先读ID，未匹配时跳过该行的时间、载荷和帧型解析；目标记录仍完整校验。ASC路径不使用此筛选。 |
time_frame_ids |
tuple[int, ...] | None | 否 | None | 仅关键字。本次需要检查时间顺序的CAN报文ID；同时限定来源的内部通道。None检查完整序列；空元组不交付帧但仍同次统计来源范围。完整检查或原帧导出不得传选择集合。 |
emit_frame_ids |
tuple[int, ...] | None | 否 | None | 仅关键字。限定实际交付的报文ID集合。None交付全部已解析帧；筛选不自动缩小任务要求的时间检查和观测范围。 |
blf_time_scope |
str | 否 | 'source' | 仅关键字。纯BLF按需时间范围：source检查并观测全部记录；selected只采目标时间；none明确不采时间，仅用于无需时间的逐消息累计。时间归并不能使用none。 |
legacy_blf_decode |
bool | 否 | False | 仅关键字。默认False；规范化纯can_blf的legacy转接设True，串行与并行均保留其长度政策和DecodeError缺值行为；其他异常按各入口政策处理。 |
serial_blf_policy |
str | None | 否 | None | 仅关键字。仅纯BLF串行使用requested或all，保留该入口的解码范围和异常政策；None采用文本/并行共用规则，不传给并行读取器。 |
post_decode_frame_ids |
tuple[int, ...] | None | 否 | None | 仅关键字。仅串行all在每帧解码和完整值检查后筛选交付ID；None全部交付，不减少解码调用，也不下推并行。 |
返回说明
未开始读取的owner。
异常说明
声明/预算错误；持续清理失败附text_can_cleanup_owner。
本函数直接报告的具体错误：
TypeError：文本CAN读取需要静态声明、预算及所需信号定义。ValueError：文本CAN别名不能重复。ValueError：文本CAN字段通道与来源声明不一致。ValueError：共用DBC上下文必须匹配当前文件和共享预算。
源码：src/chronaxis/sources/text_can_decode.py:112（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。
CANTextDecodeRead.closed
查看本对象负责的资源是否已经全部关闭。
CANTextDecodeRead.closed装饰器：property。
读取属性，不使用调用括号。
参数说明
无。
返回说明
True表示本对象的关闭已完成；False表示尚未关闭完毕。
异常说明
无。
源码：src/chronaxis/sources/text_can_decode.py:206（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。
CANTextDecodeRead.exhausted
区别真实全文件EOF与提前close。
CANTextDecodeRead.exhausted装饰器：property。
读取属性，不使用调用括号。
参数说明
无。
返回说明
True表示输入或结果已正常读完；False表示尚未正常读完。发生异常不等于正常读完。
异常说明
无。
源码：src/chronaxis/sources/text_can_decode.py:212（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。
CANTextDecodeRead.metadata
取得本次读取使用的DBC及其相关记录。
CANTextDecodeRead.metadata装饰器：property。
读取属性，不使用调用括号。
参数说明
无。
返回说明
冻结Mapping。
异常说明
未启动或已关闭时ResultClosedError。
本函数直接报告的具体错误：
ResultClosedError：文本CAN尚无可用的同次DBC元数据。
源码：src/chronaxis/sources/text_can_decode.py:218（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。
CANTextDecodeRead.prepare_metadata
只初始化一次DBC，供计算在首帧前取得周期。
CANTextDecodeRead.prepare_metadata()参数：无显式参数。
参数说明
无。
返回说明
同次冻结元数据。
异常说明
失败/关闭拒绝，启动错误交实际owner清理。 不打开原始文件，不改变EOF状态。
源码：src/chronaxis/sources/text_can_decode.py:225（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。
CANTextDecodeRead._start
一次加载并核所需定位/单位。
CANTextDecodeRead._start()参数：无显式参数。
参数说明
无。
返回说明
返回None，不返回额外的计算值。
异常说明
原DBC/I/O/预算或单位不符。
本函数直接报告的具体错误：
ValueError：加载期间DBC内容发生变化。
源码：src/chronaxis/sources/text_can_decode.py:242（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。
CANTextDecodeRead._decode
给本条原帧分类并按需解码。
CANTextDecodeRead._decode(raw)参数
| 名称 | 数据类型 | 必填 | 省略时的值 | 用途、取值和效果 |
|---|---|---|---|---|
raw |
RawCANRecord | 是 | 无 | 位置或关键字。raw为本次实际RawCANRecord。 |
返回说明
(values,status)。
异常说明
所选政策的长度检查或非DBC解码错误。文本legacy遇DecodeError停止； strict/partial及明确的纯BLF legacy转接将其记为本条无值，缺失信号不沿用前值。
源码：src/chronaxis/sources/text_can_decode.py:301（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。
CANTextDecodeRead.__iter__
迭代同次读取。
CANTextDecodeRead.__iter__()参数：无显式参数。
参数说明
无。
返回说明
返回当前对象本身。后续迭代或with语句使用的仍是同一个对象。
异常说明
无。
源码：src/chronaxis/sources/text_can_decode.py:354（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。
CANTextDecodeRead._time_selected
判断此帧是否属于所需通道与ID；不解码、不改时间。
CANTextDecodeRead._time_selected(frame)参数
| 名称 | 数据类型 | 必填 | 省略时的值 | 用途、取值和效果 |
|---|---|---|---|---|
frame |
LegacyRawFrame | 是 | 无 | 位置或关键字。已经解析的当前原帧；只读取其内部通道和报文ID，判断是否属于本次所需时间序列。 |
返回说明
bool；None选择全部帧。
异常说明
无。 纯BLF串行按ID沿用旧时间范围，其他来源同时匹配通道；同ID帧型交绑定解析器核对。
源码：src/chronaxis/sources/text_can_decode.py:359（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。
CANTextDecodeRead.__next__
逐条返回原始报文和本次请求的解码信号值。
CANTextDecodeRead.__next__()参数：无显式参数。
参数说明
无。
返回说明
DecodedCANRecord。
异常说明
EOF/定位数据错/原I/O、预算、取消。
源码：src/chronaxis/sources/text_can_decode.py:368（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。
CANTextDecodeRead._blf_observation
接收BLF投影前已核的范围和顺序事实。
CANTextDecodeRead._blf_observation()参数：无显式参数。
参数说明
无。
返回说明
None。
异常说明
无。
文件尾部只有无关帧时也更新来源结束；这些事实不能当成已消费水位。
源码：src/chronaxis/sources/text_can_decode.py:466（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。
CANTextDecodeRead.close
关闭自有解析器及DBC状态，可重试。
CANTextDecodeRead.close()参数：无显式参数。
参数说明
无。
返回说明
返回None，不返回额外的计算值。
异常说明
原关闭/预算错误。
源码：src/chronaxis/sources/text_can_decode.py:482（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。
CANTextDecodeRead.__enter__
建立显式资源上下文。
CANTextDecodeRead.__enter__()参数：无显式参数。
参数说明
无。
返回说明
返回当前对象本身。后续迭代或with语句使用的仍是同一个对象。
异常说明
无。
源码：src/chronaxis/sources/text_can_decode.py:501（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。
CANTextDecodeRead.__exit__
保原业务错误并收尾。
CANTextDecodeRead.__exit__(exception_type, error, traceback)参数
| 名称 | 数据类型 | 必填 | 省略时的值 | 用途、取值和效果 |
|---|---|---|---|---|
exception_type |
type[BaseException] | None | 是 | 无 | 位置或关键字。with代码块抛出的异常类型；正常离开时为None，由Python传入。 |
error |
BaseException | None | 是 | 无 | 位置或关键字。with代码块抛出的异常对象；正常离开时为None，由Python传入。 |
traceback |
TracebackType | None | 是 | 无 | 位置或关键字。异常发生时的调用栈；正常离开时为None，由Python传入，供异常继续传播。 |
返回说明
False。
异常说明
正常退出时的关闭错误。
源码：src/chronaxis/sources/text_can_decode.py:506（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。
pack_text_records
把有限已解码原帧交给现有数值核心，不再次解码或重复DBC缩放。
pack_text_records(definition, records, session_id, backend)参数
| 名称 | 数据类型 | 必填 | 省略时的值 | 用途、取值和效果 |
|---|---|---|---|---|
definition |
SignalDefinition | 是 | 无 | 位置或关键字。definition为SignalDefinition |
records |
tuple | 是 | 无 | 位置或关键字。records为有限DecodedCANRecord tuple |
session_id |
str | 是 | 无 | 位置或关键字。session_id会话 |
backend |
str | 是 | 无 | 位置或关键字。"reference"使用独立参考计算；"numpy"使用NumPy数组计算。须明确选择一种。 |
返回说明
SignalSeries，保精确纳秒、同一时刻原序号和CANTextSourceRef；调用方负责批次数组的长期预算。
异常说明
来源/声明/记录类型不符，或既有pack_decoded类型、数值转换错误。
本函数直接报告的具体错误：
TypeError：文本CAN归一化需要定义及有限解码记录tuple。ValueError：文本CAN记录与信号来源不一致。
源码：src/chronaxis/sources/text_can_decode.py:516（行号属于 8904c2f744951857659abd40aaa3535d57faf53c）。