logo

Scalim

- -
库分发 scalim PyPI version Python versions
scalim-cli PyPI version Python versions
scalim-yaml-dsl-lsp PyPI version Python versions
文档生成器 Zensical
项目工具 uv ruff basedpyright pnpm
配套前端 Svelte Vite

简介

Scalim 是一个基于数据源加载和字段依赖关系的数据编排框架，通过统一的方式控制内存占用和资源调度，简化性能优化和开发。

对于复杂大宽表的业务报表：从多个数据源取数，按关系组合，计算派生字段，再写成 CSV 或 XLSX。源表很宽、内存又容易吃紧时，它通常更有用。

如果只是临时改一份小 CSV，pandas 往往更直接。Scalim 是在规则开始变多、报表要反复跑时才值得引入的。报表可以写成 YAML，也可以直接在 Python 里定义。

可以用 Python 编写需求

也可以用 YAML DSL 配置需求

查看 YAML 示例 
name: readme_min_yaml_report

main_source:
  source_id: orders
  loader: "myapp.loaders:load_orders"
  fields:
    order_id:
      name: 订单ID
    amount:
      name: 金额
    pay_id:
      name: 支付ID

sources:
  payments:
    loader: "myapp.loaders:load_payments"
    key: id
    params:
      ids: {$keys: {as: set}}
    fields:
      method:
        name: 支付方式
        extract: payment_method
        relation: orders_to_payments

relations:
  orders_to_payments:
    steps:
      - from: orders.pay_id
        to: payments.id

fields:
  total_amount:
    name: 总金额
    compute: "amount * 2"

outputs:
  - name: detail
    to: {file: detail_csv}
    write: {header_fields_output_by: name}
    fields: [order_id, method, total_amount]

resources:
  files:
    detail_csv:
      csv_file:
        path: ./output

把 myapp.loaders 换成你的加载函数所在模块。这份示例会在仓库里自动运行。

快速上手

# 加入到你的项目
uv add scalim

# 加入到你的环境
uv pip install scalim

# 交互式教程（需要先 clone 仓库 并且需要安装好 https://github.com/casey/just）
just notebook

运行库支持 Python 3.10 及以上版本（支持窗口与演进见 ROADMAP）。仓库中的交互式教程和文档工具同样需要 Python 3.10+。

meme

主要特性

  • 多种编写方式: 支持直接用 Python 描述计算逻辑,也支持用 YAML DSL 写配置,配套 JSON Schema 补全/校验 + scalim-cli 语义校验 + LSP/IDE 集成,写配置时更容易补全、检查和落地

  • 多种写入支持: 支持批量执行、流式输出和行式/列式 sink,方便在吞吐、内存和输出形式之间做取舍

  • 方便集成AI开发环境: 支持 agent skill 集成

  • 可视化在线工具: 有可视化在线工具做回放和排查,执行计划、事件流和 trace 都能接起来看

  • 可配置自适应并发执行: 大部分情况无需手动优化 — 运行时自动为你找到最优执行路径

    • 自动识别并发机会:基于依赖图的拓扑分析
    • Fan-out/Fan-in 编排:独立任务并行执行,依赖任务串行化
    • 资源感知调度:根据任务数量、数据量、CPU 资源动态调整
    • 快速失败回退:并发失败自动降级到串行模式

  • 生产级可观测性: 16+ 种事件类型 + 4 种预设 Observer

    • PerformanceObserver:吞吐量、延迟统计
    • MemoryOptimizationObserver:内存释放追踪
    • RelationObserver:关系查找命中率
    • ExecutionTraceObserver:完整执行链路追踪

  • 延迟计算非必要字段 当某个派生字段仅用于最终输出，且未被其他字段或数据加载环节依赖时，Scalim 会将其推迟到写出前再计算。配置中无需额外开关；有下游依赖的字段则仍按正常顺序计算。

  • 低内存模式: 内置字段剪枝、字段释放和行级释放,尽量只保留当前批次真正还要用的数据,减少上下文占用(内存占用)

性能

与 pandas / polars 惯用法（DataFrame 全量物化 + 向量化派生 + 库内写出）的同任务端到端对比，覆盖七种典型表（报表宽表 / 大宽表 csv+xlsx / 大长表 / 超多列宽表 / 链式边界 / 多源关联）：

① 行数扫参（1k → 1M · 20 派生列 · csv，折线看趋势）：

内存 耗时
峰值内存随行数变化：Scalim 保持约 30 MiB 平线 总耗时随行数变化

复现：just bench-external-probes --runs 3 · 脚本 run_probes.py · 数据 external-baseline-0.10.probes.json

② 七种典型表（倍数 = 相对 pandas 的比值，1.0× 虚线为持平，条尾含绝对值）：

内存 耗时
七种典型表的峰值内存对比 七种典型表的总耗时对比

复现：just bench-external --runs 3 · 脚本 run_ab.py · 数据 external-baseline-0.10.json · 完整表格与交互图表：外部基线对比

  • 内存（scalim 主定位）：全部形状峰值 RSS 保持 30–56 MiB 平台，与表面积无关；对照 pandas 为 1/4–1/35，对照 polars 为 1/7–1/37。polars 内存并不总是更低——csv 大导出与关联场景其峰值反高于 pandas。
  • 时间（分场景取舍）：xlsx 报表场景优于 pandas（0.61–0.65×）、约为 polars 的 1.6×；csv 大导出时间让给 pandas/polars（2–96×），换峰值内存 1/9–1/37；关联查询（本机 SQLite 真实 IO）时间 7.2×、内存 1/4。
  • adaptive ≈ seq：单数据流报表 demand 无并行机会，自适应并发不劣化也无收益；其收益场景是多任务编排。

以上数字的条件与边界（务必同读）：scalim 0.10.3 vs pandas 2.3.3 vs polars 1.42.1、Python 3.10.18、单机合成数据（关联 shape 为本机 SQLite 真实 IO）、每场景 3/5 次取 median、读回 golden 校验（108/108 通过）、薄算术派生函数；不构成通用加速、真实业务基准或跨机器 SLA。完整表格、形状明细、复现命令与数据 JSON 见 外部基线对比；扫参曲线、派生函数复杂度、慢源分片并行与 0.10 历史 Python 3.6 兼容边界（0.20 起 floor 为 3.10）的交互图表也在该页。

naive vs Scalim 内存代理图（小规模相对增量口径）的代码、数据与重跑方法
  • 测量口径：相对 RSS 增量代理（naive = 1.0）——同一台机器上一次运行前后进程 RSS 的变化，不是运行中的最高内存；不能跨机器比较绝对值，也不构成 SLA 承诺。代理图资产：memory-compare.svg · memory-compare-scenarios.svg。
  • 默认测试数据在 support/knobs.py：1,500 行、48 个字段，每批 150 行（CI 固定小 scale 保证秒级）。
  • 图表内容来自 chart_snapshot.json。仓库会确认示例能运行，但不会要求某个固定的内存比例。
  • 重跑：SCALIM_EXAMPLES_SUITES=example_readme_suite just examples，然后 just gen-readme-examples 更新图表。

更多见 参考文档。

质量保证

  • 100% 核心逻辑测试覆盖率 (CI全覆盖), 将用户演示notebooks作为集成测试辅助对拍验证主要场景
  • 100% 核心逻辑类型注解, 使用 basedpyright 进行较为严格的类型检查
  • 严格的 Ruff 检查和统一代码格式化
  • 最低支持版本 Python 3.10 在 CI matrix 中完整回归（3.10–3.14；typing-extensions>=4.4）.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for straydragon from gravatar.com straydragon

Credits

Author: straydragon

Requires

Python >=3.10

Provides Extra

excel pandas

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

scalim-0.20.1.tar.gz (594.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

scalim-0.20.1-py3-none-any.whl (785.0 kB view details)

Uploaded Python 3

File details

Details for the file scalim-0.20.1.tar.gz.

File metadata

  • Download URL: scalim-0.20.1.tar.gz
  • Upload date:
  • Size: 594.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for scalim-0.20.1.tar.gz
Algorithm Hash digest
SHA256 4d5fbbc33de05dfa9ae9fc2975d542eabdddcc24f9d4d18ec489c9d526f22970
MD5 70490a02573a267db1d13ec403f8698f
BLAKE2b-256 d58ec5cc1a6a4e3269fd18ab8c88da171e3815431f5ef43adedca5d32f440a4b

See more details on using hashes here.

File details

Details for the file scalim-0.20.1-py3-none-any.whl.

File metadata

  • Download URL: scalim-0.20.1-py3-none-any.whl
  • Upload date:
  • Size: 785.0 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: uv/0.12.10 {"installer":{"name":"uv","version":"0.12.10","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

File hashes

Hashes for scalim-0.20.1-py3-none-any.whl
Algorithm Hash digest
SHA256 0dbfe003b5e0e21b33e21b8f4fac6699219ea2e6b0d8a16000708db076dc8841
MD5 40aeca494ccc75345588eebe7b7a1be6
BLAKE2b-256 a14e6202fa411e0bc43fc76ef8cb032bd87ed25a3fb6301172882957fd7b175b

See more details on using hashes here.

Release history Release notifications | RSS feed

This release

0.20.1 This release

2 files

0.20.0

2 files

0.10.3

2 files

0.10.2

2 files

0.10.1

2 files

0.10.0

2 files

0.9.26

2 files

0.9.25

2 files

0.9.24

2 files

0.9.23

2 files

0.9.22

2 files

0.9.21

2 files

0.9.20

2 files

0.9.19

2 files

0.9.18

2 files

0.9.17

2 files

0.9.16

2 files

0.9.15

2 files

0.9.14

2 files

0.9.13

2 files

0.9.12

2 files

0.9.11

2 files

0.9.10

2 files

0.9.9

2 files

0.9.8

2 files

0.9.7

2 files

0.9.6

2 files

0.9.5

2 files

0.9.4

2 files

0.9.3

2 files

0.9.2

2 files

0.9.1

2 files

0.9.0

2 files

0.8.3

2 files

0.8.2

2 files

0.8.1

2 files

0.8.0

2 files

0.7.9

2 files

0.7.8

2 files

0.7.7

2 files

0.7.6

2 files

0.7.5

2 files

0.7.4

2 files

0.7.3

2 files

0.7.2

2 files

0.7.1

2 files

0.7.0

2 files

0.6.0

2 files

0.5.1

2 files

0.5.0

2 files

0.4.2

2 files

0.4.1

2 files

0.4.0

2 files

0.3.4

2 files

0.3.3

2 files

0.3.2

2 files

0.3.1

2 files

0.3.0

2 files

0.2.7

2 files

0.2.6

2 files

0.2.5

2 files

0.2.4

2 files

0.2.3

2 files

0.2.2

2 files

0.2.1

2 files

0.1.0

2 files

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page