Magika Python 包版本演进与迁移指南CHANGELOG 0.1.0 → 0.6.0 全解读【免费下载链接】magikaFast and accurate AI powered file content types detection项目地址: https://gitcode.com/GitHub_Trending/ma/magika本文以 python/CHANGELOG.md 为主体系统梳理 Magika Python 包从 0.1.0 首个版本到 0.6.0 发布候选线的完整演进脉络0.6.0 用 Rust 编写的 CLI 替换 Python 旧 CLI、MagikaResult类型化 API、字段弃用与重命名、以及新模型支持 200 内容类型等关键变更。读完本文你可以掌握每个版本的破坏性变更细节、CLI 选项的历史演变并结合仓库源码Magika 主类、类型定义验证这些变更在代码中的真实落地形式从而为升级或迁移现有 Magika 客户端提供完整依据。版本记录规范如何阅读这份 CHANGELOGpython/CHANGELOG.md 开头声明了它的格式约定变更格式基于 Keep a Changelog 规范并遵循语义化版本Semantic Versioning特殊规则版本号以0开头的0.x.yx位的递增应被视为一次主版本major级、可能包含破坏性变更的升级。这意味着阅读 Magika 的版本历史时0.1 → 0.2、0.2 → 0.3、0.3 → 0.4、0.4 → 0.5、0.5 → 0.6每一次x位升级都可能改变 API 或输出格式升级前必须对照 changelog 逐条核对。当前仓库中magika/__init__.py里的开发版本号为0.6.1-dev见 python/src/magika/init.py即代码库正处于 0.6.0 发布之后的迭代阶段。0.6.0 线rc1 → rc3CLI 换 Rust、API 全量类型化这是 changelog 中信息量最大的一个版本段包含一条构建修复、一条轮子wheel修复和一组核心架构变更。0.6.0-rc3 与 0.6.0-rc2安装问题修复rc32024-11-20修复了通过uv在 macOS 上安装 Magika 的问题rc22024-11-19修复 manylinux wheel 及其他小问题。这两条说明 0.6.0 发布前的最后阶段主要在处理跨平台分发的工程问题macOS 的uv安装路径、Linux manylinux 二进制轮子而功能层面的重大变化集中在 rc1。0.6.0-rc1五大核心变更逐条解析1. 命令线客户端由 Rust 重写changelog 明确写道“The package ships a new command line client written in Rust. This replaces the old client written in Python.” 仓库中这一事实有完整佐证rust/cli/ 目录实现了新的 CLIcli.go同级目录下的 cli.go 是 Go 绑定勿混淆python/README.md 也声明“Starting from magika0.6.0, the python package ships the new CLI, written in Rust”python/pyproject.toml 的构建系统配置印证了这一集成方式构建后端为maturin并通过manifest-path ../rust/cli/Cargo.toml把 Rust CLI 直接打进 Python 包bindings bin表示 Rust 侧以可执行文件形式随包分发。因此通过pip install magika装到的magika可执行命令从 0.6.0 起实际是 Rust 程序而不是 Python 脚本。2. JSON 输出结构调整changelog 指出新 CLI 的 JSON 输出与旧版略有不同score字段上移到与dl、output同级不再位于dl.score与output.score输出新增is_text预测内容类型是否为文本形态与extensions该内容类型关联的文件扩展名列表。python/README.md 中的真实示例与之一致--json输出的result.value下dl/output各含label、mime_type、group、description、extensions、is_text而score: 0.753与二者平级。源码侧同样能验证这一结构约束ContentTypeInfo 是 frozen dataclass只有label、mime_type、group、description、extensions、is_text六个字段其中的score属性content_type_info.py访问时会主动抛出 AttributeError并提示“.score.is not stored anymore in thedloroutputobjects; it is now stored inMagikaResult”——这是把 changelog 描述的破坏性变更做成了代码级护栏。3. Python API 返回MagikaResultStatusOr 风格changelog 写道API 现在返回MagikaResult一个类似absl::StatusOr的对象包装MagikaPrediction目的是把“有效预测”与“错误情况”明确分离。python/src/magika/types/magika_result.py 展示了这一设计的实现细节__post_init__强制二选一约束status OK时prediction必须存在否则prediction必须为空从结构上杜绝“有状态错误却带着预测值”的歧义prediction属性在非 OK 状态下访问会直接抛ValueError同时提供dl、output、score三个便捷转发属性magika_result.py。源码注释解释了动机绝大多数调用是 OK 路径不希望所有客户端都被迫写冗长的mr.prediction.output。错误状态的具体取值定义在 Status 枚举OK、FILE_NOT_FOUND_ERROR、PERMISSION_ERROR、UNKNOWN。4. 字段弃用ct_label→label、magic→descriptiondl.ct_label与output.ct_label弃用改用dl.label/output.label且label的类型是ContentTypeLabel一个StrEnum可直接当字符串用magic元数据弃用改用description。ContentTypeInfo 中的两个只读属性完整落实了这一点访问ct_label或magic都会触发DeprecationWarning模块顶部还特意warnings.simplefilter(always, DeprecationWarning)保证弃用警告可见并分别转发到str(self.label)与self.description。迁移时只需全局替换属性名旧代码在过渡期仍可运行但会收到警告。ContentTypeLabel是一个自动生成的StrEnumpython/src/magika/types/content_type_label.py 顶部注释标明 DO NOT EDIT --- This file is automatically generated它列出所有已知内容类型标签注释同时提醒模型实际支持的只是其中子集具体以模型配置为准。5. 元数据扩展与模型升级内容类型元数据新增is_text布尔与extensions扩展名列表——对应 ContentTypeInfo 的两个新字段未启用深度学习模型时dl.label现在取ContentTypeLabel.UNDEFINED而不是把整个dl置为None。这一改动简化了客户端的空值处理dl永远是一个合法的ContentTypeInfo是否真正走了模型只需看label是否为UNDEFINEDPython 模块全量类型化fully typedpyproject.toml的 classifiers 中包含Typing :: Typed仓库中也带有 py.typed 标记文件内置新模型支持 200 内容类型但会读取更多输入字节、速度略降。changelog 建议依赖特定结果的代码更新后对照新模型的支持列表assets/models/standard_v2_1/README.md。关于模型版本需要补充一个时间线细节changelog 写于 0.6.0-rc1 阶段当时随包模型是standard_v2_1而当前代码库中 magika.py 的DEFAULT_MODEL_NAME standard_v3_0包内 python/src/magika/models/ 目录同时携带fast_v2_1、standard_v2_1、standard_v3_0三个模型各含config.min.json与model.onnx。也就是说Magika()构造函数不传model_dir时默认加载standard_v3_0传model_dir则可按需切换到其他模型magika.py。这提示升级后识别结果的标签集合会随模型版本变化正是 changelog 提醒“update any code depending on specific results”的原因。0.5.x 线公开 API 定型与 Python 3.12 支持0.5.12024-03-06支持 Python 3.12声明支持范围3.8 且 3.13。当前仓库 pyproject.toml 的requires-python 3.8与 classifiers 列出的 3.8–3.12 与此一致注意 numpy 的版本约束已覆盖到 3.13见 pyproject.toml修复特征提取的多处边角 bug从支持内容类型列表中移除 MIME 类型涉及--list-output-content-typesFAQ 中有上下文特征提取围绕 Seekable 抽象重构只保留一份参考实现。仓库中这一抽象即 python/src/magika/seekable.py它提供Buffer/File两种可 seek 源——python/README.md 解释过其收益identify_path/identify_paths通过seek()在大文件中定位并抽取特征不必把整个文件载入内存为特征提取 v2 打下基础其余为清理与内部重构。0.5.02024-02-15这一版完成了 Python API 的定型三个新的公开 APIidentify_paths、identify_path、identify_bytes。它们在 Magika 类 中均有严格类型检查非Path或bytes输入直接抛TypeErrorAPI 返回值统一为MagikaResult模型预测置信度低、返回泛化内容类型时仍会附带免责声明打印模型的最佳猜测unknown 的描述文案更新为 Unknown binary dataCLI 默认切换为 high-confidence 模式原 default 模式改称 medium-confidence。当前代码中 PredictionMode 枚举 的三个取值BEST_GUESS/MEDIUM_CONFIDENCE/HIGH_CONFIDENCE正是这次重命名后的形态且Magika.__init__的默认参数就是PredictionMode.HIGH_CONFIDENCEmagika.py-p/--output-probability更名为-s/--output-score以保持一致性默认模型更名为standard_v1并完成大重构。0.4.0CLI 能力大幅扩展0.4.12024-02-07只是“各种改进与清理”真正的变化在 0.4.02023-12-22它奠定了 Magika CLI 今日的交互形态更新模型至 dense_v4_top_20230910且包内直接携带模型此前需要另行下载支持 stdincat path | magika -或curl url | magika --表示从标准输入读取只能使用一次。python/README.md 保留了示例cat doc.ini | magika -padding 策略从 0 改为 256提升了精度输出标签symlink更名为symlinktext以更贴合其本质新增--prediction-mode选项指定预测所需置信度支持三档best-guess、default、high-confidence0.5.0 后default更名为medium-confidence见上文目录与符号链接支持与file命令对齐-r/--recursive随之适配新增小文件特殊处理权限问题不再导致崩溃改为返回permission_error——对应 Status 枚举 中的PERMISSION_ERROR取值不再解析resolve文件路径相对路径保持相对新增--no-dereference默认情况下符号链接会被解引用读取其指向的内容加此选项后按file的行为直接识别链接本身。0.3.x输出形态与元数据体系0.3.02023-08-23默认改为人类可读输出新增-l/--label输出稳定的内容类型标签JSON/JSONL 输出包含给定内容类型的全部元数据为每种内容类型补充 magic 与 description 元数据日志改写到 stderr而非 stdout保证管道场景下 stdout 只含结果新增--generate-report输出可用于调试与反馈的 JSON 报告Python 版本要求放宽为^3.8此前为^3.8,3.11找不到任何可扫描文件时给出描述性错误而不是静默退出。0.3.12023-08-23移除使用 MIME 类型与兼容模式compatibility mode时的警告。0.2.x置信度阈值与输出格式0.2.02023-08-09新增能力输入文件改为分多个小批次处理而不是一个大批次按内容类型的阈值基于召回率 0.005 分位点计算。这一机制在当前代码中依然存在magika.py 从模型配置config[thresholds]加载逐类型阈值判定逻辑magika.py会依据BEST_GUESS/HIGH_CONFIDENCE/MEDIUM_CONFIDENCE三档分别采用最高概率直接放行、逐类型阈值、或统一medium_confidence_threshold三种策略所有内容类型的 MIME 类型与group元数据兼容模式基础支持-c/--compatibility-mode开启--no-colors关闭彩色输出-b/--batch-size指定批大小--guess/--output-highest-probability无视分数输出概率最高的类型--version打印版本。同时改变的行为输出采用group::content type格式概率分数默认不显示需-p开启按内容类型所在 group 对输出着色移除 richlogger 依赖换成更简单的 logger当前对应 python/src/magika/logger.py。0.2.1 与 0.2.22023-08-10 / 08-110.2.1若干小 bug 修复0.2.2预测分数高于 0.95 时直接采信不再受逐类型阈值限制输出格式回退为单纯的content type仅在显示元数据时才带 group更新部分内容类型的元数据。0.1.0首个发布0.1.02023-07-28是 Magika Python 包的首个发布版本changelog 仅一条记录“First release.” 后续所有版本均以此为基线演进。升级迁移清单从 changelog 到代码的对照综合各版本条目迁移 Magika 客户端时可按下面清单核对每项均能在当前仓库找到落地证据变更引入版本迁移动作仓库佐证CLI 由 Rust 实现0.6.0无需改调用方式注意 JSON 输出结构rust/cli/、pyproject.tomlscore上移至顶层0.6.0改为读取result.value.score或MagikaResult.scoremagika_result.pyAPI 返回MagikaResult0.6.00.5.0 已引入用res.ok/res.status判断后再取res.predictionmagika_result.pyct_label→label0.6.0全局替换属性名旧写法触发 DeprecationWarningcontent_type_info.pymagic→description0.6.0同上content_type_info.py新增is_text、extensions0.6.0可按需使用新字段content_type_info.py未用模型时dl.label UNDEFINED0.6.0用label判空值而非判断dl is Nonetypes 包模型升级200 类型0.6.0回归测试依赖特定标签的代码注意当前默认模型已演进至standard_v3_0magika.py三档预测模式命名0.5.0default→medium-confidencePython 侧为PredictionMode.MEDIUM_CONFIDENCEprediction_mode.py-p→-s0.5.0更新脚本中的 CLI 参数python/README.md权限错误返回permission_error0.4.0捕获Status.PERMISSION_ERROR而非异常status.py小结python/CHANGELOG.md 记录了一条清晰的演进路线0.2.x 建立置信度阈值与输出格式体系0.3.x 完善元数据与可调试性0.4.0 让 CLI 能力对标file命令stdin、符号链接、权限容错0.5.x 定型 Python 公开 API 与三档预测模式0.6.0 则以 Rust CLI、StatusOr 风格类型化 API 和 200 类型的新模型完成架构换代。结合 python/README.md、python/src/magika/magika.py 与 python/src/magika/types/ 中的当前实现可以确认上述变更均已真实落地对于仍在使用 0.5.x 及更早版本 API 的代码建议按上文迁移清单逐项对照重点关注MagikaResult的 OK/错误二分模型与label/description字段重命名这两类破坏性变更。【免费下载链接】magikaFast and accurate AI powered file content types detection项目地址: https://gitcode.com/GitHub_Trending/ma/magika创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考