pyflowstep 0.2.0__tar.gz → 0.4.0__tar.gz

{pyflowstep-0.2.0 → pyflowstep-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyflowstep
-Version: 0.2.0
+Version: 0.4.0
 Summary: A lightweight, typed Python library for composing functions into readable, reusable flows that can be defined as JSON.
 Keywords: flow,pipeline,composition,functional,fluent-interface,json,json-schema,workflow,dsl
 Author: aaltatan
@@ -32,6 +32,7 @@ A lightweight, typed Python library for composing functions into readable, reusa
 - step arguments are validated and parsed when a flow is **built**, not halfway through running it
 - raw JSON values become typed arguments with a `Parse` marker next to the parameter
 - steps get external objects (a mailer, a database session) through FastAPI-style `Depends`
+- the caller hands per-run values to a flow by name: `flow(page, user=user)` fills every `user: User = Input()`
 - registry-based registration keeps steps organized and discoverable
 - flow definitions can be compiled from dictionaries or JSON
 - every registry can describe its flow language as a JSON Schema
@@ -181,7 +182,7 @@ pipeline      # Flow(add >> multiply >> add)
 pipeline(1)   # 31
 ```
 
-`step` and `tap` do one thing: turn a function into a flow factory. Naming a step belongs to the [registry](#registry). Two markers can sit on a parameter: [`Parse`](#parsing-arguments) to convert the value passed for it, and [`Depends`](#dependencies) to inject an object nobody passes.
+`step` and `tap` do one thing: turn a function into a flow factory. Naming a step belongs to the [registry](#registry). Three markers can sit on a parameter: [`Parse`](#parsing-arguments) to convert the value passed for it, [`Depends`](#dependencies) to inject an object nobody passes, and [`Input`](#run-inputs) to receive a value from whoever runs the flow.
 
 Arguments are bound against the function signature **immediately**, so mistakes fail fast:
 
@@ -442,6 +443,8 @@ def send_email(order: Order, template: str, mailer: MailerDep) -> None: ...
 def send_invoice(order: Order, mailer: MailerDep) -> None: ...
 ```
 
+Both forms behave the same when the flow runs. Type checkers differ: with the `Annotated` form they still see `mailer` as a required argument and report `send_email("receipt")` as missing it. Use the default-value form for steps you call from Python; the `Annotated` form suits steps that are only used from JSON.
+
 ### One object per flow run
 
 A flow run is one scope, like one request in a web framework. A provider is called **at most once per run**, and every step of that run receives the same object. The next run starts fresh.
@@ -532,6 +535,89 @@ See [`examples/dependencies.py`](examples/dependencies.py) for a complete flow w
 
 ---
 
+## Run inputs
+
+Some values exist only where the flow is run: the logged-in user, the record being processed, credentials read from a prompt. No provider can build them and JSON must not hold them. Give the parameter the default `Input()` and the caller supplies it, by name, when it runs the flow:
+
+```python
+from pyflowstep import Input, StepsRegistry
+
+steps = StepsRegistry[Page]()
+
+
+@steps.tap()
+def login(page: Page, url: str, credentials: Credentials = Input()) -> None:
+    page.navigate(url)
+    page.fill("#user", credentials.username)
+    page.fill("#password", credentials.password)
+
+
+@steps.tap()
+def fill_year(page: Page, selector: str, voucher: Voucher = Input()) -> None:
+    page.fill(selector, voucher.year)
+
+
+flow = login("https://example.com/login") >> fill_year("#year")   # inputs are not arguments
+
+flow(page, credentials=credentials, voucher=voucher)              # they are given to the run
+```
+
+```json
+[
+  {"name": "login", "args": ["https://example.com/login"]},
+  {"name": "fill_year", "args": ["#year"]}
+]
+```
+
+The name of the input is the name of the parameter, and every step that declares it receives the same value.
+
+`Input()` is written as the default value, never inside `Annotated`, so that type checkers see the parameter as optional and accept `fill_year("#year")`.
+
+### Checked before anything runs
+
+A flow knows the inputs its steps require, and checks them before the first step runs. A forgotten input never fails halfway through:
+
+```python
+flow.inputs   # frozenset({'credentials', 'voucher'})
+
+flow(page, credentials=credentials)
+# MissingInputError: missing run input 'voucher' for step 'fill_year'; run the flow as flow(subject, voucher=...)
+```
+
+### Rules
+
+- **Invisible to JSON**, like a dependency: an input is absent from the JSON schema, cannot be parsed, and passing one while building the flow raises `UnexpectedKeywordArgumentError` (or `TooManyArgumentsError`).
+- **`Input(default=...)` makes the input optional**: with `note: str = Input(default="")`, `""` is used when the caller passes no `note`. Optional inputs are not listed in `flow.inputs`.
+- **Extra inputs are ignored**, so one caller can run different flows, each using the inputs it needs.
+- **Nested flows see the inputs of the run they join.** A flow called from inside a step can be given inputs of its own, `inner(page, voucher=other)`; they are laid over the outer ones for that call only.
+- **Declarations are checked early**, when the step is created, with `InvalidInputError`: an input on the subject, on a positional-only parameter, on a parameter that is also a dependency, or written inside `Annotated`. A provider cannot take an input.
+
+Using ruff? Add `Input` next to `Depends` for its `B008` rule:
+
+```toml
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = ["pyflowstep.Depends", "pyflowstep.Input"]
+```
+
+### Upgrading from 0.3
+
+`Input[T]` is gone, because a type checker reported `fill_year("#year")` as missing its `voucher` argument. Move the marker to the default value:
+
+| 0.3                                | 0.4                                      |
+| ---------------------------------- | ---------------------------------------- |
+| `voucher: Input[Voucher]`          | `voucher: Voucher = Input()`             |
+| `note: Input[str] = ""`            | `note: str = Input(default="")`          |
+
+### `Input` or `Depends`?
+
+| The object…                                                  | Use                                   |
+| ------------------------------------------------------------ | ------------------------------------- |
+| is written in the flow definition (a selector, a limit)      | a plain argument, with `Parse` if needed |
+| can be built by a function, the same way for every caller (a mailer, a session) | `Depends(provider)`     |
+| is only known to whoever runs the flow (a user, a record, credentials) | `Input()`                   |
+
+---
+
 ## Compiling flows from JSON
 
 `FlowCompiler` turns a flow definition — a list of step dictionaries — into a `Flow`.
@@ -738,13 +824,15 @@ checkout = note_if(is_large(Decimal(100)), "needs approval") >> apply_tax(round(
 | `Parse(fn)`                                                  | marker    | Apply `fn` to the value passed for a parameter, see [Parsing arguments](#parsing-arguments) |
 | `Depends(provider)`                                          | marker    | Inject a parameter by calling `provider`, see [Dependencies](#dependencies) |
 | `override_dependencies(mapping)`                             | context manager | Replace providers inside a `with` block, for tests        |
+| `Input(default=...)`                                         | marker    | Receive a parameter from the caller of the flow, `flow(subject, name=value)`, see [Run inputs](#run-inputs) |
+| `Flow.inputs`                                                | property  | The names of the inputs a flow requires                         |
 | `FlowCompiler[T](steps)`                                     | class     | `compile(definition)` turns parsed step dicts into a flow       |
 | `validate_step_dict(item, path)`                             | function  | Validate one step dictionary                                    |
 | `get_json_schema(annotation)`                                | function  | JSON Schema of a type annotation                                |
 | `get_step_json_schema(name, step)`                           | function  | JSON Schema of one step dictionary                              |
 | `get_flow_json_schema(steps)`                                | function  | JSON Schema of a whole flow definition                          |
 
-All exceptions derive from `PyflowstepError`; argument errors, `InvalidParserError` and `InvalidDependencyError` also derive from `TypeError`, definition errors from `ValueError`, and `StepDoesNotExistError` from `LookupError`.
+All exceptions derive from `PyflowstepError`; argument errors, `InvalidParserError`, `InvalidDependencyError`, `InvalidInputError` and `MissingInputError` also derive from `TypeError`, definition errors from `ValueError`, and `StepDoesNotExistError` from `LookupError`.
 
 ---
 

{pyflowstep-0.2.0 → pyflowstep-0.4.0}/README.md

@@ -9,6 +9,7 @@ A lightweight, typed Python library for composing functions into readable, reusa
 - step arguments are validated and parsed when a flow is **built**, not halfway through running it
 - raw JSON values become typed arguments with a `Parse` marker next to the parameter
 - steps get external objects (a mailer, a database session) through FastAPI-style `Depends`
+- the caller hands per-run values to a flow by name: `flow(page, user=user)` fills every `user: User = Input()`
 - registry-based registration keeps steps organized and discoverable
 - flow definitions can be compiled from dictionaries or JSON
 - every registry can describe its flow language as a JSON Schema
@@ -158,7 +159,7 @@ pipeline      # Flow(add >> multiply >> add)
 pipeline(1)   # 31
 ```
 
-`step` and `tap` do one thing: turn a function into a flow factory. Naming a step belongs to the [registry](#registry). Two markers can sit on a parameter: [`Parse`](#parsing-arguments) to convert the value passed for it, and [`Depends`](#dependencies) to inject an object nobody passes.
+`step` and `tap` do one thing: turn a function into a flow factory. Naming a step belongs to the [registry](#registry). Three markers can sit on a parameter: [`Parse`](#parsing-arguments) to convert the value passed for it, [`Depends`](#dependencies) to inject an object nobody passes, and [`Input`](#run-inputs) to receive a value from whoever runs the flow.
 
 Arguments are bound against the function signature **immediately**, so mistakes fail fast:
 
@@ -419,6 +420,8 @@ def send_email(order: Order, template: str, mailer: MailerDep) -> None: ...
 def send_invoice(order: Order, mailer: MailerDep) -> None: ...
 ```
 
+Both forms behave the same when the flow runs. Type checkers differ: with the `Annotated` form they still see `mailer` as a required argument and report `send_email("receipt")` as missing it. Use the default-value form for steps you call from Python; the `Annotated` form suits steps that are only used from JSON.
+
 ### One object per flow run
 
 A flow run is one scope, like one request in a web framework. A provider is called **at most once per run**, and every step of that run receives the same object. The next run starts fresh.
@@ -509,6 +512,89 @@ See [`examples/dependencies.py`](examples/dependencies.py) for a complete flow w
 
 ---
 
+## Run inputs
+
+Some values exist only where the flow is run: the logged-in user, the record being processed, credentials read from a prompt. No provider can build them and JSON must not hold them. Give the parameter the default `Input()` and the caller supplies it, by name, when it runs the flow:
+
+```python
+from pyflowstep import Input, StepsRegistry
+
+steps = StepsRegistry[Page]()
+
+
+@steps.tap()
+def login(page: Page, url: str, credentials: Credentials = Input()) -> None:
+    page.navigate(url)
+    page.fill("#user", credentials.username)
+    page.fill("#password", credentials.password)
+
+
+@steps.tap()
+def fill_year(page: Page, selector: str, voucher: Voucher = Input()) -> None:
+    page.fill(selector, voucher.year)
+
+
+flow = login("https://example.com/login") >> fill_year("#year")   # inputs are not arguments
+
+flow(page, credentials=credentials, voucher=voucher)              # they are given to the run
+```
+
+```json
+[
+  {"name": "login", "args": ["https://example.com/login"]},
+  {"name": "fill_year", "args": ["#year"]}
+]
+```
+
+The name of the input is the name of the parameter, and every step that declares it receives the same value.
+
+`Input()` is written as the default value, never inside `Annotated`, so that type checkers see the parameter as optional and accept `fill_year("#year")`.
+
+### Checked before anything runs
+
+A flow knows the inputs its steps require, and checks them before the first step runs. A forgotten input never fails halfway through:
+
+```python
+flow.inputs   # frozenset({'credentials', 'voucher'})
+
+flow(page, credentials=credentials)
+# MissingInputError: missing run input 'voucher' for step 'fill_year'; run the flow as flow(subject, voucher=...)
+```
+
+### Rules
+
+- **Invisible to JSON**, like a dependency: an input is absent from the JSON schema, cannot be parsed, and passing one while building the flow raises `UnexpectedKeywordArgumentError` (or `TooManyArgumentsError`).
+- **`Input(default=...)` makes the input optional**: with `note: str = Input(default="")`, `""` is used when the caller passes no `note`. Optional inputs are not listed in `flow.inputs`.
+- **Extra inputs are ignored**, so one caller can run different flows, each using the inputs it needs.
+- **Nested flows see the inputs of the run they join.** A flow called from inside a step can be given inputs of its own, `inner(page, voucher=other)`; they are laid over the outer ones for that call only.
+- **Declarations are checked early**, when the step is created, with `InvalidInputError`: an input on the subject, on a positional-only parameter, on a parameter that is also a dependency, or written inside `Annotated`. A provider cannot take an input.
+
+Using ruff? Add `Input` next to `Depends` for its `B008` rule:
+
+```toml
+[tool.ruff.lint.flake8-bugbear]
+extend-immutable-calls = ["pyflowstep.Depends", "pyflowstep.Input"]
+```
+
+### Upgrading from 0.3
+
+`Input[T]` is gone, because a type checker reported `fill_year("#year")` as missing its `voucher` argument. Move the marker to the default value:
+
+| 0.3                                | 0.4                                      |
+| ---------------------------------- | ---------------------------------------- |
+| `voucher: Input[Voucher]`          | `voucher: Voucher = Input()`             |
+| `note: Input[str] = ""`            | `note: str = Input(default="")`          |
+
+### `Input` or `Depends`?
+
+| The object…                                                  | Use                                   |
+| ------------------------------------------------------------ | ------------------------------------- |
+| is written in the flow definition (a selector, a limit)      | a plain argument, with `Parse` if needed |
+| can be built by a function, the same way for every caller (a mailer, a session) | `Depends(provider)`     |
+| is only known to whoever runs the flow (a user, a record, credentials) | `Input()`                   |
+
+---
+
 ## Compiling flows from JSON
 
 `FlowCompiler` turns a flow definition — a list of step dictionaries — into a `Flow`.
@@ -715,13 +801,15 @@ checkout = note_if(is_large(Decimal(100)), "needs approval") >> apply_tax(round(
 | `Parse(fn)`                                                  | marker    | Apply `fn` to the value passed for a parameter, see [Parsing arguments](#parsing-arguments) |
 | `Depends(provider)`                                          | marker    | Inject a parameter by calling `provider`, see [Dependencies](#dependencies) |
 | `override_dependencies(mapping)`                             | context manager | Replace providers inside a `with` block, for tests        |
+| `Input(default=...)`                                         | marker    | Receive a parameter from the caller of the flow, `flow(subject, name=value)`, see [Run inputs](#run-inputs) |
+| `Flow.inputs`                                                | property  | The names of the inputs a flow requires                         |
 | `FlowCompiler[T](steps)`                                     | class     | `compile(definition)` turns parsed step dicts into a flow       |
 | `validate_step_dict(item, path)`                             | function  | Validate one step dictionary                                    |
 | `get_json_schema(annotation)`                                | function  | JSON Schema of a type annotation                                |
 | `get_step_json_schema(name, step)`                           | function  | JSON Schema of one step dictionary                              |
 | `get_flow_json_schema(steps)`                                | function  | JSON Schema of a whole flow definition                          |
 
-All exceptions derive from `PyflowstepError`; argument errors, `InvalidParserError` and `InvalidDependencyError` also derive from `TypeError`, definition errors from `ValueError`, and `StepDoesNotExistError` from `LookupError`.
+All exceptions derive from `PyflowstepError`; argument errors, `InvalidParserError`, `InvalidDependencyError`, `InvalidInputError` and `MissingInputError` also derive from `TypeError`, definition errors from `ValueError`, and `StepDoesNotExistError` from `LookupError`.
 
 ---
 

{pyflowstep-0.2.0 → pyflowstep-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyflowstep"
-version = "0.2.0"
+version = "0.4.0"
 description = "A lightweight, typed Python library for composing functions into readable, reusable flows that can be defined as JSON."
 readme = "README.md"
 license = "GPL-3.0-only"
@@ -101,6 +101,8 @@ ignore = [
 extend-immutable-calls = [
     "pyflowstep.Depends",
     "pyflowstep.dependencies.Depends",
+    "pyflowstep.Input",
+    "pyflowstep.inputs.Input",
 ]
 
 [tool.ruff.lint.per-file-ignores]

{pyflowstep-0.2.0 → pyflowstep-0.4.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "pyflowstep"
-version = "0.2.0"
+version = "0.4.0"
 description = "A lightweight, typed Python library for composing functions into readable, reusable flows that can be defined as JSON."
 readme = "README.md"
 authors = [
@@ -80,8 +80,13 @@ ignore = [
 ]
 
 [tool.ruff.lint.flake8-bugbear]
-# `x: T = Depends(provider)` is a marker, not a mutable default
-extend-immutable-calls = ["pyflowstep.Depends", "pyflowstep.dependencies.Depends"]
+# `x: T = Depends(provider)` and `x: T = Input()` are markers, not mutable defaults
+extend-immutable-calls = [
+    "pyflowstep.Depends",
+    "pyflowstep.dependencies.Depends",
+    "pyflowstep.Input",
+    "pyflowstep.inputs.Input",
+]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**" = ["S101", "PLR2004", "ANN", "ARG", "INP001", "E501"]

{pyflowstep-0.2.0 → pyflowstep-0.4.0}/src/pyflowstep/__init__.py

@@ -27,10 +27,12 @@ from .exceptions import (
     ArgumentError,
     InvalidDependencyError,
     InvalidFlowDefinitionError,
+    InvalidInputError,
     InvalidParserError,
     InvalidStepError,
     InvalidStepNameError,
     MissingArgumentError,
+    MissingInputError,
     MultipleValuesArgumentError,
     ParseArgumentError,
     PositionalOnlyArgumentError,
@@ -41,6 +43,7 @@ from .exceptions import (
     UnexpectedKeywordArgumentError,
 )
 from .flow import Action, Flow, compose
+from .inputs import Input
 from .json_schema import get_flow_json_schema, get_json_schema, get_step_json_schema
 from .parsers import Parse
 from .registry import StepsRegistry
@@ -53,12 +56,15 @@ __all__ = [
     "Flow",
     "FlowCompiler",
     "FlowDefinition",
+    "Input",
     "InvalidDependencyError",
     "InvalidFlowDefinitionError",
+    "InvalidInputError",
     "InvalidParserError",
     "InvalidStepError",
     "InvalidStepNameError",
     "MissingArgumentError",
+    "MissingInputError",
     "MultipleValuesArgumentError",
     "Parse",
     "ParseArgumentError",

{pyflowstep-0.2.0 → pyflowstep-0.4.0}/src/pyflowstep/annotations.py

@@ -1,59 +1,90 @@
-"""Read the annotations that carry markers such as `Parse` and `Depends`."""
-
-from collections.abc import Callable
-from functools import partial
-from inspect import get_annotations, isroutine
-from typing import Annotated, Any, TypeAliasType, get_args, get_origin
-
-
-def resolved_annotations(fn: Callable[..., Any]) -> dict[str, Any]:
-    """Return the annotations describing a call to `fn`, with strings evaluated when possible.
-
-    For a class this is its `__init__`, for a callable object its `__call__`,
-    and for a `functools.partial` the function it wraps.
-
-    Example:
-    ```python
-    >>> def wait(page, selector: "str", timeout: float = 5.0): ...
-    >>> resolved_annotations(wait)
-    {'selector': <class 'str'>, 'timeout': <class 'float'>}
-
-    ```
-
-    """
-    target = _annotated_function(fn)
-
-    try:
-        return get_annotations(target, eval_str=True)
-    except NameError:
-        return get_annotations(target)
-
-
-def annotated_metadata(annotation: Any) -> tuple[Any, ...]:
-    """Return the extra arguments of `Annotated[...]`, looking through `type` aliases.
-
-    Example:
-    ```python
-    >>> type Port = Annotated[int, "tcp", 8080]
-    >>> annotated_metadata(Port)
-    ('tcp', 8080)
-    >>> annotated_metadata(int)
-    ()
-
-    ```
-
-    """
-    while isinstance(annotation, TypeAliasType):
-        annotation = annotation.__value__
-
-    return get_args(annotation)[1:] if get_origin(annotation) is Annotated else ()
-
-
-def _annotated_function(fn: Callable[..., Any]) -> Callable[..., Any]:
-    if isinstance(fn, partial):
-        return _annotated_function(fn.func)
-
-    if isinstance(fn, type):
-        return fn.__init__
-
-    return fn if isroutine(fn) else type(fn).__call__
+"""Read the annotations that carry markers such as `Parse` and `Depends`."""
+
+from collections.abc import Callable
+from functools import partial
+from inspect import get_annotations, isroutine
+from typing import Annotated, Any, TypeAliasType, get_args, get_origin
+
+
+def resolved_annotations(fn: Callable[..., Any]) -> dict[str, Any]:
+    """Return the annotations describing a call to `fn`, with strings evaluated when possible.
+
+    For a class this is its `__init__`, for a callable object its `__call__`,
+    and for a `functools.partial` the function it wraps.
+
+    Example:
+    ```python
+    >>> def wait(page, selector: "str", timeout: float = 5.0): ...
+    >>> resolved_annotations(wait)
+    {'selector': <class 'str'>, 'timeout': <class 'float'>}
+
+    ```
+
+    """
+    target = _annotated_function(fn)
+
+    try:
+        return get_annotations(target, eval_str=True)
+    except NameError:
+        return get_annotations(target)
+
+
+def annotated_metadata(annotation: Any) -> tuple[Any, ...]:
+    """Return the extra arguments of `Annotated[...]`, looking through `type` aliases.
+
+    Example:
+    ```python
+    >>> type Port = Annotated[int, "tcp", 8080]
+    >>> annotated_metadata(Port)
+    ('tcp', 8080)
+    >>> annotated_metadata(int)
+    ()
+    >>> type Tagged[T] = Annotated[T, "tag"]
+    >>> annotated_metadata(Tagged[int])
+    ('tag',)
+    >>> annotated_metadata(Annotated[Tagged[Port], "outer"])
+    ('tcp', 8080, 'tag', 'outer')
+    >>> type Fixed[T] = Annotated[int, "fixed"]
+    >>> annotated_metadata(Fixed[str])
+    ('fixed',)
+
+    ```
+
+    """
+    annotation = _alias_value(annotation)
+
+    if get_origin(annotation) is not Annotated:
+        return ()
+
+    inner, *metadata = get_args(annotation)
+    return (*annotated_metadata(inner), *metadata)
+
+
+def _alias_value(annotation: Any) -> Any:
+    """Return what a `type` alias stands for, also when it is subscripted (`Alias[int]`)."""
+    while True:
+        origin = get_origin(annotation)
+
+        if isinstance(annotation, TypeAliasType):
+            annotation = annotation.__value__
+        elif isinstance(origin, TypeAliasType):
+            annotation = _substituted(origin.__value__, get_args(annotation))
+        else:
+            return annotation
+
+
+def _substituted(value: Any, arguments: tuple[Any, ...]) -> Any:
+    try:
+        return value[arguments]
+    except TypeError:  # the alias does not use its type parameters
+        return value
+
+
+def _annotated_function(fn: Callable[..., Any]) -> Callable[..., Any]:
+    if isinstance(fn, partial):
+        return _annotated_function(fn.func)
+
+    if isinstance(fn, type):
+        return fn.__init__
+
+    return fn if isroutine(fn) else type(fn).__call__