chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/results/codec.py

@@ -0,0 +1,246 @@
+"""编码和严格解码当前扁平结果JSONL；内部叶子格式另用于历史和导出。
+
+公开结果只登记当前行类型和编号。内部_pack/_unpack保留整数、tuple、枚举、
+来源与非有限诊断标记；它们不提供旧结果包装或公开v1—v6读取。
+最大行字节与递归深度显式限制；调用方须先预留编码与解析临时空间。"""
+
+# 只访问登记dataclass字段，不开放表达式对象访问或反射导入。
+from dataclasses import fields
+from enum import Enum
+import json
+from math import isfinite
+from sys import getsizeof
+from ..core.models import Interval, SourceRef
+from ..core.numeric import ScalarValue
+from ..core.calculations import CalculationResult, CalculationDefinition
+from ..core.selection import SelectionRow
+from ..core.temporal import Event, TemporalRule
+from ..core.sequence import SequenceRule, SequenceResult
+from ..core.windows import Segment, WindowSpec
+from ..core.types import QualityFlag, SignalDType, Truth
+# CSV实际定位需要完整具体字段；只登记冻结协议，不打开来源或引入reader。
+from ..sources.csv_spec import CSVSourceRef
+# CAN引用只导入冻结位置模型，不加载原reader/DBC或产生额外扫描。
+from ..sources.can_spec import CANSourceRef
+from ..sources.text_can_ref import CANTextSourceRef
+from .rows import ResultRow, row_table
+from .errors import ResultFormatError
+from .summary import SummaryCalculationRow, SUMMARY_FIELDS, summary_fields, SUMMARY_MODELS
+# 行类型各有固定编号；只接受当前登记的格式，不提供旧版本解码。
+_SUMMARY_VERSIONS = {version:(model,names) for model,(_,names,version) in SUMMARY_MODELS.items()}
+_MODELS = {cls.__name__: cls for cls in (Interval, SourceRef, CSVSourceRef, CANSourceRef, CANTextSourceRef, ScalarValue, CalculationDefinition,
+           CalculationResult, SelectionRow, Event, TemporalRule, Segment, WindowSpec,
+           SequenceRule, SequenceResult)}
+_ENUMS = {cls.__name__: cls for cls in (QualityFlag, SignalDType, Truth)}
+def _pack(value, depth: int = 0):
+    """递归编码固定模型、枚举、tuple和原生标量。
+
+    参数: value为白名单树，depth为递归深度。返回: 仅JSON结构的树。
+    异常: ResultFormatError表示类型或深度不受支持。
+    """
+    # 深度限制避免异常嵌套占用无界栈；序列长度由调用侧RAM预估限制。
+    try:
+        if depth > 32:
+            raise ResultFormatError('结果行嵌套超过32层')
+        value_type = type(value)
+        # 原生叶子直接处理；无效数值仍保留诊断标签，不能变成普通JSON非有限值。
+        if value_type is float and not isfinite(value):
+            return {'diagnostic_float': 'nan' if value != value else 'inf' if value > 0 else '-inf'}
+        if value is None or value_type in (str, int, bool, float):
+            return value
+        if isinstance(value, Enum) and type(value).__name__ in _ENUMS and type(value) is _ENUMS[type(value).__name__]:
+            return {'enum': type(value).__name__, 'value': value.value}
+        if type(value).__name__ in _MODELS and type(value) is _MODELS[type(value).__name__]:
+            packed = {}
+            for field in fields(value):
+                if field.init:
+                    packed[field.name] = _pack(getattr(value, field.name), depth + 1)
+            return {'model': type(value).__name__, 'fields': packed}
+        if type(value) is tuple:
+            packed = []
+            for item in value:
+                packed.append(_pack(item, depth + 1))
+            return {'tuple': packed}
+        raise ResultFormatError(f'结果行含未注册类型{type(value).__name__}')
+    finally:
+        # 显式循环不留下comprehension迭代器；失败TB只断本层参数/新容器。
+        value = packed = items = kwargs = field = key = item = None
+        value_type = None
+
+
+def _unpack(value, depth: int = 0):
+    """只从已登记标签重建冻结对象。
+
+    参数: value为解析结构，depth为深度。返回: typed值。
+    异常: ResultFormatError/TypeError/ValueError为结构或模型校验错误。
+    """
+    # 未标记数组/对象不得绕过tuple和模型校验。
+    try:
+        if depth > 32:
+            raise ResultFormatError('结果行嵌套超过32层')
+        # JSON的1e999也会被解析为Inf，不能绕过明确诊断标签。
+        if type(value) is float and not isfinite(value):
+            raise ResultFormatError('非有限结果必须使用诊断标签')
+        if value is None or type(value) in (str, int, bool, float):
+            return value
+        if type(value) is not dict:
+            raise ResultFormatError('结果结构需要明确类型标签')
+        if set(value) == {'tuple'} and type(value['tuple']) is list:
+            items = []
+            for item in value['tuple']:
+                items.append(_unpack(item, depth + 1))
+            return tuple(items)
+        if set(value) == {'diagnostic_float'} and value['diagnostic_float'] in ('nan', 'inf', '-inf'):
+            return float(value['diagnostic_float'])
+        if set(value) == {'enum', 'value'} and value['enum'] in _ENUMS:
+            # enum原始值不能用bool冒充质量位整数。
+            expected = int if value['enum'] == 'QualityFlag' else str
+            if type(value['value']) is not expected:
+                raise ResultFormatError('枚举底层值类型错误')
+            return _ENUMS[value['enum']](value['value'])
+        if set(value) == {'model', 'fields'} and value['model'] in _MODELS and type(value['fields']) is dict:
+            cls = _MODELS[value['model']]
+            expected = {field.name for field in fields(cls) if field.init}
+            if set(value['fields']) != expected:
+                raise ResultFormatError('结果模型字段缺失或出现未知字段')
+            kwargs = {}
+            for key, item in value['fields'].items():
+                kwargs[key] = _unpack(item, depth + 1)
+            return cls(**kwargs)
+        raise ResultFormatError('未知或多余结果类型标签')
+    finally:
+        # 显式循环不留下comprehension迭代器；失败TB只断本层参数/新容器。
+        value = packed = items = kwargs = field = key = item = None
+
+
+def _unique_object(pairs):
+    """拒绝重复JSON键，避免解析时后值覆盖前值。
+
+    参数: pairs为JSON对象键值对。返回: dict。
+    异常: ResultFormatError为重复字段。
+    """
+    # 精确键检查覆盖外层版本和所有嵌套对象。
+    try:
+        result = {}
+        for key, value in pairs:
+            if key in result:
+                raise ResultFormatError(f'结果JSON重复键{key}')
+            result[key] = value
+        return result
+    finally:
+        # 显式循环不留下comprehension迭代器；失败TB只断本层参数/新容器。
+        pairs = result = key = value = None
+
+
+
+
+
+
+
+
+
+
+def _reject_constant(value):
+    """拒绝非标准JSON NaN/Infinity，诊断只能使用明确标签。
+
+    参数: value为解析器识别的常量名。返回: 无。
+    异常: ResultFormatError始终抛出。
+    """
+    raise ResultFormatError(f'结果JSON含非法数值{value}')
+
+
+def estimate_row_bytes(row: ResultRow) -> int:
+    """保守估计结果树、JSON转换与编码期间的新层RAM开销。
+
+    参数: row为冻结行。返回: 正整数bytes估算，含容器/标签和字符串转义余量。
+    异常: ResultFormatError为未登记类型或过深结构；不测量全进程RSS。
+    """
+    # 先确认根类型；递归只观察既有输入，不复制完整树。
+    row_table(row)
+    if type(row) is SummaryCalculationRow:
+        return (getsizeof(row) + sum(256 + getsizeof(getattr(row, name)) for name in SUMMARY_FIELDS))*16 + 8192
+    return _estimate(row) * 16 + 8192
+
+
+def _estimate(value, depth: int = 0) -> int:
+    """累计原生对象及字段容器成本，重复引用也保守重复计数。
+
+    参数: value为固定树，depth为深度。返回: 基础bytes估算。
+    异常: ResultFormatError为类型/深度不支持。
+    """
+    if depth > 32:
+        raise ResultFormatError('结果行嵌套超过32层')
+    value_type = type(value)
+    if value is None or value_type in (str, int, bool, float):
+        return getsizeof(value) + 64
+    # 字段键与临时dict的开销按每字段256bytes留余量。
+    if type(value) in SUMMARY_MODELS or (type(value).__name__ in _MODELS and type(value) is _MODELS[type(value).__name__]):
+        return getsizeof(value) + sum(256 + _estimate(getattr(value, field.name), depth + 1)
+                                    for field in fields(value) if field.init)
+    if type(value) is tuple:
+        return getsizeof(value) + sum(_estimate(item, depth + 1) + 32 for item in value)
+    if isinstance(value, Enum) and type(value).__name__ in _ENUMS:
+        return 512
+    raise ResultFormatError('不能估算未登记结果对象')
+
+
+def encode_row(row: ResultRow, max_bytes: int) -> bytes:
+    """生成一条确定JSONL，包含行结束符且限制字节数。
+
+    参数: row为typed行；max_bytes为正原生int。
+    返回: UTF-8 bytes，整数不经过浮点数转换。
+    异常: ResultFormatError/ValueError为类型、大小或格式错误。
+    """
+    # 限额由资源账本给出；此函数不自行声称RAM已预留。
+    try:
+        row_table(row)
+        if type(max_bytes) is not int or max_bytes <= 0:
+            raise ValueError('max_bytes需正原生int')
+        packed = {'row_schema_version': SUMMARY_MODELS[type(row)][2], 'row': summary_fields(row)}
+        payload = (json.dumps(packed, ensure_ascii=False, allow_nan=False, sort_keys=True,
+                              separators=(',', ':')) + '\n').encode('utf-8')
+        if len(payload) > max_bytes:
+            raise ResultFormatError('结果行超过max_bytes')
+        return payload
+    finally:
+        # 原异常/TB和返回值保持；只断本层临时引用，不清调用方帧。
+        packed = payload = row = None
+
+
+def decode_row(payload: bytes, max_bytes: int) -> ResultRow:
+    """从单行版本化JSONL恢复并重新校验所有模型。
+
+    参数: payload为UTF-8 bytes；max_bytes为正原生int。
+    返回: 当前登记的平坦结果行；旧版本1—6不再读取。
+    异常: ResultFormatError为解析/版本/模型错误，ValueError为限额配置错误。
+    """
+    try:
+        if type(max_bytes) is not int or max_bytes <= 0:
+            raise ValueError('max_bytes需正原生int')
+        if type(payload) is not bytes or len(payload) > max_bytes:
+            raise ResultFormatError('结果行类型或字节限额错误')
+        try:
+            # 禁止重复键、隐式非有限值和未知外层字段。
+            packed = json.loads(payload, object_pairs_hook=_unique_object, parse_constant=_reject_constant)
+            if type(packed) is not dict or set(packed) != {'row_schema_version', 'row'}:
+                raise ResultFormatError('结果行外层字段错误')
+            version = packed['row_schema_version']
+            if type(version) is int and version in _SUMMARY_VERSIONS:
+                model, names = _SUMMARY_VERSIONS[version]
+                fields_ = packed['row']
+                if (type(fields_) is not dict or set(fields_) != set(names)
+                        or type(fields_['quality']) is not int or fields_['quality'] < 0):
+                    raise ResultFormatError('结果字段集合或质量类型错误')
+                fields_['quality'] = QualityFlag(fields_['quality'])
+                if version==11:
+                    if type(fields_['parent_event_ids']) is not list:
+                        raise ResultFormatError('片段父ID需要JSON数组')
+                    fields_['parent_event_ids']=tuple(fields_['parent_event_ids'])
+                return model(**fields_)
+            raise ResultFormatError('不支持的结果行版本')
+        except (ValueError, TypeError, OverflowError, RecursionError, UnicodeError) as exc:
+            # 保留原模型报错原因，不吞异常或给出正常零。
+            raise ResultFormatError(f'结果行无法解析: {exc}') from exc
+    finally:
+        # 原异常/TB和返回值保持；只断本层临时引用，不清调用方帧。
+        packed = payload = row = fields_ = None

chronaxis/results/errors.py

@@ -0,0 +1,25 @@
+"""定义结果暂存、资源预算和发布的明确异常边界。
+
+输入是结果层失败原因，输出是供调用者捕获的异常类型；不执行I/O或清理。
+AnalysisError是分析执行和结果交付共用的失败基类，原始异常通过异常链保留。
+"""
+
+
+class AnalysisError(RuntimeError):
+    """表示分析或结果交付失败；异常本身不承诺旧输出已回滚。"""
+
+
+class BudgetExceededError(AnalysisError):
+    """表示新分析层估算RAM或累计磁盘暂存超过显式限额。"""
+
+
+class ResultClosedError(AnalysisError):
+    """表示结果已经关闭，不能再创建迭代器、读取或发布。"""
+
+
+class ResultFormatError(AnalysisError):
+    """表示暂存行版本、结构或typed事实非法；禁止静默补值。"""
+
+
+class ContributionsUnavailableError(AnalysisError):
+    """表示本次选择不生成贡献明细；应改为full重新运行，不能把缺失明细当作零条计算。"""

chronaxis/results/export_files.py

@@ -0,0 +1,216 @@
+"""用有限缓冲写新导出目录，全部文件真正关闭后才独占发布。
+
+供信号CSV及新报文导出共用：输入是已编码的有限bytes，输出为文件摘要和新目录。
+临时文件保留供排查；失败不覆盖用户目录、不删除已有数据。累计spool先预约，
+RAM按自有槽释放；关闭失败保真实句柄供重试。沿用项目已验证的Windows rename
+语义，其他平台预先拒绝。此层不读取原始日志、不解码，也不计算插值。
+"""
+
+from hashlib import sha256
+import json
+from pathlib import Path
+import platform
+from uuid import uuid4
+
+from .budget import ResourceBudget, _reserve_owned_ram, _release_owned_ram, _cleanup_owner
+from .errors import ResultClosedError, ResultFormatError
+
+
+class ExportFiles:
+    """拥有当前/挂起的有限输出文件、消费游标及可选处理owner，最多16文件。"""
+
+    def __init__(self, destination, budget, *, integrity=True):
+        """预检输出并创建独占临时目录。参数: destination新目录、budget共享账本，integrity控制摘要（旧入口默认开启）。
+
+        返回: owner。异常: 路径/平台/预算/I/O错；清理失败附export_cleanup_owner。
+        """
+        if not isinstance(destination,(str,Path)) or not isinstance(budget,ResourceBudget):
+            raise TypeError('导出需要目录路径和ResourceBudget')
+        if type(integrity) is not bool:
+            raise TypeError('integrity必须为bool')
+        self._integrity=integrity
+        self.destination = Path(destination).absolute()
+        # 检查词法及解析路径，防止通过链接写回历史项目；已有目标不复用。
+        if any(p.casefold()=='refprojects' for p in (*self.destination.parts,*self.destination.resolve().parts)):
+            raise ValueError('导出不能位于RefProjects')
+        if platform.system()!='Windows':
+            raise NotImplementedError('导出原子安装目前只验证Windows')
+        try:
+            self.destination.lstat()
+        except FileNotFoundError:
+            pass
+        else:
+            raise FileExistsError(self.destination)
+        self._budget = budget
+        self._held_cost = self._fixed_cost = self._row_cost = 0
+        self._closed = False
+        self.reader = self.worker = self.stream = self.verifier = self.temporary = None
+        self._parked = {}
+        self._name = self._hash = None
+        self._bytes = 0
+        self.files = []
+        try:
+            _reserve_owned_ram(self,131072+len(str(self.destination).encode('utf-8'))*32,'_fixed_cost')
+            self.destination.parent.mkdir(parents=True,exist_ok=True)
+            self.temporary = self.destination.parent/('.'+self.destination.name+'.'+uuid4().hex+'.incomplete')
+            self.temporary.mkdir(exist_ok=False)
+        except BaseException as error:
+            _cleanup_owner(self,error,'export_cleanup_owner','导出目录构造')
+            raise
+
+    @property
+    def closed(self):
+        """返回真实关闭状态。参数: 无。返回: bool。异常: 无。
+        """
+        return self._closed
+
+    def open_file(self, name):
+        """打开一个固定平面文件。参数: name安全文件名。返回: None。异常: 未关闭/重复/非法名/I/O错。
+        """
+        if self._closed or self.stream is not None:
+            raise ResultClosedError('导出已关闭或前一文件未关闭')
+        if (type(name) is not str or not name or len(name)>128 or Path(name).name!=name
+                or any(c in name for c in '/\\:') or name in ('.','..') or len(self.files)+len(self._parked)>=16):
+            raise ValueError('导出文件名或数量非法')
+        if name in self._parked or any(item['name']==name for item in self.files):
+            raise ValueError('导出文件重复')
+        # 多张表共用同次输入时会同时存在缓冲；每个新文件单独预约，不各自借满总预算。
+        _reserve_owned_ram(self,131072,'_fixed_cost')
+        self.stream = (self.temporary/name).open('xb',buffering=65536)
+        self._name,self._hash,self._bytes = name,sha256() if self._integrity else None,0
+
+    def select_file(self, name):
+        """切换有限输出表，不重新打开或覆盖。参数: name已开或新固定文件名。返回: None。异常: 打开/状态错。
+        """
+        if self._closed:
+            raise ResultClosedError('导出已关闭')
+        if self._name == name:
+            return
+        if self.stream is not None:
+            self._parked[self._name] = (self.stream,self._hash,self._bytes)
+            self.stream = self._name = self._hash = None
+        if name in self._parked:
+            self.stream,self._hash,self._bytes = self._parked.pop(name)
+            self._name = name
+        else:
+            self.open_file(name)
+
+    def append(self, payload):
+        """有限块实际写入并更新摘要。参数: payload最多64KiB bytes。返回: None。异常: 配额/写入/结构错。
+        """
+        if self._closed or self.stream is None:
+            raise ResultClosedError('导出文件未打开')
+        if type(payload) is not bytes or len(payload)>65536:
+            raise ResultFormatError('导出块需要至多64KiB bytes')
+        # 配额在任何写动作之前预约，短写继续；零进展不能伪装成功。
+        self._budget.reserve_spool(len(payload))
+        position = 0
+        while position < len(payload):
+            written = self.stream.write(payload[position:])
+            if type(written) is not int or not 0 < written <= len(payload)-position:
+                raise OSError('导出写入没有合法进展')
+            position += written
+        if self._hash is not None: self._hash.update(payload)
+        self._bytes += len(payload)
+
+    def close_file(self):
+        """真实关闭后登记摘要。参数: 无。返回: None。异常: 关闭失败保留句柄供重试。
+        """
+        if self.stream is None:
+            return
+        self.stream.close()
+        self.stream = None
+        self.files.append(dict(name=self._name,bytes=self._bytes,
+            **({} if self._hash is None else {'sha256':self._hash.hexdigest()})))
+        self._name = self._hash = None
+
+    def close_reader(self):
+        """关闭已接管的输入游标。参数: 无。返回: None。异常: 原关闭错误，保留游标供重试。
+        """
+        if self.reader is not None:
+            close = getattr(self.reader,'close',None)
+            if close is not None:
+                close()
+            self.reader = None
+
+    def close_files(self):
+        """关闭当前及挂起文件。参数: 无。返回: None。异常: 原关闭错误，未关的仍在owner中。
+        """
+        self.close_file()
+        while self._parked:
+            name = next(iter(self._parked))
+            self.select_file(name)
+            self.close_file()
+
+    def register_external(self,name):
+        """登记同目录内已关闭的外部writer文件。参数: name固定文件名。返回: None。异常: 名称/读取/关闭错。
+
+        外部writer已付spool，本层仅有限回读计算摘要，不再次计算磁盘费用。
+        """
+        if (self._closed or self.verifier is not None or type(name) is not str or not name or len(name)>128 or Path(name).name!=name
+                or any(c in name for c in '/\\:') or name in ('.','..')
+                or len(self.files)+len(self._parked)+(self.stream is not None)>=16
+                or name==self._name or name in self._parked or any(f['name']==name for f in self.files)):
+            raise ValueError('外部导出文件名称或状态非法')
+        # 未请求完整性诊断时，只登记外部writer已关闭文件的实际大小，不为摘要回读。
+        if not self._integrity:
+            self.files.append({'name':name,'bytes':(self.temporary/name).stat().st_size})
+            return
+        self.verifier=(self.temporary/name).open('rb')
+        digest=sha256(); size=0
+        while True:
+            chunk=self.verifier.read(65536)
+            if not chunk:
+                break
+            digest.update(chunk); size+=len(chunk)
+        self.verifier.close()
+        self.verifier=None
+        self.files.append({'name':name,'sha256':digest.hexdigest(),'bytes':size})
+
+    def finish(self, metadata):
+        """写完成清单并原子安装目录。参数: metadata有界JSON事实。返回: 已发布目录Path。
+
+        异常: 序列化/配额/关闭/竞态目标错误；失败保.incomplete目录，不冒报发布成功。
+        """
+        from ..execution.history import _metadata_bytes
+        # 输入完整消费并真实关闭、数据文件关闭后才写完成清单。
+        self.close_reader()
+        if self.worker is not None:
+            self.worker.close()
+            self.worker = None
+        if self.verifier is not None:
+            self.verifier.close()
+            self.verifier=None
+        self.close_files()
+        _reserve_owned_ram(self,65536+_metadata_bytes(metadata)*16,'_row_cost')
+        try:
+            document = dict(metadata,export_version=1,status='completed',files=tuple(self.files))
+            payload = (json.dumps(document,ensure_ascii=False,allow_nan=False,sort_keys=True)+'\n').encode('utf-8')
+            self.open_file('manifest.json')
+            # 清单受声明规模和RAM预算约束，按有限块写出，不把CSV单行上限误用为总清单上限。
+            for start in range(0,len(payload),65536):
+                self.append(payload[start:start+65536])
+            self.close_file()
+        finally:
+            _release_owned_ram(self,self._row_cost,'_row_cost')
+        # 关闭及费用释放失败时也不能安装；Windows rename拒绝竞态产生的已有目标。
+        self.close()
+        self.temporary.rename(self.destination)
+        return self.destination
+
+    def close(self):
+        """只关闭自有资源，保留诊断文件。参数: 无。返回: None。异常: 原关闭/释放错，允许重试。
+        """
+        if self._closed:
+            return
+        self.close_reader()
+        if self.worker is not None:
+            self.worker.close()
+            self.worker = None
+        if self.verifier is not None:
+            self.verifier.close()
+            self.verifier=None
+        self.close_files()
+        _release_owned_ram(self,self._row_cost,'_row_cost')
+        _release_owned_ram(self,self._fixed_cost,'_fixed_cost')
+        self._closed = True