codeupipe 0.1.0__tar.gz → 1.0.0__tar.gz

codeupipe-1.0.0/LICENSE

@@ -0,0 +1,177 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS

codeupipe-1.0.0/NOTICE

@@ -0,0 +1,4 @@
+codeupipe
+Copyright 2026 Orchestrate LLC
+
+Licensed under the Apache License, Version 2.0. See LICENSE.

codeupipe-1.0.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: codeupipe
+Version: 1.0.0
+Summary: A Python library for writing a program as a pipeline of small steps.
+Author: Joshua Wink
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/orchestrate-solutions/codeupipe
+Project-URL: Repository, https://github.com/orchestrate-solutions/codeupipe
+Project-URL: Issues, https://github.com/orchestrate-solutions/codeupipe/issues
+Keywords: pipeline,filter,payload,composition
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: NOTICE
+Dynamic: license-file
+
+# codeupipe
+
+codeupipe is a Python library for writing a program as a pipeline of small
+steps. It has no dependencies. Python 3.9 or later.
+
+```bash
+pip install codeupipe
+```
+
+## The eight primitives
+
+| Primitive | What it does | Who writes it |
+|---|---|---|
+| **Payload** | Carries the data | The library |
+| **Filter** | Changes the data | You |
+| **Predicate** | Asks a yes-or-no question about the data | You |
+| **Valve** | Joins a Predicate to a Filter: the Filter runs when the answer is yes | The library. You add one with `add_valve(predicate, filter)` |
+| **Tap** | Reads the data as it goes by | You |
+| **Hook** | Is called before and after each step | You |
+| **State** | Records which steps ran | The library |
+| **Pipeline** | Runs the steps in order | You |
+
+## Example
+
+Each class is in its own file. The pipeline file imports them and adds them.
+
+```python
+# discount_filter.py
+class DiscountFilter:
+    def __init__(self, rate):
+        self.rate = rate
+
+    def call(self, payload):
+        return payload.insert("price", round(payload.get("price", 0) * (1 - self.rate), 2))
+```
+
+```python
+# at_least_predicate.py
+class AtLeastPredicate:
+    def __init__(self, key, minimum):
+        self.key = key
+        self.minimum = minimum
+
+    def test(self, payload):
+        return payload.get(self.key, 0) >= self.minimum
+```
+
+```python
+# pricing_pipeline.py
+from codeupipe import Pipeline
+
+from .at_least_predicate import AtLeastPredicate
+from .audit_tap import AuditTap
+from .discount_filter import DiscountFilter
+from .mark_bulk_filter import MarkBulkFilter
+
+
+class PricingPipeline(Pipeline):
+    def __init__(self):
+        super().__init__()
+        self.add_filter(DiscountFilter(0.1))
+        # MarkBulkFilter runs only when the predicate is true.
+        self.add_valve(AtLeastPredicate("qty", 10), MarkBulkFilter())
+        # A Tap failure is recorded and does not stop the run.
+        self.add_tap(AuditTap())
+```
+
+```python
+from codeupipe import Payload
+
+PricingPipeline().run(Payload({"price": 100.0, "qty": 12})).to_dict()
+# {'price': 90.0, 'qty': 12, 'bulk': True}
+```
+
+A step must be a class in a module. A lambda is refused, because a step is
+identified by its type, and State, Hooks and the export use that identity.
+
+## What is in the package
+
+- `codeupipe`: the eight primitives.
+- `python -m codeupipe.lower`: writes a pipeline as plain Python with no
+  import of codeupipe.
+- `codeupipe.config`: reads `cup.config.json`.
+
+The linter is a separate package: `pip install codeupipe-lint`.
+
+## Documentation
+
+- The contract: https://github.com/orchestrate-solutions/codeupipe/blob/main/conformance/API.md
+- The export: https://github.com/orchestrate-solutions/codeupipe/blob/main/docs/static-export.md
+- The config file: https://github.com/orchestrate-solutions/codeupipe/blob/main/docs/config.md
+- The repository: https://github.com/orchestrate-solutions/codeupipe
+
+## License
+
+Apache License 2.0.

codeupipe-1.0.0/README.md

@@ -0,0 +1,96 @@
+# codeupipe
+
+codeupipe is a Python library for writing a program as a pipeline of small
+steps. It has no dependencies. Python 3.9 or later.
+
+```bash
+pip install codeupipe
+```
+
+## The eight primitives
+
+| Primitive | What it does | Who writes it |
+|---|---|---|
+| **Payload** | Carries the data | The library |
+| **Filter** | Changes the data | You |
+| **Predicate** | Asks a yes-or-no question about the data | You |
+| **Valve** | Joins a Predicate to a Filter: the Filter runs when the answer is yes | The library. You add one with `add_valve(predicate, filter)` |
+| **Tap** | Reads the data as it goes by | You |
+| **Hook** | Is called before and after each step | You |
+| **State** | Records which steps ran | The library |
+| **Pipeline** | Runs the steps in order | You |
+
+## Example
+
+Each class is in its own file. The pipeline file imports them and adds them.
+
+```python
+# discount_filter.py
+class DiscountFilter:
+    def __init__(self, rate):
+        self.rate = rate
+
+    def call(self, payload):
+        return payload.insert("price", round(payload.get("price", 0) * (1 - self.rate), 2))
+```
+
+```python
+# at_least_predicate.py
+class AtLeastPredicate:
+    def __init__(self, key, minimum):
+        self.key = key
+        self.minimum = minimum
+
+    def test(self, payload):
+        return payload.get(self.key, 0) >= self.minimum
+```
+
+```python
+# pricing_pipeline.py
+from codeupipe import Pipeline
+
+from .at_least_predicate import AtLeastPredicate
+from .audit_tap import AuditTap
+from .discount_filter import DiscountFilter
+from .mark_bulk_filter import MarkBulkFilter
+
+
+class PricingPipeline(Pipeline):
+    def __init__(self):
+        super().__init__()
+        self.add_filter(DiscountFilter(0.1))
+        # MarkBulkFilter runs only when the predicate is true.
+        self.add_valve(AtLeastPredicate("qty", 10), MarkBulkFilter())
+        # A Tap failure is recorded and does not stop the run.
+        self.add_tap(AuditTap())
+```
+
+```python
+from codeupipe import Payload
+
+PricingPipeline().run(Payload({"price": 100.0, "qty": 12})).to_dict()
+# {'price': 90.0, 'qty': 12, 'bulk': True}
+```
+
+A step must be a class in a module. A lambda is refused, because a step is
+identified by its type, and State, Hooks and the export use that identity.
+
+## What is in the package
+
+- `codeupipe`: the eight primitives.
+- `python -m codeupipe.lower`: writes a pipeline as plain Python with no
+  import of codeupipe.
+- `codeupipe.config`: reads `cup.config.json`.
+
+The linter is a separate package: `pip install codeupipe-lint`.
+
+## Documentation
+
+- The contract: https://github.com/orchestrate-solutions/codeupipe/blob/main/conformance/API.md
+- The export: https://github.com/orchestrate-solutions/codeupipe/blob/main/docs/static-export.md
+- The config file: https://github.com/orchestrate-solutions/codeupipe/blob/main/docs/config.md
+- The repository: https://github.com/orchestrate-solutions/codeupipe
+
+## License
+
+Apache License 2.0.

codeupipe-1.0.0/codeupipe/__init__.py

@@ -0,0 +1,8 @@
+"""codeupipe: the eight primitives, runnable two ways.
+
+``codeupipe.core`` is the dynamic runtime. ``codeupipe.lower`` exports a
+pipeline as plain code with no framework import.
+"""
+
+from .core import *  # noqa: F401,F403
+from .core import __all__  # noqa: F401

codeupipe-1.0.0/codeupipe/config.py

@@ -0,0 +1,83 @@
+"""cup.config.json: what Lint and Compile do when they are given no arguments.
+
+    {"lint":    {"paths": ["src"], "exclude": ["*/generated/*"], "disable": ["CUP-I005"]},
+     "compile": [{"target": "app.pipelines:checkout", "out": "build/checkout",
+                  "lowering": "inline", "observe": false}]}
+
+The file is optional and every key in it is optional. A key is here only
+because a tool reads it: one that no tool reads is an error, not ignored, so
+the file cannot fill up with settings that do nothing. An argument given on
+the command line wins over the file.
+"""
+
+import json
+import os
+from typing import Optional
+
+__all__ = ["ConfigError", "DEFAULT_NAME", "load_config"]
+
+DEFAULT_NAME = "cup.config.json"
+_SECTIONS = ("lint", "compile")
+_LINT_KEYS = ("paths", "exclude", "disable")
+_PIPELINE_KEYS = ("target", "out", "lowering", "observe")
+_LOWERINGS = ("steps", "inline")
+
+
+class ConfigError(Exception):
+    """The config file cannot be used as it is."""
+
+
+def _unknown(where: str, given, allowed) -> None:
+    extra = sorted(set(given) - set(allowed))
+    if extra:
+        raise ConfigError("%s: unknown key %s (the keys are %s)" % (
+            where, ", ".join(repr(key) for key in extra), ", ".join(allowed)))
+
+
+def _strings(where: str, value) -> None:
+    if not (isinstance(value, list) and all(isinstance(item, str) for item in value)):
+        raise ConfigError("%s must be a list of strings" % where)
+
+
+def load_config(path: Optional[str] = None) -> Optional[dict]:
+    """The config as a dict, checked. With no ``path``: ``cup.config.json`` in
+    the working directory, or None when there is no such file."""
+    name = path or DEFAULT_NAME
+    if not os.path.isfile(name):
+        if path is None:
+            return None
+        raise ConfigError("%s: no such file" % name)
+    try:
+        with open(name, encoding="utf-8") as handle:
+            config = json.load(handle)
+    except ValueError as error:
+        raise ConfigError("%s is not valid JSON: %s" % (name, error))
+    if not isinstance(config, dict):
+        raise ConfigError("%s must hold a JSON object" % name)
+    _unknown(name, config, _SECTIONS)
+
+    lint = config.get("lint", {})
+    if not isinstance(lint, dict):
+        raise ConfigError("%s: lint must be an object" % name)
+    _unknown("%s: lint" % name, lint, _LINT_KEYS)
+    for key in lint:
+        _strings("%s: lint.%s" % (name, key), lint[key])
+
+    pipelines = config.get("compile", [])
+    if not isinstance(pipelines, list):
+        raise ConfigError("%s: compile must be a list of pipelines" % name)
+    for index, pipeline in enumerate(pipelines):
+        where = "%s: compile[%d]" % (name, index)
+        if not isinstance(pipeline, dict):
+            raise ConfigError("%s must be an object" % where)
+        _unknown(where, pipeline, _PIPELINE_KEYS)
+        for key in ("target", "out"):
+            if not isinstance(pipeline.get(key), str):
+                raise ConfigError("%s needs %s, a string" % (where, key))
+        if pipeline.get("lowering", "steps") not in _LOWERINGS:
+            raise ConfigError("%s: lowering is one of %s" % (where, ", ".join(_LOWERINGS)))
+        if not isinstance(pipeline.get("observe", False), bool):
+            raise ConfigError("%s: observe is true or false" % where)
+        if pipeline.get("observe") and pipeline.get("lowering") == "inline":
+            raise ConfigError("%s: observe needs the steps lowering, not inline" % where)
+    return config

codeupipe-1.0.0/codeupipe/core/__init__.py

@@ -0,0 +1,29 @@
+"""
+Core: the eight primitives.
+
+Payload, Filter, Predicate, Valve, Tap, Hook, State and Pipeline, as conformance/API.md
+defines them. Standard library only. A Valve is added with
+``Pipeline.add_valve(predicate, filter)``; its class is not a public name.
+"""
+
+from .payload import Payload
+from .filter import AsyncFilter, Filter
+from .async_step_in_sync_run import AsyncStepInSyncRun
+from .anonymous_step import AnonymousStep
+from .pipeline import Pipeline
+from .predicate import Predicate
+from .tap import AsyncTap, Tap
+from .state import State
+from .async_hook import AsyncHook
+from .hook import Hook
+
+__all__ = [
+    "Payload",
+    "Filter", "AsyncFilter",
+    "Pipeline",
+    "Predicate",
+    "Tap", "AsyncTap",
+    "Hook", "AsyncHook",
+    "State",
+    "AnonymousStep", "AsyncStepInSyncRun",
+]

codeupipe-1.0.0/codeupipe/core/anonymous_step.py

@@ -0,0 +1,13 @@
+"""AnonymousStep: a step whose identity cannot be derived from the code.
+
+Step identity is a pointer to the filter (conformance/API.md, "Step
+identity"). Lambdas, closures, classes defined inside a function, filters
+defined in the entry script and unnamed nested pipelines have no stable
+pointer, and are not independently testable, so the runtime refuses them.
+"""
+
+__all__ = ["AnonymousStep"]
+
+
+class AnonymousStep(TypeError):
+    """Raised when a step has no stable identity to report."""

codeupipe-1.0.0/codeupipe/core/async_filter.py

@@ -0,0 +1,26 @@
+"""AsyncFilter protocol — the processing unit that explicitly awaits.
+
+Split from ``filter.py`` to satisfy the one-component-per-file rule (CUP001).
+``Filter`` remains the default; reach for this only when a step truly awaits
+I/O rather than doing CPU-bound work.
+
+``filter.py`` re-exports this name, so ``from codeupipe.core.filter import
+AsyncFilter`` keeps working.
+"""
+
+from typing import Protocol, TypeVar
+
+from .payload import Payload
+
+__all__ = ["AsyncFilter"]
+
+TInput = TypeVar('TInput')
+TOutput = TypeVar('TOutput')
+
+
+class AsyncFilter(Protocol[TInput, TOutput]):
+    """Async processing unit — explicitly opts into suspension."""
+
+    async def call(self, payload: Payload[TInput]) -> Payload[TOutput]:
+        """Process the payload and return a transformed result."""
+        ...

codeupipe-1.0.0/codeupipe/core/async_hook.py

@@ -0,0 +1,26 @@
+"""AsyncHook: a Hook whose methods are coroutines."""
+
+from typing import Optional, TypeVar
+
+from .hook import Hook
+from .payload import Payload
+
+__all__ = ["AsyncHook"]
+
+T = TypeVar('T')
+
+
+class AsyncHook(Hook):
+    """Lifecycle hook that explicitly opts into async suspension."""
+
+    async def before(self, step: Optional[str], payload: Payload[T]) -> None:
+        """Before step ``step`` (its name), or before the pipeline starts (``None``)."""
+        pass
+
+    async def after(self, step: Optional[str], payload: Payload[T]) -> None:
+        """After step ``step`` (its name), or after the pipeline ends (``None``)."""
+        pass
+
+    async def on_error(self, step: Optional[str], error: Exception, payload: Payload[T]) -> None:
+        """Called when an error occurs."""
+        pass

codeupipe-1.0.0/codeupipe/core/async_step_in_sync_run.py

@@ -0,0 +1,7 @@
+"""Raised when the sync ``Pipeline.run()`` meets async work."""
+
+__all__ = ["AsyncStepInSyncRun"]
+
+
+class AsyncStepInSyncRun(RuntimeError):
+    """``run()`` never starts an event loop; use ``run_async()`` for async steps."""

codeupipe-1.0.0/codeupipe/core/async_tap.py

@@ -0,0 +1,25 @@
+"""AsyncTap protocol — the observation point that explicitly awaits.
+
+Split from ``tap.py`` to satisfy the one-component-per-file rule (CUP001).
+Like every Tap it must not modify the payload, and it must not raise into the
+pipeline it observes.
+
+``tap.py`` re-exports this name, so ``from codeupipe.core.tap import AsyncTap``
+keeps working.
+"""
+
+from typing import Protocol, TypeVar
+
+from .payload import Payload
+
+__all__ = ["AsyncTap"]
+
+T = TypeVar('T')
+
+
+class AsyncTap(Protocol[T]):
+    """Async observation point — explicitly opts into suspension."""
+
+    async def observe(self, payload: Payload[T]) -> None:
+        """Observe the payload. Must not modify it."""
+        ...

codeupipe-1.0.0/codeupipe/core/filter.py

@@ -0,0 +1,29 @@
+"""Filter protocol: sync by default, async by declaration.
+
+New code should prefer ``Filter`` for CPU-bound transforms and opt into
+``AsyncFilter`` (in ``async_filter.py``) when the step truly awaits I/O.
+
+The runtime remains backward compatible with legacy async filters passed to
+``Pipeline.add_filter()`` by detecting the coroutine signature at
+registration time.
+"""
+
+from typing import Protocol, TypeVar
+
+from .async_filter import AsyncFilter
+from .payload import Payload
+
+# AsyncFilter is re-exported for backward compatibility — it moved to
+# async_filter.py under the one-component-per-file rule.
+__all__ = ["Filter", "AsyncFilter"]
+
+TInput = TypeVar('TInput')
+TOutput = TypeVar('TOutput')
+
+
+class Filter(Protocol[TInput, TOutput]):
+    """Synchronous processing unit — takes a payload in, returns payload out."""
+
+    def call(self, payload: Payload[TInput]) -> Payload[TOutput]:
+        """Process the payload and return a transformed result."""
+        ...