pyflowstep 0.3.0__tar.gz → 0.4.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyflowstep
-Version: 0.3.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,7 +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: Input[User]`
+- 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
@@ -443,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.
@@ -535,7 +537,7 @@ 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. Annotate the parameter with `Input[T]` and the caller supplies it, by name, when it runs the flow:
+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
@@ -544,14 +546,14 @@ steps = StepsRegistry[Page]()
 
 
 @steps.tap()
-def login(page: Page, url: str, credentials: Input[Credentials]) -> None:
+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: Input[Voucher]) -> None:
+def fill_year(page: Page, selector: str, voucher: Voucher = Input()) -> None:
     page.fill(selector, voucher.year)
 
 
@@ -569,6 +571,8 @@ flow(page, credentials=credentials, voucher=voucher)              # they are giv
 
 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:
@@ -583,10 +587,26 @@ flow(page, credentials=credentials)
 ### 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`).
-- **A default value makes the input optional**: `note: Input[str] = ""` is used when the caller passes no `note`. Optional inputs are not listed in `flow.inputs`.
+- **`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, `*args` or `**kwargs` parameter, or on a parameter that is also a dependency. A provider cannot take an input.
+- **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`?
 
@@ -594,7 +614,7 @@ flow(page, credentials=credentials)
 | ------------------------------------------------------------ | ------------------------------------- |
 | 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[T]`                  |
+| is only known to whoever runs the flow (a user, a record, credentials) | `Input()`                   |
 
 ---
 
@@ -804,7 +824,7 @@ 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[T]`                                                   | marker    | Receive a parameter from the caller of the flow, `flow(subject, name=value)`, see [Run inputs](#run-inputs) |
+| `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                                    |

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

@@ -9,7 +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: Input[User]`
+- 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
@@ -420,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.
@@ -512,7 +514,7 @@ 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. Annotate the parameter with `Input[T]` and the caller supplies it, by name, when it runs the flow:
+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
@@ -521,14 +523,14 @@ steps = StepsRegistry[Page]()
 
 
 @steps.tap()
-def login(page: Page, url: str, credentials: Input[Credentials]) -> None:
+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: Input[Voucher]) -> None:
+def fill_year(page: Page, selector: str, voucher: Voucher = Input()) -> None:
     page.fill(selector, voucher.year)
 
 
@@ -546,6 +548,8 @@ flow(page, credentials=credentials, voucher=voucher)              # they are giv
 
 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:
@@ -560,10 +564,26 @@ flow(page, credentials=credentials)
 ### 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`).
-- **A default value makes the input optional**: `note: Input[str] = ""` is used when the caller passes no `note`. Optional inputs are not listed in `flow.inputs`.
+- **`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, `*args` or `**kwargs` parameter, or on a parameter that is also a dependency. A provider cannot take an input.
+- **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`?
 
@@ -571,7 +591,7 @@ flow(page, credentials=credentials)
 | ------------------------------------------------------------ | ------------------------------------- |
 | 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[T]`                  |
+| is only known to whoever runs the flow (a user, a record, credentials) | `Input()`                   |
 
 ---
 
@@ -781,7 +801,7 @@ 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[T]`                                                   | marker    | Receive a parameter from the caller of the flow, `flow(subject, name=value)`, see [Run inputs](#run-inputs) |
+| `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                                    |

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

@@ -1,6 +1,6 @@
 [project]
 name = "pyflowstep"
-version = "0.3.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.3.0 → pyflowstep-0.4.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "pyflowstep"
-version = "0.3.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.3.0 → pyflowstep-0.4.0}/src/pyflowstep/dependencies.py

@@ -35,6 +35,7 @@ from typing import Any
 
 from .annotations import annotated_metadata, resolved_annotations
 from .exceptions import InvalidDependencyError
+from .inputs import RunInput
 
 type Provider = Callable[..., Any]
 
@@ -292,6 +293,13 @@ def _validate_provider(provider: Provider, path: tuple[Provider, ...]) -> None:
     dependencies = find_dependencies(provider)
 
     for name, parameter in parameters.items():
+        if isinstance(parameter.default, RunInput):
+            msg = (
+                f"Provider '{_name(provider)}' cannot take the run input '{name}'; "
+                "only steps receive run inputs"
+            )
+            raise InvalidDependencyError(msg)
+
         if name in dependencies and parameter.kind in _UNSUPPORTED_KINDS:
             msg = (
                 f"Provider '{_name(provider)}' cannot inject {parameter.kind.description} "

{pyflowstep-0.3.0 → pyflowstep-0.4.0}/src/pyflowstep/exceptions.py

@@ -50,10 +50,11 @@ class InvalidDependencyError(PyflowstepError, TypeError):
 
 
 class InvalidInputError(PyflowstepError, TypeError):
-    """Raised when an `Input[...]` declaration cannot work.
+    """Raised when an `Input()` declaration cannot work.
 
-    For example an input on the subject, on a positional-only, `*args` or
-    `**kwargs` parameter, or on a parameter that is also a dependency.
+    For example an input on the subject, on a positional-only parameter, on a
+    parameter that is also a dependency, or written inside `Annotated` instead
+    of as the default value.
     """
 
 

{pyflowstep-0.3.0 → pyflowstep-0.4.0}/src/pyflowstep/flow.py

@@ -18,7 +18,7 @@ class Flow[T]:
     with `>>`, which always returns a *new* flow and never mutates its operands.
 
     Keyword arguments given to the call are the run inputs: `flow(page, user=user)`
-    hands `user` to every step that declares `user: Input[User]`.
+    hands `user` to every step that declares `user: User = Input()`.
 
     Args:
         *actions: The callables to run, in order. Each one takes the subject and

{pyflowstep-0.3.0 → pyflowstep-0.4.0}/src/pyflowstep/inputs.py

@@ -1,178 +1,231 @@
-"""Run inputs: hand a flow the values only its caller has, when it runs.
-
-A step parameter annotated with `Input[T]` is not an argument of the step:
-nobody passes it while the flow is built, neither Python nor JSON. The caller
-supplies it by name when it runs the flow:
-
-    @step
-    def fill_year(page: Page, selector: str, voucher: Input[Voucher]) -> Page: ...
-
-    flow = fill_year("#year")      # only `selector` is an argument
-    flow(page, voucher=voucher)    # `voucher` is supplied for this run
-
-The name of the input is the name of the parameter. A flow checks the inputs
-its steps require before the first step runs, so a forgotten one never fails
-halfway through. A parameter with a default value is an optional input.
-
-Use `Depends` when a provider can build the object, and `Input` when only the
-caller of the flow has it.
-
-Example:
-```python
->>> from pyflowstep import step
->>> @step
-... def add_tax(price: float, rate: Input[float]) -> float:
-...     return price * (1 + rate)
->>> add_tax()(100.0, rate=0.25)
-125.0
->>> add_tax()(100.0)
-Traceback (most recent call last):
-...
-pyflowstep.exceptions.MissingInputError: missing run input 'rate' for step 'add_tax'...
-
-```
-
-"""
-
-from collections.abc import Callable, Iterable, Mapping
-from dataclasses import dataclass
-from inspect import Parameter, signature
-from typing import Annotated, Any
-
-from .annotations import annotated_metadata, resolved_annotations
-from .dependencies import Run
-from .exceptions import InvalidInputError, MissingInputError
-
-_UNSUPPORTED_KINDS = (Parameter.POSITIONAL_ONLY, Parameter.VAR_POSITIONAL, Parameter.VAR_KEYWORD)
-_REQUIRED_INPUTS = "__pyflowstep_inputs__"
-
-
-@dataclass(frozen=True, slots=True)
-class RunInput:
-    """The marker carried by `Input[T]`: "the caller of the flow supplies this parameter"."""
-
-
-type Input[T] = Annotated[T, RunInput()]
-
-
-def find_inputs(fn: Callable[..., Any]) -> dict[str, bool]:
-    """Return the parameters of `fn` marked with `Input`, mapped to whether they are required.
-
-    Example:
-    ```python
-    >>> def add_tax(price: float, label: str, rate: Input[float], bonus: Input[float] = 0.0): ...
-    >>> find_inputs(add_tax)
-    {'rate': True, 'bonus': False}
-
-    ```
-
-    """
-    annotations = resolved_annotations(fn)
-    return {
-        name: parameter.default is Parameter.empty
-        for name, parameter in signature(fn).parameters.items()
-        if any(isinstance(item, RunInput) for item in annotated_metadata(annotations.get(name)))
-    }
-
-
-def step_inputs(fn: Callable[..., Any], step_name: str) -> dict[str, bool]:
-    """Return the inputs of a step function after validating them.
-
-    Raises:
-        InvalidInputError: If the subject is marked, or an input sits on a
-            positional-only, `*args` or `**kwargs` parameter.
-
-    """
-    inputs = find_inputs(fn)
-    parameters = signature(fn).parameters
-    subject = next(iter(parameters))
-
-    if subject in inputs:
-        msg = f"Step '{step_name}' cannot take its subject '{subject}' as a run input"
-        raise InvalidInputError(msg)
-
-    for name in inputs:
-        if parameters[name].kind in _UNSUPPORTED_KINDS:
-            msg = (
-                f"Step '{step_name}' cannot take {parameters[name].kind.description} "
-                f"parameter '{name}' as a run input"
-            )
-            raise InvalidInputError(msg)
-
-    return inputs
-
-
-def resolve_inputs(run: Run, inputs: Mapping[str, bool], step_name: str) -> dict[str, Any]:
-    """Return the value of every input the run was given, optional ones only when present.
-
-    Raises:
-        MissingInputError: If the run was not given a required input.
-
-    """
-    missing = [name for name, required in inputs.items() if required and name not in run.inputs]
-
-    if missing:
-        raise MissingInputError(_missing_message((name, step_name) for name in missing))
-
-    return {name: run.inputs[name] for name in inputs if name in run.inputs}
-
-
-def mark_required_inputs(action: Callable[..., Any], inputs: Mapping[str, bool]) -> None:
-    """Record on a step action the inputs it requires, for `required_inputs` to read."""
-    required = frozenset(name for name, required in inputs.items() if required)
-    setattr(action, _REQUIRED_INPUTS, required)
-
-
-def required_inputs(action: Callable[..., Any]) -> frozenset[str]:
-    """Return the names of the inputs an action requires; plain callables require none.
-
-    Example:
-    ```python
-    >>> from pyflowstep import step
-    >>> @step
-    ... def add_tax(price: float, rate: Input[float], bonus: Input[float] = 0.0) -> float:
-    ...     return price * (1 + rate) + bonus
-    >>> required_inputs(add_tax().actions[0])
-    frozenset({'rate'})
-    >>> required_inputs(abs)
-    frozenset()
-
-    ```
-
-    """
-    return getattr(action, _REQUIRED_INPUTS, frozenset())
-
-
-def check_inputs(actions: Iterable[Callable[..., Any]], given: Mapping[str, Any]) -> None:
-    """Raise if `given` lacks an input one of `actions` requires.
-
-    Raises:
-        MissingInputError: Naming every missing input and the step that needs it.
-
-    """
-    missing = [
-        (name, getattr(action, "__name__", repr(action)))
-        for action in actions
-        for name in sorted(required_inputs(action) - given.keys())
-    ]
-
-    if missing:
-        raise MissingInputError(_missing_message(missing))
-
-
-def _missing_message(missing: Iterable[tuple[str, str]]) -> str:
-    steps_by_input: dict[str, list[str]] = {}
-
-    for name, step_name in missing:
-        steps = steps_by_input.setdefault(name, [])
-        if step_name not in steps:
-            steps.append(step_name)
-
-    details = ", ".join(
-        f"'{name}' for step{'s' if len(steps) > 1 else ''} {', '.join(map(repr, steps))}"
-        for name, steps in steps_by_input.items()
-    )
-    names = ", ".join(f"{name}=..." for name in steps_by_input)
-    plural = "s" if len(steps_by_input) > 1 else ""
-
-    return f"missing run input{plural} {details}; run the flow as flow(subject, {names})"
+"""Run inputs: hand a flow the values only its caller has, when it runs.
+
+A step parameter whose default is `Input()` is not an argument of the step:
+nobody passes it while the flow is built, neither Python nor JSON. The caller
+supplies it by name when it runs the flow:
+
+    @step
+    def fill_year(page: Page, selector: str, voucher: Voucher = Input()) -> Page: ...
+
+    flow = fill_year("#year")      # only `selector` is an argument
+    flow(page, voucher=voucher)    # `voucher` is supplied for this run
+
+The name of the input is the name of the parameter. A flow checks the inputs
+its steps require before the first step runs, so a forgotten one never fails
+halfway through. `Input(default=...)` makes the input optional.
+
+Use `Depends` when a provider can build the object, and `Input` when only the
+caller of the flow has it.
+
+Example:
+```python
+>>> from pyflowstep import step
+>>> @step
+... def add_tax(price: float, rate: float = Input()) -> float:
+...     return price * (1 + rate)
+>>> add_tax()(100.0, rate=0.25)
+125.0
+>>> add_tax()(100.0)
+Traceback (most recent call last):
+...
+pyflowstep.exceptions.MissingInputError: missing run input 'rate' for step 'add_tax'...
+
+```
+
+"""
+
+from collections.abc import Callable, Iterable, Mapping
+from dataclasses import dataclass
+from inspect import Parameter, signature
+from typing import Any
+
+from .annotations import annotated_metadata, resolved_annotations
+from .exceptions import InvalidInputError, MissingInputError
+
+_REQUIRED_INPUTS = "__pyflowstep_inputs__"
+
+
+class _Required:
+    """The default of an input that has none: the caller must supply it."""
+
+    def __repr__(self) -> str:
+        return "<required>"
+
+
+_REQUIRED: Any = _Required()
+
+
+@dataclass(frozen=True, slots=True)
+class RunInput:
+    """The marker created by `Input`: "the caller of the flow supplies this parameter"."""
+
+    default: Any = _REQUIRED
+
+    @property
+    def required(self) -> bool:
+        """Whether the caller must supply the input."""
+        return self.default is _REQUIRED
+
+
+def Input(*, default: Any = _REQUIRED) -> Any:  # noqa: N802
+    """Mark a step parameter as supplied by the caller when the flow runs.
+
+    Use it as the default value of the parameter. The parameter stops being an
+    argument of the step; `flow(subject, name=value)` fills it for one run.
+
+    Args:
+        default: The value used when the caller supplies none, which makes the
+            input optional. Without it the input is required.
+
+    Example:
+    ```python
+    >>> from pyflowstep import step
+    >>> @step
+    ... def greet(names: list, user: str = Input(), mark: str = Input(default="!")) -> list:
+    ...     return [*names, user + mark]
+    >>> greet()([], user="Ada")
+    ['Ada!']
+    >>> greet()([], user="Ada", mark="?")
+    ['Ada?']
+    >>> sorted(greet().inputs)
+    ['user']
+
+    ```
+
+    """
+    return RunInput(default)
+
+
+def find_inputs(fn: Callable[..., Any]) -> dict[str, RunInput]:
+    """Return the parameters of `fn` whose default is `Input()`, by name.
+
+    Example:
+    ```python
+    >>> def add_tax(price: float, rate: float = Input(), bonus: float = Input(default=0.0)): ...
+    >>> {name: marker.required for name, marker in find_inputs(add_tax).items()}
+    {'rate': True, 'bonus': False}
+
+    ```
+
+    """
+    return {
+        name: parameter.default
+        for name, parameter in signature(fn).parameters.items()
+        if isinstance(parameter.default, RunInput)
+    }
+
+
+def step_inputs(fn: Callable[..., Any], step_name: str) -> dict[str, RunInput]:
+    """Return the inputs of a step function after validating them.
+
+    Raises:
+        InvalidInputError: If the subject or a positional-only parameter is
+            marked, or `Input()` is used inside `Annotated` instead of as a default.
+
+    """
+    inputs = find_inputs(fn)
+    parameters = signature(fn).parameters
+    annotations = resolved_annotations(fn)
+    subject = next(iter(parameters))
+
+    for name in parameters:
+        if any(isinstance(item, RunInput) for item in annotated_metadata(annotations.get(name))):
+            msg = (
+                f"Step '{step_name}' uses Input inside Annotated for '{name}'; write it as the "
+                f"default value, `{name}: <type> = Input()`, so type checkers see the parameter "
+                "as optional"
+            )
+            raise InvalidInputError(msg)
+
+    if subject in inputs:
+        msg = f"Step '{step_name}' cannot take its subject '{subject}' as a run input"
+        raise InvalidInputError(msg)
+
+    for name in inputs:
+        if parameters[name].kind is Parameter.POSITIONAL_ONLY:
+            msg = (
+                f"Step '{step_name}' cannot take positional-only parameter '{name}' as a run input"
+            )
+            raise InvalidInputError(msg)
+
+    return inputs
+
+
+def resolve_inputs(
+    given: Mapping[str, Any],
+    inputs: Mapping[str, RunInput],
+    step_name: str,
+) -> dict[str, Any]:
+    """Return the value of every input: the one `given`, or the default of an optional input.
+
+    Raises:
+        MissingInputError: If a required input was not given.
+
+    """
+    missing = [name for name, marker in inputs.items() if marker.required and name not in given]
+
+    if missing:
+        raise MissingInputError(_missing_message((name, step_name) for name in missing))
+
+    return {name: given.get(name, marker.default) for name, marker in inputs.items()}
+
+
+def mark_required_inputs(action: Callable[..., Any], inputs: Mapping[str, RunInput]) -> None:
+    """Record on a step action the inputs it requires, for `required_inputs` to read."""
+    required = frozenset(name for name, marker in inputs.items() if marker.required)
+    setattr(action, _REQUIRED_INPUTS, required)
+
+
+def required_inputs(action: Callable[..., Any]) -> frozenset[str]:
+    """Return the names of the inputs an action requires; plain callables require none.
+
+    Example:
+    ```python
+    >>> from pyflowstep import step
+    >>> @step
+    ... def add_tax(price: float, rate: float = Input(), bonus: float = Input(default=0.0)):
+    ...     return price * (1 + rate) + bonus
+    >>> required_inputs(add_tax().actions[0])
+    frozenset({'rate'})
+    >>> required_inputs(abs)
+    frozenset()
+
+    ```
+
+    """
+    return getattr(action, _REQUIRED_INPUTS, frozenset())
+
+
+def check_inputs(actions: Iterable[Callable[..., Any]], given: Mapping[str, Any]) -> None:
+    """Raise if `given` lacks an input one of `actions` requires.
+
+    Raises:
+        MissingInputError: Naming every missing input and the step that needs it.
+
+    """
+    missing = [
+        (name, getattr(action, "__name__", repr(action)))
+        for action in actions
+        for name in sorted(required_inputs(action) - given.keys())
+    ]
+
+    if missing:
+        raise MissingInputError(_missing_message(missing))
+
+
+def _missing_message(missing: Iterable[tuple[str, str]]) -> str:
+    steps_by_input: dict[str, list[str]] = {}
+
+    for name, step_name in missing:
+        steps = steps_by_input.setdefault(name, [])
+        if step_name not in steps:
+            steps.append(step_name)
+
+    details = ", ".join(
+        f"'{name}' for step{'s' if len(steps) > 1 else ''} {', '.join(map(repr, steps))}"
+        for name, steps in steps_by_input.items()
+    )
+    names = ", ".join(f"{name}=..." for name in steps_by_input)
+    plural = "s" if len(steps_by_input) > 1 else ""
+
+    return f"missing run input{plural} {details}; run the flow as flow(subject, {names})"

{pyflowstep-0.3.0 → pyflowstep-0.4.0}/src/pyflowstep/steps.py

@@ -15,8 +15,8 @@ Three markers can sit on a parameter:
   see `pyflowstep.parsers`.
 - `Depends(provider)` makes it no argument at all: it is injected when the flow
   runs, see `pyflowstep.dependencies`.
-- `Input[T]` makes it no argument either: the caller supplies it when it runs
-  the flow, see `pyflowstep.inputs`.
+- `Input()` as the default makes it no argument either: the caller supplies it
+  when it runs the flow, see `pyflowstep.inputs`.
 
 Naming steps is a registry concern, see `StepsRegistry`.
 """
@@ -29,7 +29,7 @@ from typing import Any, Concatenate
 from .dependencies import Dependency, resolve_dependencies, run_scope, step_dependencies
 from .exceptions import InvalidInputError, InvalidParserError, InvalidStepError, to_argument_error
 from .flow import Flow, action_name
-from .inputs import mark_required_inputs, resolve_inputs, step_inputs
+from .inputs import RunInput, mark_required_inputs, resolve_inputs, step_inputs
 from .parsers import find_parsers, parse_arguments
 
 type StepFn[T, **P] = Callable[Concatenate[T, P], T]
@@ -189,14 +189,14 @@ def _inject(
     bound: BoundArguments,
     *,
     dependencies: Mapping[str, Dependency],
-    inputs: Mapping[str, bool],
+    inputs: Mapping[str, RunInput],
 ) -> Callable[[Any], Any]:
     """Like `_call`, resolving the run inputs and the dependencies each time the step runs."""
 
     def call(subject: Any) -> Any:
         with run_scope() as run:
             resolved = {
-                **resolve_inputs(run, inputs, step_name),
+                **resolve_inputs(run.inputs, inputs, step_name),
                 **resolve_dependencies(run, dependencies),
             }
             arguments = BoundArguments(full_signature, {**bound.arguments, **resolved})  # type: ignore[arg-type]