pyflowstep 0.3.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyflowstep
-Version: 0.3.0
+Version: 0.5.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
@@ -427,22 +427,24 @@ send_email("receipt")   # only `template` is an argument
 
 It works the same with the plain `@step` and `@tap` decorators; no registry is required.
 
-### Two ways to write it
+### Always the default value
 
-```python
-from typing import Annotated
+`Depends(...)` is written as the default value of the parameter, in steps and in providers. To name a dependency once and reuse it in many steps, keep the marker in a constant:
 
-# default value: quick, for a one-off
+```python
+# inline: quick, for a one-off
 def send_email(order: Order, template: str, mailer: Mailer = Depends(get_mailer)) -> None: ...
 
 
-# Annotated: name the dependency once, reuse it in many steps
-type MailerDep = Annotated[Mailer, Depends(get_mailer)]
+# a constant: name the dependency once, reuse it
+MAILER = Depends(get_mailer)
 
-def send_email(order: Order, template: str, mailer: MailerDep) -> None: ...
-def send_invoice(order: Order, mailer: MailerDep) -> None: ...
+def send_email(order: Order, template: str, mailer: Mailer = MAILER) -> None: ...
+def send_invoice(order: Order, mailer: Mailer = MAILER) -> None: ...
 ```
 
+It is never written inside `Annotated`. Only a default value tells a type checker that the parameter is not passed, so `send_email("receipt")` type-checks; `Annotated[Mailer, Depends(get_mailer)]` raises `InvalidDependencyError` when the step is created.
+
 ### 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.
@@ -466,16 +468,16 @@ def get_session() -> Iterator[Session]:
         session.close()
 
 
-type SessionDep = Annotated[Session, Depends(get_session)]
+SESSION = Depends(get_session)
 
 
 @steps.tap()
-def save(order: Order, session: SessionDep) -> None:
+def save(order: Order, session: Session = SESSION) -> None:
     session.add(order)
 
 
 @steps.tap()
-def audit(order: Order, action: str, session: SessionDep) -> None:
+def audit(order: Order, action: str, session: Session = SESSION) -> None:
     session.add(AuditRow(order.id, action))   # the same session `save` used
 
 
@@ -518,7 +520,7 @@ Keys are the original providers and values the providers to call instead. Nested
 ### Rules
 
 - **Invisible to JSON.** A dependency is absent from the JSON schema, cannot be parsed, and passing one raises `UnexpectedKeywordArgumentError` (or `TooManyArgumentsError`) when the flow is built.
-- **Declarations are checked early**, when the step is created, with `InvalidDependencyError`: a provider that is not callable, is circular, or has a required parameter that is not a dependency; a dependency on the subject, or on a positional-only, `*args` or `**kwargs` parameter.
+- **Declarations are checked early**, when the step is created, with `InvalidDependencyError`: a provider that is not callable, is circular, or has a required parameter that is not a dependency; a dependency on the subject or on a positional-only parameter; `Depends` written inside `Annotated`.
 - **Providers run late**, when the flow runs. An error inside a provider surfaces then, not at compile time.
 - A dependency is for an object the JSON must **not** choose. When the JSON should pick one by name (`"via": "email"`), use [`Parse`](#parsing-arguments) with a function that turns the name into the object.
 
@@ -531,11 +533,21 @@ extend-immutable-calls = ["pyflowstep.Depends"]
 
 See [`examples/dependencies.py`](examples/dependencies.py) for a complete flow with a mailer, a per-run session and a test override.
 
+### Upgrading from 0.4
+
+`Annotated[T, Depends(provider)]` is gone, for the same reason `Input[T]` went in 0.4: a type checker reported `send_email("receipt")` as missing its `mailer` argument. Move the marker to the default value, in steps and in providers:
+
+| 0.4                                                       | 0.5                                          |
+| --------------------------------------------------------- | -------------------------------------------- |
+| `mailer: Annotated[Mailer, Depends(get_mailer)]`          | `mailer: Mailer = Depends(get_mailer)`       |
+| `type MailerDep = Annotated[Mailer, Depends(get_mailer)]` | `MAILER = Depends(get_mailer)`               |
+| `mailer: MailerDep`                                       | `mailer: Mailer = MAILER`                    |
+
 ---
 
 ## 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 +556,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 +581,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 +597,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, 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 +624,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()`                   |
 
 ---
 
@@ -745,7 +775,7 @@ Runnable examples live in [`examples/`](examples):
   def send_email(order: Order, template: str, mailer: Mailer = Depends(get_mailer)) -> None: ...
 
   @fulfilment_steps.tap()
-  def save(order: Order, session: SessionDep) -> None: ...
+  def save(order: Order, session: Session = SESSION) -> None: ...
   ```
 
 ### Working with pyspecification and pyformula
@@ -804,7 +834,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.5.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
@@ -404,22 +404,24 @@ send_email("receipt")   # only `template` is an argument
 
 It works the same with the plain `@step` and `@tap` decorators; no registry is required.
 
-### Two ways to write it
+### Always the default value
 
-```python
-from typing import Annotated
+`Depends(...)` is written as the default value of the parameter, in steps and in providers. To name a dependency once and reuse it in many steps, keep the marker in a constant:
 
-# default value: quick, for a one-off
+```python
+# inline: quick, for a one-off
 def send_email(order: Order, template: str, mailer: Mailer = Depends(get_mailer)) -> None: ...
 
 
-# Annotated: name the dependency once, reuse it in many steps
-type MailerDep = Annotated[Mailer, Depends(get_mailer)]
+# a constant: name the dependency once, reuse it
+MAILER = Depends(get_mailer)
 
-def send_email(order: Order, template: str, mailer: MailerDep) -> None: ...
-def send_invoice(order: Order, mailer: MailerDep) -> None: ...
+def send_email(order: Order, template: str, mailer: Mailer = MAILER) -> None: ...
+def send_invoice(order: Order, mailer: Mailer = MAILER) -> None: ...
 ```
 
+It is never written inside `Annotated`. Only a default value tells a type checker that the parameter is not passed, so `send_email("receipt")` type-checks; `Annotated[Mailer, Depends(get_mailer)]` raises `InvalidDependencyError` when the step is created.
+
 ### 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.
@@ -443,16 +445,16 @@ def get_session() -> Iterator[Session]:
         session.close()
 
 
-type SessionDep = Annotated[Session, Depends(get_session)]
+SESSION = Depends(get_session)
 
 
 @steps.tap()
-def save(order: Order, session: SessionDep) -> None:
+def save(order: Order, session: Session = SESSION) -> None:
     session.add(order)
 
 
 @steps.tap()
-def audit(order: Order, action: str, session: SessionDep) -> None:
+def audit(order: Order, action: str, session: Session = SESSION) -> None:
     session.add(AuditRow(order.id, action))   # the same session `save` used
 
 
@@ -495,7 +497,7 @@ Keys are the original providers and values the providers to call instead. Nested
 ### Rules
 
 - **Invisible to JSON.** A dependency is absent from the JSON schema, cannot be parsed, and passing one raises `UnexpectedKeywordArgumentError` (or `TooManyArgumentsError`) when the flow is built.
-- **Declarations are checked early**, when the step is created, with `InvalidDependencyError`: a provider that is not callable, is circular, or has a required parameter that is not a dependency; a dependency on the subject, or on a positional-only, `*args` or `**kwargs` parameter.
+- **Declarations are checked early**, when the step is created, with `InvalidDependencyError`: a provider that is not callable, is circular, or has a required parameter that is not a dependency; a dependency on the subject or on a positional-only parameter; `Depends` written inside `Annotated`.
 - **Providers run late**, when the flow runs. An error inside a provider surfaces then, not at compile time.
 - A dependency is for an object the JSON must **not** choose. When the JSON should pick one by name (`"via": "email"`), use [`Parse`](#parsing-arguments) with a function that turns the name into the object.
 
@@ -508,11 +510,21 @@ extend-immutable-calls = ["pyflowstep.Depends"]
 
 See [`examples/dependencies.py`](examples/dependencies.py) for a complete flow with a mailer, a per-run session and a test override.
 
+### Upgrading from 0.4
+
+`Annotated[T, Depends(provider)]` is gone, for the same reason `Input[T]` went in 0.4: a type checker reported `send_email("receipt")` as missing its `mailer` argument. Move the marker to the default value, in steps and in providers:
+
+| 0.4                                                       | 0.5                                          |
+| --------------------------------------------------------- | -------------------------------------------- |
+| `mailer: Annotated[Mailer, Depends(get_mailer)]`          | `mailer: Mailer = Depends(get_mailer)`       |
+| `type MailerDep = Annotated[Mailer, Depends(get_mailer)]` | `MAILER = Depends(get_mailer)`               |
+| `mailer: MailerDep`                                       | `mailer: Mailer = MAILER`                    |
+
 ---
 
 ## 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 +533,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 +558,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 +574,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, 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 +601,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()`                   |
 
 ---
 
@@ -722,7 +752,7 @@ Runnable examples live in [`examples/`](examples):
   def send_email(order: Order, template: str, mailer: Mailer = Depends(get_mailer)) -> None: ...
 
   @fulfilment_steps.tap()
-  def save(order: Order, session: SessionDep) -> None: ...
+  def save(order: Order, session: Session = SESSION) -> None: ...
   ```
 
 ### Working with pyspecification and pyformula
@@ -781,7 +811,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.5.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyflowstep"
-version = "0.3.0"
+version = "0.5.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.5.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "pyflowstep"
-version = "0.3.0"
+version = "0.5.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.5.0}/src/pyflowstep/dependencies.py

@@ -35,11 +35,10 @@ from typing import Any
 
 from .annotations import annotated_metadata, resolved_annotations
 from .exceptions import InvalidDependencyError
+from .inputs import RunInput
 
 type Provider = Callable[..., Any]
 
-_UNSUPPORTED_KINDS = (Parameter.POSITIONAL_ONLY, Parameter.VAR_POSITIONAL, Parameter.VAR_KEYWORD)
-
 
 @dataclass(frozen=True, slots=True)
 class Dependency:
@@ -51,13 +50,16 @@ class Dependency:
 def Depends(provider: Provider, /) -> Any:  # noqa: N802
     """Mark a step (or provider) parameter as injected by calling `provider`.
 
-    Use it as a default value, or inside `Annotated` to name a dependency once
-    and reuse it:
+    Use it as the default value of the parameter. To name a dependency once and
+    reuse it, keep the marker in a constant:
 
         def send(order: Order, mailer: Mailer = Depends(get_mailer)) -> Order: ...
 
-        type MailerDep = Annotated[Mailer, Depends(get_mailer)]
-        def send(order: Order, mailer: MailerDep) -> Order: ...
+        MAILER = Depends(get_mailer)
+        def send(order: Order, mailer: Mailer = MAILER) -> Order: ...
+
+    It is never written inside `Annotated`: only a default value lets type
+    checkers see that the parameter is not passed, so `send()` type-checks.
 
     A provider is a function returning the object, or a generator function
     that yields it once and cleans up after the `yield`. Its own parameters may
@@ -89,15 +91,14 @@ def Depends(provider: Provider, /) -> Any:  # noqa: N802
 
 
 def find_dependencies(fn: Callable[..., Any]) -> dict[str, Dependency]:
-    """Return the parameters of `fn` marked with `Depends`, by name.
+    """Return the parameters of `fn` whose default is `Depends(...)`, by name.
 
     Example:
     ```python
     >>> def get_rate() -> float:
     ...     return 0.25
-    >>> from typing import Annotated
-    >>> type Rate = Annotated[float, Depends(get_rate)]
-    >>> def add_tax(price: float, label: str, rate: Rate, extra: float = Depends(get_rate)): ...
+    >>> RATE = Depends(get_rate)
+    >>> def add_tax(price: float, rate: float = RATE, extra: float = Depends(get_rate)): ...
     >>> list(find_dependencies(add_tax))
     ['rate', 'extra']
 
@@ -109,22 +110,24 @@ def find_dependencies(fn: Callable[..., Any]) -> dict[str, Dependency]:
     except ValueError:  # builtins without a signature take no dependencies
         return {}
 
-    annotations = resolved_annotations(fn)
-    markers = (
-        (name, _marker(parameter, annotations.get(name))) for name, parameter in parameters.items()
-    )
-    return {name: marker for name, marker in markers if marker is not None}
+    return {
+        name: parameter.default
+        for name, parameter in parameters.items()
+        if isinstance(parameter.default, Dependency)
+    }
 
 
 def step_dependencies(fn: Callable[..., Any], step_name: str) -> dict[str, Dependency]:
     """Return the dependencies of a step function after validating them.
 
     Raises:
-        InvalidDependencyError: If the subject is marked, a dependency sits on a
-            positional-only, `*args` or `**kwargs` parameter, or a provider is
+        InvalidDependencyError: If `Depends` is written inside `Annotated`, the
+            subject or a positional-only parameter is marked, or a provider is
             circular or has a required parameter that is not a dependency.
 
     """
+    _reject_annotated_markers(fn, f"Step '{step_name}'")
+
     dependencies = find_dependencies(fn)
     parameters = signature(fn).parameters
     subject = next(iter(parameters))
@@ -134,11 +137,8 @@ def step_dependencies(fn: Callable[..., Any], step_name: str) -> dict[str, Depen
         raise InvalidDependencyError(msg)
 
     for name, dependency in dependencies.items():
-        if parameters[name].kind in _UNSUPPORTED_KINDS:
-            msg = (
-                f"Step '{step_name}' cannot inject {parameters[name].kind.description} "
-                f"parameter '{name}'"
-            )
+        if parameters[name].kind is Parameter.POSITIONAL_ONLY:
+            msg = f"Step '{step_name}' cannot inject positional-only parameter '{name}'"
             raise InvalidDependencyError(msg)
         _validate_provider(dependency.provider, ())
 
@@ -268,14 +268,17 @@ def _provider_dependencies(provider: Provider) -> Mapping[str, Dependency]:
     return MappingProxyType(find_dependencies(provider))
 
 
-def _marker(parameter: Parameter, annotation: Any) -> Dependency | None:
-    if isinstance(parameter.default, Dependency):
-        return parameter.default
-
-    return next(
-        (item for item in annotated_metadata(annotation) if isinstance(item, Dependency)),
-        None,
-    )
+def _reject_annotated_markers(fn: Callable[..., Any], owner: str) -> None:
+    """Raise if a parameter of `fn` carries `Depends` inside `Annotated`."""
+    for name, annotation in resolved_annotations(fn).items():
+        for item in annotated_metadata(annotation):
+            if isinstance(item, Dependency):
+                msg = (
+                    f"{owner} uses Depends inside Annotated for '{name}'; write it as the "
+                    f"default value, `{name}: <type> = Depends({_name(item.provider)})`, so type "
+                    "checkers see the parameter as optional"
+                )
+                raise InvalidDependencyError(msg)
 
 
 def _validate_provider(provider: Provider, path: tuple[Provider, ...]) -> None:
@@ -289,16 +292,21 @@ def _validate_provider(provider: Provider, path: tuple[Provider, ...]) -> None:
     except ValueError:  # builtins without a signature are called with no arguments
         return
 
+    _reject_annotated_markers(provider, f"Provider '{_name(provider)}'")
     dependencies = find_dependencies(provider)
 
     for name, parameter in parameters.items():
-        if name in dependencies and parameter.kind in _UNSUPPORTED_KINDS:
+        if isinstance(parameter.default, RunInput):
             msg = (
-                f"Provider '{_name(provider)}' cannot inject {parameter.kind.description} "
-                f"parameter '{name}'"
+                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 is Parameter.POSITIONAL_ONLY:
+            msg = f"Provider '{_name(provider)}' cannot inject positional-only parameter '{name}'"
+            raise InvalidDependencyError(msg)
+
         if name in dependencies:
             _validate_provider(dependencies[name].provider, (*path, provider))
         elif _is_required(parameter):

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

@@ -45,15 +45,16 @@ class InvalidDependencyError(PyflowstepError, TypeError):
     """Raised when a `Depends(...)` declaration cannot work.
 
     For example a provider that is not callable, is circular, or has a required
-    parameter that is not itself a dependency.
+    parameter that is not itself a dependency, or a marker written inside
+    `Annotated` instead of as the default value.
     """
 
 
 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, or
+    written inside `Annotated` instead of as the default value.
     """
 
 

{pyflowstep-0.3.0 → pyflowstep-0.5.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.5.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.5.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`.
 """
@@ -27,9 +27,9 @@ from inspect import BoundArguments, Parameter, Signature, signature
 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 .exceptions import 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]
@@ -130,10 +130,6 @@ def _make_step[T, **P](fn: TapFn[T, P], *, passthrough: bool) -> StepFactory[T,
     parsers = find_parsers(fn, step_name)
     injected = dependencies.keys() | inputs.keys()
 
-    if both := sorted(dependencies.keys() & inputs.keys()):
-        msg = f"Step '{step_name}' cannot take {both} both as a dependency and as a run input"
-        raise InvalidInputError(msg)
-
     if both := sorted(parsers.keys() & injected):
         msg = f"Step '{step_name}' cannot both parse and inject {both}: nothing is passed for them"
         raise InvalidParserError(msg)
@@ -189,14 +185,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]