staged-pipeline 0.1.0a1__tar.gz

staged_pipeline-0.1.0a1/.editorconfig

@@ -0,0 +1,18 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{yml,yaml,toml,json}]
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

staged_pipeline-0.1.0a1/.env.example

@@ -0,0 +1,9 @@
+# Шаблон окружения. Скопировать в .env (в .gitignore) и заполнить.
+# Используется scripts/github_bootstrap.py (poe github), см. PLAN.md T7.1.
+
+# Fine-grained PAT на один репозиторий: Administration RW, Contents RW,
+# Workflows RW, Environments RW, Metadata R.
+GH_TOKEN=
+GITHUB_OWNER=0cherednoq
+GITHUB_REPO=staged-pipeline
+GITHUB_VISIBILITY=public

staged_pipeline-0.1.0a1/.gitattributes

@@ -0,0 +1,6 @@
+* text=auto eol=lf
+
+*.png binary
+*.jpg binary
+*.gif binary
+*.ico binary

staged_pipeline-0.1.0a1/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+  - package-ecosystem: uv
+    directory: "/"
+    schedule:
+      interval: weekly

staged_pipeline-0.1.0a1/.github/workflows/check.yml

@@ -0,0 +1,59 @@
+name: check
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_call:
+
+# UTF-8 вывод на всех ОС: инструменты (import-linter, pytest) печатают русский
+# текст, а Windows-консоль по умолчанию не UTF-8 → UnicodeEncodeError.
+env:
+  PYTHONUTF8: "1"
+
+concurrency:
+  group: check-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.13"
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run poe check
+      - run: uv run poe deps
+      - run: uv run poe spell
+      - name: pre-commit (локальные хуки уже покрыты poe check)
+        run: uv run pre-commit run --all-files --show-diff-on-failure
+        env:
+          SKIP: ruff-format,ruff-check,mypy,import-linter,pytest
+
+  py314:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.14"
+          enable-cache: true
+      - run: uv sync --locked
+      - run: uv run poe test
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - run: uv run --with twine twine check --strict dist/*
+      - name: smoke-импорт колеса в чистом окружении
+        run: uv run --isolated --no-project --find-links dist --with staged-pipeline python -c "import staged_pipeline; print(staged_pipeline.__version__)"

staged_pipeline-0.1.0a1/.github/workflows/release.yml

@@ -0,0 +1,83 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+env:
+  PYTHONUTF8: "1"
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  check:
+    uses: ./.github/workflows/check.yml
+
+  build:
+    needs: check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv build
+      - name: тег совпадает с версией
+        run: |
+          tag="${GITHUB_REF_NAME#v}"
+          ver=$(uv run --no-sync python -c "import tomllib, pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text('utf-8'))['project']['version'])")
+          if [ "$tag" != "$ver" ]; then
+            echo "тег '$tag' не совпадает с версией в pyproject '$ver'"
+            exit 1
+          fi
+      - run: uv run --with twine twine check --strict dist/*
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  smoke:
+    needs: build
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        py: ["3.13", "3.14"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: ${{ matrix.py }}
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - run: uv run --isolated --no-project --find-links dist --with staged-pipeline python -c "import staged_pipeline; print(staged_pipeline.__version__)"
+
+  publish:
+    needs: smoke
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist
+      - name: GitHub Release
+        run: gh release create "$GITHUB_REF_NAME" dist/* --generate-notes
+        env:
+          GH_TOKEN: ${{ github.token }}

staged_pipeline-0.1.0a1/.gitignore

@@ -0,0 +1,29 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info/
+.eggs/
+
+# Virtual environments
+.venv/
+
+# Тестирование и покрытие
+.pytest_cache/
+.hypothesis/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.basedpyright/
+
+# Секреты
+.env
+
+# IDE
+.idea/
+.vscode/

staged_pipeline-0.1.0a1/.pre-commit-config.yaml

@@ -0,0 +1,76 @@
+# Хуки pre-commit. На CI (T6.1) локальные хуки пропускаются (SKIP), т.к. их
+# запускает уже `uv run poe check`. Локально оффлайн первый запуск недоступен:
+# pre-commit клонирует репозитории хуков с GitHub (D-009) — это делается на CI.
+minimum_pre_commit_version: "4.0.0"
+default_install_hook_types: [pre-commit, pre-push]
+
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-merge-conflict
+      - id: check-toml
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: mixed-line-ending
+        args: [--fix=lf]
+      - id: trailing-whitespace
+
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.10.12
+    hooks:
+      - id: uv-lock
+
+  - repo: https://github.com/codespell-project/codespell
+    rev: v2.4.3
+    hooks:
+      - id: codespell
+        additional_dependencies: [tomli]
+
+  - repo: https://github.com/python-jsonschema/check-jsonschema
+    rev: 0.38.2
+    hooks:
+      - id: check-github-workflows
+
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: v0.27
+    hooks:
+      - id: validate-pyproject
+
+  # Локальные хуки через uv run --frozen (на CI пропускаются через SKIP).
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff format
+        entry: uv run --frozen ruff format --check
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+      - id: ruff-check
+        name: ruff check
+        entry: uv run --frozen ruff check
+        language: system
+        types_or: [python, pyi]
+        require_serial: true
+      - id: mypy
+        name: mypy
+        entry: uv run --frozen mypy
+        language: system
+        types_or: [python, pyi]
+        pass_filenames: false
+        require_serial: true
+      - id: import-linter
+        name: import-linter
+        entry: uv run --frozen lint-imports
+        language: system
+        pass_filenames: false
+        require_serial: true
+      - id: pytest
+        name: pytest
+        entry: uv run --frozen pytest
+        language: system
+        pass_filenames: false
+        require_serial: true
+        stages: [pre-push]

staged_pipeline-0.1.0a1/.python-version

@@ -0,0 +1 @@
+3.13

staged_pipeline-0.1.0a1/AGENTS.md

@@ -0,0 +1,35 @@
+# Правила разработки staged-pipeline
+
+Полный процесс — [docs/plan/PLAN.md](docs/plan/PLAN.md). Ниже — то, что нельзя нарушать (§0.3).
+
+## Железные правила
+
+- **Не ослаблять** линтеры, типизацию, покрытие (≥ 90%). Подавление — точечное и с причиной:
+  `# ruff: ignore[rule]  # причина`, `# pyright: ignore[rule]  # причина`.
+- Запрещены (banned-api): `typing.Any`, `asyncio.get_event_loop`, `logging.basicConfig`,
+  `unittest.mock.patch`.
+- **Ядро без зависимостей:** `dependencies = []`. Extras не импортируют внешних пакетов
+  (интеграция tallyho — через `Protocol`, architecture.md §9.3).
+- Все исключения библиотеки — подклассы `StagedPipelineError`, кроме исходов `Skip`/`Error`
+  (они — `Outcome(Exception)`, архитектурно отдельны). Все модули объявляют `__all__`.
+- Комментарии и docstring — на русском, идентификаторы — на английском. Google-style docstring.
+- Решения architecture.md не менять молча: сначала запись в
+  [docs/plan/DECISIONS.md](docs/plan/DECISIONS.md), потом код.
+- Файлы, которые пишет Python, — с `newline="\n"`.
+
+## Время и тесты
+
+- Время — только через `Clock`; в тестах `FakeClock`. Реальные `asyncio.sleep` ≤ 10 мс и только там,
+  где проверяется сам event loop.
+- Весь набор тестов < 30 с, `pytest-timeout = 5` на тест. Нет Docker, нагрузочных и хаос-тестов.
+
+## Гейты (Definition of Done)
+
+- `uv run poe check` — формат, линт, типы, import-linter, deptry, codespell, pytest + покрытие.
+- `uv run pre-commit run --all-files`.
+- DoD конкретной карточки задачи в PLAN.md.
+
+## Коммиты
+
+- Маленькие, одно логическое изменение. Сообщение на русском, заголовок `T<id>: <что>` ≤ 72 символов.
+- Ветка работы — `impl/v1`; коммиты в `main` запрещены pre-commit-хуком.

staged_pipeline-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+Все заметные изменения этого проекта документируются здесь.
+
+Формат основан на [Keep a Changelog](https://keepachangelog.com/ru/1.1.0/),
+проект придерживается [семантического версионирования](https://semver.org/lang/ru/).
+
+## [Unreleased]
+
+## [0.1.0a1] - 2026-10-25
+
+Первый альфа-релиз. Полный API v0.1 (architecture.md §4).
+
+### Added
+
+- Ядро конвейера: `Pipeline`/`Stage`, пул воркеров на стадию, супервизор (fail-fast,
+  плоское исключение), вывод режима завершения из графа (DAG по писателям, цикл по quiescence).
+- Политики исходов: `retry=` с backoff (`Expo`/`Fixed`), `skip_on`/`error_on`, `Skip`/`Error`,
+  предохранители `ErrorRate`/`NoSuccess`.
+- Дедупликация (`key=`, `SeenStore`), `seed`/`resume`/`seed_open` (`Feeder`).
+- Маршрутизация по типу выхода, `executor="thread"`, лимиты (`Limit`: concurrency + rate).
+- Остановка: `cancel`/`drain`/таймаут.
+- Прогресс: `view`/`watch`/`PipelineReport`, EWMA rate/latency, `expected`/`eta`, `Observer`.
+- `staged_pipeline.testing` (`run_stage`, `FakeClock`), интеграция `integrations.tallyho`.
+- CI (check/release), документация (README, docs/guide.md, docs/architecture.md).
+
+### Known limitations (alpha)
+
+- Открытые пункты аудита (docs/AUDIT.md): V1 (гонка `ctx.incr` из sync-хендлера), V3, V5–V12.
+- API может меняться до 1.0.
+
+[Unreleased]: https://github.com/0cherednoq/staged-pipeline/compare/v0.1.0a1...HEAD
+[0.1.0a1]: https://github.com/0cherednoq/staged-pipeline/releases/tag/v0.1.0a1

staged_pipeline-0.1.0a1/CLAUDE.md

@@ -0,0 +1,2 @@
+Правила разработки этого репозитория — в [AGENTS.md](AGENTS.md). Процесс и задачи —
+[docs/plan/PLAN.md](docs/plan/PLAN.md).

staged_pipeline-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 0cherednoq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

staged_pipeline-0.1.0a1/PKG-INFO

@@ -0,0 +1,123 @@
+Metadata-Version: 2.5
+Name: staged-pipeline
+Version: 0.1.0a1
+Summary: Декларативный конвейер стадий поверх asyncio: воркеры, dedup, ретраи, прогресс
+Project-URL: Homepage, https://github.com/0cherednoq/staged-pipeline
+Project-URL: Repository, https://github.com/0cherednoq/staged-pipeline
+Project-URL: Issues, https://github.com/0cherednoq/staged-pipeline/issues
+Project-URL: Changelog, https://github.com/0cherednoq/staged-pipeline/blob/main/CHANGELOG.md
+Author: 0cherednoq
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,dataflow,pipeline,seda
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Provides-Extra: tallyho
+Description-Content-Type: text/markdown
+
+# staged-pipeline
+
+> **Статус: pre-release (0.1.0a).** API описан в [docs/architecture.md](docs/architecture.md),
+> реализация — по [docs/plan/PLAN.md](docs/plan/PLAN.md). До релиза `0.1.0` возможны изменения.
+
+Декларативный конвейер стадий поверх `asyncio` внутри одного процесса: пул воркеров на стадию,
+дедупликация, ретраи с backoff, предохранители, лимиты и живой прогресс. Режим завершения выводится
+из графа (DAG закрывается по писателям, цикл — по quiescence), поэтому «выбрать неправильный режим и
+повиснуть» нельзя.
+
+## Чем это является
+
+- слой внутри одного процесса и одного event loop: стадии с воркерами, маршрутизацией по типу,
+  политиками исходов (`retry`/`skip_on`/`error_on`), лимитами и дедупликацией;
+- источник честного прогресса: `found / queued / in_flight / deferred / ok / skip / error /
+  cancelled / duplicates`, `expected` и `eta`;
+- одноразовый граф, проверяемый до старта (ошибка топологии не запускает ничего).
+
+## Чем это не является
+
+- не durable и не распределённая система — всё в одном процессе;
+- не владеет хранилищем: устойчивость между прогонами даёт БД домена (resume засевом);
+- не замена очереди задач (Tallyho и подобных) — это слой внутри одного Item.
+
+## Установка
+
+```bash
+uv add staged-pipeline            # ядро, без зависимостей
+uv add "staged-pipeline[tallyho]" # + маркер интеграции с Tallyho
+```
+
+Требуется Python 3.13+.
+
+## Quickstart
+
+```python
+import asyncio
+from staged_pipeline import Pipeline
+
+
+async def scan(folder: str):          # async-генератор: потоковый fan-out
+    for i in range(3):
+        yield f"{folder}/{i}"
+
+
+async def resolve(path: str) -> list[str]:   # атомарный fan-out
+    return [f"{path}.a", f"{path}.b"]
+
+
+async def download(url: str) -> None:        # терминальная стадия
+    ...
+
+
+async def main() -> None:
+    pipe = Pipeline("export")
+    listing = pipe.stage("list", scan, workers=2)
+    resolving = pipe.stage("resolve", resolve, workers=8, key=lambda p: p)
+    media = pipe.stage("media", download, workers=4, key=lambda u: u)
+
+    listing.to(resolving)
+    resolving.to(media)
+    listing.seed(["inbox"])
+
+    report = await pipe.run()
+    print(report.stages["media"].ok)
+
+
+asyncio.run(main())
+```
+
+Больше примеров — в [examples/](examples/): `crawler.py` (цикл/самопетля) и `export.py`
+(fan-out + dedup + resume). Оба исполняются в тестах.
+
+## Когда этапы Tallyho, а когда пайплайн
+
+| Критерий | Этапы Tallyho (`sub_batch` + `fed_by`) | Пайплайн внутри Item |
+|---|---|---|
+| Элемент должен пережить падение воркера сам по себе | ✔ | ✘ (resume — через БД домена) |
+| Элементы дешёвые (≪ 100 мс) и их 10⁴–10⁶ на единицу | дорого: строка + коммит на элемент | ✔ |
+| Общая сессия/лиз/соединение на единицу | ✘ (лиз на задачу) | ✔ |
+| Масштаб на несколько машин | ✔ | ✘ |
+| Нужен точный итог по каждому элементу в БД | ✔ | домен пишет сам |
+
+Мост прогресса и остановки к Tallyho — `staged_pipeline.integrations.tallyho` (`track`,
+`outcome_for`), без зависимости от `tallyho`. Подробности — [architecture.md §9](docs/architecture.md).
+
+## Документация
+
+- [Руководство по задачам (юз-кейсы с примерами)](docs/guide.md)
+- [Архитектура и API](docs/architecture.md)
+- [Prior art / ресёрч](docs/research.md)
+- [План реализации](docs/plan/PLAN.md) · [прогресс](docs/plan/PROGRESS.md) ·
+  [решения](docs/plan/DECISIONS.md)
+
+## Лицензия
+
+[MIT](LICENSE).

staged_pipeline-0.1.0a1/README.md

@@ -0,0 +1,97 @@
+# staged-pipeline
+
+> **Статус: pre-release (0.1.0a).** API описан в [docs/architecture.md](docs/architecture.md),
+> реализация — по [docs/plan/PLAN.md](docs/plan/PLAN.md). До релиза `0.1.0` возможны изменения.
+
+Декларативный конвейер стадий поверх `asyncio` внутри одного процесса: пул воркеров на стадию,
+дедупликация, ретраи с backoff, предохранители, лимиты и живой прогресс. Режим завершения выводится
+из графа (DAG закрывается по писателям, цикл — по quiescence), поэтому «выбрать неправильный режим и
+повиснуть» нельзя.
+
+## Чем это является
+
+- слой внутри одного процесса и одного event loop: стадии с воркерами, маршрутизацией по типу,
+  политиками исходов (`retry`/`skip_on`/`error_on`), лимитами и дедупликацией;
+- источник честного прогресса: `found / queued / in_flight / deferred / ok / skip / error /
+  cancelled / duplicates`, `expected` и `eta`;
+- одноразовый граф, проверяемый до старта (ошибка топологии не запускает ничего).
+
+## Чем это не является
+
+- не durable и не распределённая система — всё в одном процессе;
+- не владеет хранилищем: устойчивость между прогонами даёт БД домена (resume засевом);
+- не замена очереди задач (Tallyho и подобных) — это слой внутри одного Item.
+
+## Установка
+
+```bash
+uv add staged-pipeline            # ядро, без зависимостей
+uv add "staged-pipeline[tallyho]" # + маркер интеграции с Tallyho
+```
+
+Требуется Python 3.13+.
+
+## Quickstart
+
+```python
+import asyncio
+from staged_pipeline import Pipeline
+
+
+async def scan(folder: str):          # async-генератор: потоковый fan-out
+    for i in range(3):
+        yield f"{folder}/{i}"
+
+
+async def resolve(path: str) -> list[str]:   # атомарный fan-out
+    return [f"{path}.a", f"{path}.b"]
+
+
+async def download(url: str) -> None:        # терминальная стадия
+    ...
+
+
+async def main() -> None:
+    pipe = Pipeline("export")
+    listing = pipe.stage("list", scan, workers=2)
+    resolving = pipe.stage("resolve", resolve, workers=8, key=lambda p: p)
+    media = pipe.stage("media", download, workers=4, key=lambda u: u)
+
+    listing.to(resolving)
+    resolving.to(media)
+    listing.seed(["inbox"])
+
+    report = await pipe.run()
+    print(report.stages["media"].ok)
+
+
+asyncio.run(main())
+```
+
+Больше примеров — в [examples/](examples/): `crawler.py` (цикл/самопетля) и `export.py`
+(fan-out + dedup + resume). Оба исполняются в тестах.
+
+## Когда этапы Tallyho, а когда пайплайн
+
+| Критерий | Этапы Tallyho (`sub_batch` + `fed_by`) | Пайплайн внутри Item |
+|---|---|---|
+| Элемент должен пережить падение воркера сам по себе | ✔ | ✘ (resume — через БД домена) |
+| Элементы дешёвые (≪ 100 мс) и их 10⁴–10⁶ на единицу | дорого: строка + коммит на элемент | ✔ |
+| Общая сессия/лиз/соединение на единицу | ✘ (лиз на задачу) | ✔ |
+| Масштаб на несколько машин | ✔ | ✘ |
+| Нужен точный итог по каждому элементу в БД | ✔ | домен пишет сам |
+
+Мост прогресса и остановки к Tallyho — `staged_pipeline.integrations.tallyho` (`track`,
+`outcome_for`), без зависимости от `tallyho`. Подробности — [architecture.md §9](docs/architecture.md).
+
+## Документация
+
+- [Руководство по задачам (юз-кейсы с примерами)](docs/guide.md)
+- [Архитектура и API](docs/architecture.md)
+- [Prior art / ресёрч](docs/research.md)
+- [План реализации](docs/plan/PLAN.md) · [прогресс](docs/plan/PROGRESS.md) ·
+  [решения](docs/plan/DECISIONS.md)
+
+## Лицензия
+
+[MIT](LICENSE).