Metadata-Version: 2.4
Name: pipeline-frame
Version: 0.0.1
Summary: A middleware framework for building data processing pipelines
Author-email: alan <al6nlee@gmail.com>
Project-URL: Homepage, https://github.com/al6nlee/pipeline-frame
Project-URL: Bug Reports, https://github.com/al6nlee/pipeline-frame/issues
Project-URL: Source, https://github.com/al6nlee/pipeline-frame
Keywords: middleware,pipeline,execution,processor
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# Pipeline Frame

一个用于构建 middleware-style processing pipeline 的轻量 Python 框架。
每个 `Processor` 分别处理进入和返回阶段的数据，从而形成 U-shaped
执行路径：

```text
input:  Processor A -> Processor B -> Processor C
output: Processor A <- Processor B <- Processor C
```

适用于 request/response middleware、数据校验与转换链、ETL 和 event
processing 等场景。应用启动入口创建一个 application-scoped `Engine`，
由它注册 processor 并构建可复用的 `Workflow`；每次调用 workflow 时，
再创建一个 one-shot `Execution`。

## 快速开始 / Quick Start

安装方式以及完整的 sync/async 示例，请参阅
[Quick Start](./docs/quick-start.md)。

## 架构概览 / Architecture

运行时分为两层：application-scoped `Engine` 注册并构建 frozen
`Workflow`；每次调用 workflow 时创建 one-shot `Execution`，由它拥有本次
调用的 processor instances、`ExecutionContext`、`ExecutionState` 和
`ExecutionResult`。完整的 ownership、生命周期、执行顺序和失败契约请参阅
[Architecture](./docs/architecture.md)。

## 项目结构 / Package Layout

```text
pipeline_frame/
├── __init__.py
├── execution.py
├── execution_context.py
├── execution_result.py
├── execution_state.py
├── engine.py
├── processor.py
├── workflow.py
└── observability/
    ├── __init__.py
    ├── logger.py
    └── timer.py
```

## 开发 / Development

在项目根目录运行测试：

```bash
python3 -m unittest discover -s tests -v
```

使用标准 Python build frontend 构建 distribution：

```bash
python3 -m pip install build
python3 -m build
```

## 发布 / Release

向 `main` push 包含 `pyproject.toml` 中 `project.version` 变更的提交，
即视为发布新版本。CI 会在同一次 workflow 中创建 annotated
`v<version>` tag、构建 distribution 并发布到 PyPI。也支持手动 push
`v*` tag。

如果之前的 release 已创建 tag，但在发布到 PyPI 前失败，后续 `main`
push 会在 PyPI 仍缺少对应版本时复用该 tag，无需再次修改 version。

version 可以写成 `0.2.0` 或 `v0.2.0`，CI 会统一生成 `v0.2.0` tag。
在 `pyproject.toml` 中省略 `v` 是更常规的写法。

启用自动发布前，需要在 GitHub 仓库设置中为 Actions 开启
**Read and write permissions**，并为该 workflow 配置 PyPI Trusted
Publishing。每次发布必须使用新版本，PyPI 不允许覆盖已有版本。

## 项目链接 / Project Links

- [Source repository](https://github.com/al6nlee/pipeline-frame)
- [Issue tracker](https://github.com/al6nlee/pipeline-frame/issues)

## License

MIT
