pyflowstep 0.4.0__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pyflowstep
-Version: 0.4.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
@@ -427,23 +427,23 @@ 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: ...
 ```
 
-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.
+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
 
@@ -468,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
 
 
@@ -520,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.
 
@@ -533,6 +533,16 @@ 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
@@ -590,7 +600,7 @@ flow(page, credentials=credentials)
 - **`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.
+- **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:
 
@@ -765,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

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

@@ -404,23 +404,23 @@ 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: ...
 ```
 
-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.
+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
 
@@ -445,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
 
 
@@ -497,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.
 
@@ -510,6 +510,16 @@ 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
@@ -567,7 +577,7 @@ flow(page, credentials=credentials)
 - **`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.
+- **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:
 
@@ -742,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

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

@@ -1,6 +1,6 @@
 [project]
 name = "pyflowstep"
-version = "0.4.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"

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

@@ -1,6 +1,6 @@
 [project]
 name = "pyflowstep"
-version = "0.4.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 = [

{pyflowstep-0.4.0 → pyflowstep-0.5.0}/src/pyflowstep/dependencies.py

@@ -39,8 +39,6 @@ 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:
@@ -52,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
@@ -90,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']
 
@@ -110,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))
@@ -135,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, ())
 
@@ -269,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:
@@ -290,6 +292,7 @@ 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():
@@ -300,11 +303,8 @@ def _validate_provider(provider: Provider, path: tuple[Provider, ...]) -> None:
             )
             raise InvalidDependencyError(msg)
 
-        if name in dependencies and parameter.kind in _UNSUPPORTED_KINDS:
-            msg = (
-                f"Provider '{_name(provider)}' cannot inject {parameter.kind.description} "
-                f"parameter '{name}'"
-            )
+        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:

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

@@ -45,16 +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.
 
-    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.
+    For example an input on the subject, on a positional-only parameter, or
+    written inside `Annotated` instead of as the default value.
     """
 
 

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

@@ -27,7 +27,7 @@ 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 RunInput, mark_required_inputs, resolve_inputs, step_inputs
 from .parsers import find_parsers, parse_arguments
@@ -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)