nestedframe 0.1.0

Pandas-like toolkit for nested JSON/NDJSON: flatten, select, explode, reconstruct

nestedframe

面向嵌套 JSON/NDJSON 的 Pandas 风格数据工具。目标是让处理半结构化的事件日志、API 响应、埋点、NDJSON 文件像用 Pandas 一样顺畅：一行载入、路径选择、受控扁平化、数组爆炸、再构造成嵌套结构。

• 痛点：

  • json_normalize 很快失控，数组字段处理复杂，丢层级关系。
  • 需要在“保留原始嵌套结构”与“产生可分析的扁平表”之间来回切换。
  • 选择嵌套字段、匹配多层路径、对数组进行受控 explode 并保持父子关联很麻烦。

• 解决：

  • NestedFrame 提供 from_records、select('user.*')、explode('items')、to_nested(group_by='_root_id') 等 API。
  • 列名采用点路径表示，如 user.id、meta.country，数组 explode 时自动展开子字段为 items.id、items.qty。

安装

pip install -e .

快速上手

from nestedframe import NestedFrame

records = [
    {"user": {"id": 1, "name": "A"}, "items": [{"id": "i1", "qty": 2}, {"id": "i2", "qty": 1}], "meta": {"country": "CN"}},
    {"user": {"id": 2, "name": "B"}, "items": [{"id": "i3", "qty": 5}], "meta": {"country": "US"}}
]

nf = NestedFrame.from_records(records)
df = nf.to_pandas()

nf2 = nf.explode("items")
exploded = nf2.to_pandas()

nested = nf2.to_nested(group_by="_root_id")

主要 API

• NestedFrame.from_records(records) 载入嵌套数据
• select(patterns) 支持 fnmatch 风格的路径筛选，如 user.*、meta.country
• explode(path) 对数组字段受控爆炸，并将子字段扁平为点路径
• to_pandas() 获取扁平化 DataFrame
• to_nested(group_by=None) 将表再构造成嵌套记录；当使用过 explode 时建议按 _root_id 分组

适用场景

• 大量 NDJSON 事件日志分析
• API 响应批量整形、聚合和统计
• 埋点数据质量分析与快速探索

许可

MIT