pyflowstep 0.1.0__py3-none-any.whl

pyflowstep/processors.py

@@ -0,0 +1,159 @@
+"""Argument processors: transform raw step arguments before a step is built.
+
+Processors are most useful when a flow comes from JSON, where every value is a
+string, number, boolean, list, dict or null. They turn those raw values into
+the rich objects your step functions expect (dates, enums, decimals, ...).
+
+The `processors` option of a registry accepts:
+
+- `None`: arguments are passed through untouched (the default).
+- a callable: applied to every argument.
+- a mapping from parameter name to callable: applied to those arguments only.
+  The key `...` (Ellipsis) means "every argument not named here".
+
+    processors=float
+    processors={"timeout": float}
+    processors={"pumps": int, ...: str.strip}
+
+A processor for a parameter applies whether the value was passed positionally
+or by keyword. For `*args` it applies to each item, and for `**kwargs` each
+extra keyword name is looked up individually.
+"""
+
+from collections.abc import Callable, Mapping
+from inspect import BoundArguments, Parameter
+from types import EllipsisType
+from typing import Any
+
+from .exceptions import InvalidProcessorsError, ProcessArgumentError
+
+
+def processor_lookup(
+    processors: Callable[[Any], Any] | Mapping[str | EllipsisType, Callable[[Any], Any]],
+    parameters: Mapping[str, Parameter],
+    step_name: str,
+) -> Callable[[str], Callable[[Any], Any] | None]:
+    """Validate a `processors` option and turn it into a name-to-processor lookup.
+
+    Mapping keys are checked against `parameters`, so a typo fails at
+    registration instead of silently never running. Steps accepting `**kwargs`
+    allow any key.
+
+    Raises:
+        InvalidProcessorsError: If the option has the wrong type, a processor is
+            not callable, or a key names no parameter.
+
+    Example:
+    ```python
+    >>> from inspect import signature
+    >>> parameters = signature(lambda flavor, pumps: None).parameters
+    >>> lookup = processor_lookup({"pumps": int, ...: str.strip}, parameters, "add_syrup")
+    >>> lookup("pumps"), lookup("flavor")
+    (<class 'int'>, <method 'strip' of 'str' objects>)
+    >>> lookup = processor_lookup({"pumps": int}, parameters, "add_syrup")
+    >>> lookup("flavor") is None
+    True
+    >>> processor_lookup({"pums": int}, parameters, "add_syrup")
+    Traceback (most recent call last):
+    ...
+    pyflowstep.exceptions.InvalidProcessorsError: Processors of step 'add_syrup' name unknown ...
+
+    ```
+
+    """
+    if isinstance(processors, Mapping):
+        _validate_mapping(processors, parameters, step_name)
+        rest = processors.get(...)
+        return lambda name: processors.get(name, rest)
+
+    if callable(processors):
+        return lambda _: processors
+
+    msg = (
+        f"Processors of step '{step_name}' must be a callable or a mapping of "
+        f"parameter names to callables, got {processors!r}"
+    )
+    raise InvalidProcessorsError(msg)
+
+
+def process_arguments(
+    lookup: Callable[[str], Callable[[Any], Any] | None],
+    bound: BoundArguments,
+) -> BoundArguments:
+    """Return new bound arguments with every value run through its processor.
+
+    Values without a processor are kept as they are, and the original `bound`
+    object is left untouched.
+
+    Raises:
+        ProcessArgumentError: If any processor raises; the original exception is chained.
+
+    Example:
+    ```python
+    >>> from inspect import signature
+    >>> def brew(shots: int, *toppings: str, **extras: str): ...
+    >>> bound = signature(brew).bind("2", " foam ", " cocoa ", size="L", note=" hot ")
+    >>> lookup = {"shots": int, "toppings": str.strip, "size": str.lower}.get
+    >>> process_arguments(lookup, bound).arguments
+    {'shots': 2, 'toppings': ('foam', 'cocoa'), 'extras': {'size': 'l', 'note': ' hot '}}
+
+    ```
+
+    """
+    parameters = bound.signature.parameters
+    processed = {
+        name: _process_parameter(lookup, parameters[name], value)
+        for name, value in bound.arguments.items()
+    }
+    return BoundArguments(bound.signature, processed)  # type: ignore[arg-type]
+
+
+def _validate_mapping(
+    processors: Mapping[Any, Any],
+    parameters: Mapping[str, Parameter],
+    step_name: str,
+) -> None:
+    if not_callable := sorted(str(key) for key, fn in processors.items() if not callable(fn)):
+        msg = f"Processors of step '{step_name}' must be callables, not for {not_callable}"
+        raise InvalidProcessorsError(msg)
+
+    if any(parameter.kind is Parameter.VAR_KEYWORD for parameter in parameters.values()):
+        return
+
+    if unknown := sorted(map(str, processors.keys() - parameters.keys() - {...})):
+        msg = (
+            f"Processors of step '{step_name}' name unknown parameters {unknown}, "
+            f"available parameters: {', '.join(parameters) or '(none)'}"
+        )
+        raise InvalidProcessorsError(msg)
+
+
+def _process_parameter(
+    lookup: Callable[[str], Callable[[Any], Any] | None],
+    parameter: Parameter,
+    value: Any,
+) -> Any:
+    match parameter.kind:
+        case Parameter.VAR_POSITIONAL:
+            return tuple(_process_value(lookup, parameter.name, item) for item in value)
+        case Parameter.VAR_KEYWORD:
+            return {key: _process_value(lookup, key, item) for key, item in value.items()}
+        case _:
+            return _process_value(lookup, parameter.name, value)
+
+
+def _process_value(
+    lookup: Callable[[str], Callable[[Any], Any] | None],
+    name: str,
+    value: Any,
+) -> Any:
+    process = lookup(name)
+
+    if process is None:
+        return value
+
+    try:
+        return process(value)
+    except Exception as error:
+        msg = f"Argument '{name}' with value {value!r} failed to process, {error}"
+        raise ProcessArgumentError(msg) from error

pyflowstep/registry.py

@@ -0,0 +1,233 @@
+"""A registry that collects named steps for one subject type."""
+
+from collections.abc import Callable, Iterator, Mapping
+from functools import wraps
+from inspect import signature
+from types import EllipsisType, MappingProxyType
+from typing import Any
+
+from .exceptions import StepAlreadyRegisteredError, StepDoesNotExistError
+from .flow import Flow
+from .processors import process_arguments, processor_lookup
+from .steps import StepFactory, StepFn, TapFn, bind_arguments, step, tap
+from .validators import validate_step_name
+
+
+class StepsRegistry[T]:
+    """Collect named steps for subjects of type `T`.
+
+    A registry is the vocabulary of a flow language: its visible steps are what
+    a `FlowCompiler` understands and what `get_flow_json_schema` describes.
+    Hidden steps stay usable from Python but are invisible to both.
+
+    Example:
+    ```python
+    >>> from pyflowstep import FlowCompiler
+    >>> registry = StepsRegistry[list[str]]()
+    >>> @registry.step()
+    ... def push(stack: list[str], item: str) -> list[str]:
+    ...     '''Push an item on top of the stack.'''
+    ...     return [*stack, item]
+    >>> @registry.step(name="pop")
+    ... def pop_item(stack: list[str]) -> list[str]:
+    ...     return stack[:-1]
+    >>> sorted(registry.steps)
+    ['pop', 'push']
+    >>> (registry["push"]("a") >> registry["push"]("b") >> registry["pop"]())([])
+    ['a']
+    >>> FlowCompiler(registry.steps).compile([{"name": "push", "args": ["x"]}])([])
+    ['x']
+
+    ```
+
+    """
+
+    def __init__(self) -> None:
+        self._steps: dict[str, StepFactory[T, ...]] = {}
+        self._hidden: set[str] = set()
+
+    @property
+    def steps(self) -> Mapping[str, StepFactory[T, ...]]:
+        """A read-only mapping of every visible step, by name."""
+        return MappingProxyType(
+            {name: factory for name, factory in self._steps.items() if name not in self._hidden},
+        )
+
+    def __getitem__(self, name: str) -> StepFactory[T, ...]:
+        if name not in self.steps:
+            raise StepDoesNotExistError(name, self.steps.keys())
+        return self._steps[name]
+
+    def __contains__(self, name: object) -> bool:
+        return name in self.steps
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self.steps)
+
+    def __len__(self) -> int:
+        return len(self.steps)
+
+    def step[**P](
+        self,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        processors: (
+            Callable[[Any], Any] | Mapping[str | EllipsisType, Callable[[Any], Any]] | None
+        ) = None,
+        hidden: bool = False,
+    ) -> Callable[[StepFn[T, P]], StepFactory[T, P]]:
+        """Return a decorator registering a `(subject, ...) -> subject` step function.
+
+        Args:
+            name: The step name; defaults to the function name.
+            description: Overrides the function docstring (shown in the JSON schema).
+            processors (`((Any) -> Any) | Mapping[str | EllipsisType, (Any) -> Any] | None`):
+                How to transform arguments before the step is built: a callable for
+                every argument, or a mapping of parameter names to callables where
+                the key `...` covers the remaining arguments. `None` leaves them as-is.
+            hidden: Keep the step out of the registry lookups (`steps`, `[]`, `in`),
+                hence out of the compiler and the JSON schema. The returned
+                factory stays fully usable from Python.
+
+        """
+
+        def decorator(fn: StepFn[T, P]) -> StepFactory[T, P]:
+            return self.register(
+                fn,
+                name=name,
+                description=description,
+                processors=processors,
+                hidden=hidden,
+            )
+
+        return decorator
+
+    def tap[**P](
+        self,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        processors: (
+            Callable[[Any], Any] | Mapping[str | EllipsisType, Callable[[Any], Any]] | None
+        ) = None,
+        hidden: bool = False,
+    ) -> Callable[[TapFn[T, P]], StepFactory[T, P]]:
+        """Return a decorator registering a side-effect step whose return value is ignored.
+
+        See `pyflowstep.tap`.
+
+        Args:
+            name: The step name; defaults to the function name.
+            description: Overrides the function docstring (shown in the JSON schema).
+            processors (`((Any) -> Any) | Mapping[str | EllipsisType, (Any) -> Any] | None`):
+                How to transform arguments before the step is built: a callable for
+                every argument, or a mapping of parameter names to callables where
+                the key `...` covers the remaining arguments. `None` leaves them as-is.
+            hidden: Keep the step out of the registry lookups (`steps`, `[]`, `in`),
+                hence out of the compiler and the JSON schema. The returned
+                factory stays fully usable from Python.
+
+        """
+
+        def decorator(fn: TapFn[T, P]) -> StepFactory[T, P]:
+            return self.register(
+                fn,
+                name=name,
+                description=description,
+                processors=processors,
+                hidden=hidden,
+                passthrough=True,
+            )
+
+        return decorator
+
+    def register[**P](
+        self,
+        fn: TapFn[T, P],
+        /,
+        *,
+        name: str | None = None,
+        description: str | None = None,
+        processors: (
+            Callable[[Any], Any] | Mapping[str | EllipsisType, Callable[[Any], Any]] | None
+        ) = None,
+        hidden: bool = False,
+        passthrough: bool = False,
+    ) -> StepFactory[T, P]:
+        """Register `fn` as a step without decorator syntax and return its factory.
+
+        Useful for registering functions you do not own, or lambdas (with `name`).
+        The registered name is also the name shown in `repr` and error messages,
+        and processors run on every call of the returned factory, before the
+        arguments are bound to the step.
+
+        Args:
+            fn: The step function; its first positional parameter receives the subject.
+            name: The step name; defaults to the function name.
+            description: Overrides the function docstring (shown in the JSON schema).
+            processors (`((Any) -> Any) | Mapping[str | EllipsisType, (Any) -> Any] | None`):
+                How to transform arguments before the step is built: a callable for
+                every argument, or a mapping of parameter names to callables where
+                the key `...` covers the remaining arguments. `None` leaves them as-is.
+            hidden: Keep the step out of the registry lookups (`steps`, `[]`, `in`),
+                hence out of the compiler and the JSON schema. The returned
+                factory stays fully usable from Python.
+            passthrough: Ignore the return value of `fn` and pass the subject on
+                unchanged, like `tap`.
+
+        Raises:
+            StepAlreadyRegisteredError: If the name is already taken.
+            InvalidStepNameError: If the name is not a valid Python identifier.
+            InvalidStepError: If `fn` does not accept the subject positionally.
+            InvalidProcessorsError: If `processors` is malformed or names an unknown
+                parameter.
+
+        """
+        step_name = validate_step_name(name or getattr(fn, "__name__", ""))
+
+        if step_name in self._steps:
+            raise StepAlreadyRegisteredError(step_name)
+
+        make = tap if passthrough else step
+        factory = _with_processors(make(_renamed(fn, step_name)), processors)
+        factory.__doc__ = description or fn.__doc__
+
+        self._steps[step_name] = factory
+        if hidden:
+            self._hidden.add(step_name)
+
+        return factory
+
+
+def _renamed[F: Callable[..., Any]](fn: F, name: str) -> F:
+    """Return `fn` itself, or a thin wrapper exposing it under `name`."""
+    if getattr(fn, "__name__", None) == name:
+        return fn
+
+    @wraps(fn)
+    def renamed(*args: Any, **kwargs: Any) -> Any:
+        return fn(*args, **kwargs)
+
+    renamed.__name__ = renamed.__qualname__ = name
+    return renamed  # type: ignore[return-value]
+
+
+def _with_processors[T, **P](
+    factory: StepFactory[T, P],
+    processors: Callable[[Any], Any] | Mapping[str | EllipsisType, Callable[[Any], Any]] | None,
+) -> StepFactory[T, P]:
+    """Return a factory that processes its arguments before calling `factory`."""
+    if processors is None:
+        return factory
+
+    arguments_signature = signature(factory)
+    lookup = processor_lookup(processors, arguments_signature.parameters, factory.__name__)
+
+    @wraps(factory)
+    def processed(*args: P.args, **kwargs: P.kwargs) -> Flow[T]:
+        bound = bind_arguments(arguments_signature, factory.__name__, args, kwargs)
+        arguments = process_arguments(lookup, bound)
+        return factory(*arguments.args, **arguments.kwargs)
+
+    return processed

pyflowstep/steps.py

@@ -0,0 +1,158 @@
+"""Decorators that turn plain functions into step factories.
+
+A *step function* takes the flow subject first, followed by its own arguments:
+
+    def click(page: Page, selector: str) -> Page: ...
+
+Decorating it produces a *step factory*: calling the factory with the
+remaining arguments returns a single-step `Flow`, ready to be composed.
+
+    click("button#submit")  # -> Flow(click)
+
+Naming steps and processing their arguments are registry concerns, see
+`StepsRegistry`.
+"""
+
+from collections.abc import Callable
+from functools import wraps
+from inspect import BoundArguments, Parameter, Signature, signature
+from typing import Any, Concatenate
+
+from .exceptions import InvalidStepError, to_argument_error
+from .flow import Flow, action_name
+
+type StepFn[T, **P] = Callable[Concatenate[T, P], T]
+type TapFn[T, **P] = Callable[Concatenate[T, P], Any]
+type StepFactory[T, **P] = Callable[P, Flow[T]]
+
+
+def step[T, **P](fn: StepFn[T, P], /) -> StepFactory[T, P]:
+    """Turn a `(subject, *args, **kwargs) -> subject` function into a step factory.
+
+    Arguments are validated against the function signature as soon as the
+    factory is called, so mistakes surface while *building* a flow, not
+    halfway through running it.
+
+    Raises:
+        InvalidStepError: If `fn` does not accept the subject positionally.
+        ArgumentError: A subclass is raised by the factory for bad arguments.
+
+    Example:
+    ```python
+    >>> @step
+    ... def add(total: int, amount: int) -> int:
+    ...     return total + amount
+    >>> @step
+    ... def multiply(total: int, factor: int) -> int:
+    ...     return total * factor
+    >>> pipeline = add(2) >> multiply(10) >> add(amount=1)
+    >>> pipeline
+    Flow(add >> multiply >> add)
+    >>> pipeline(1)
+    31
+    >>> add()
+    Traceback (most recent call last):
+    ...
+    pyflowstep.exceptions.MissingArgumentError: missing a required argument: 'amount' for step 'add'
+
+    ```
+
+    """
+    return _make_step(fn, passthrough=False)
+
+
+def tap[T, **P](fn: TapFn[T, P], /) -> StepFactory[T, P]:
+    """Like `step`, for side-effect functions: the return value is ignored.
+
+    The subject passed in is handed, unchanged, to the next step. This removes
+    the `return page` boilerplate from steps that act on a mutable object.
+
+    Example:
+    ```python
+    >>> log: list[str] = []
+    >>> @tap
+    ... def record(value: int, label: str) -> None:
+    ...     log.append(f"{label}={value}")
+    >>> (record("before") >> Flow[int](lambda n: n * 10) >> record("after"))(4)
+    40
+    >>> log
+    ['before=4', 'after=40']
+
+    ```
+
+    """
+    return _make_step(fn, passthrough=True)
+
+
+def bind_arguments(
+    arguments_signature: Signature,
+    step_name: str,
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+) -> BoundArguments:
+    """Bind step arguments to a signature, raising the matching `ArgumentError`.
+
+    Example:
+    ```python
+    >>> from inspect import signature
+    >>> bind_arguments(signature(lambda selector: None), "click", ("#go",), {}).arguments
+    {'selector': '#go'}
+    >>> bind_arguments(signature(lambda selector: None), "click", (), {})
+    Traceback (most recent call last):
+    ...
+    pyflowstep.exceptions.MissingArgumentError: missing a required argument: 'selector'...
+
+    ```
+
+    """
+    try:
+        return arguments_signature.bind(*args, **kwargs)
+    except TypeError as error:
+        raise to_argument_error(error, step_name) from error
+
+
+def _make_step[T, **P](fn: TapFn[T, P], *, passthrough: bool) -> StepFactory[T, P]:
+    step_name = action_name(fn)
+    arguments_signature = _arguments_signature(fn, step_name)
+
+    @wraps(fn)
+    def factory(*args: P.args, **kwargs: P.kwargs) -> Flow[T]:
+        bound = bind_arguments(arguments_signature, step_name, args, kwargs)
+        return Flow(_make_action(fn, step_name, bound, passthrough=passthrough))
+
+    factory.__signature__ = arguments_signature  # type: ignore[attr-defined]
+    return factory
+
+
+def _arguments_signature(fn: Callable[..., Any], step_name: str) -> Signature:
+    """Return the signature of `fn` without its leading subject parameter."""
+    try:
+        subject, *parameters = signature(fn).parameters.values()
+    except ValueError as error:
+        msg = f"Step '{step_name}' must accept the flow subject as its first positional parameter"
+        raise InvalidStepError(msg) from error
+
+    if subject.kind not in (Parameter.POSITIONAL_ONLY, Parameter.POSITIONAL_OR_KEYWORD):
+        msg = (
+            f"Step '{step_name}' must accept the flow subject as its first positional parameter, "
+            f"got {subject.kind.description} parameter '{subject.name}'"
+        )
+        raise InvalidStepError(msg)
+
+    return Signature(parameters)
+
+
+def _make_action[T](
+    fn: Callable[..., Any],
+    step_name: str,
+    bound: BoundArguments,
+    *,
+    passthrough: bool,
+) -> Callable[[T], T]:
+    def run(subject: T) -> T:
+        result = fn(subject, *bound.args, **bound.kwargs)
+        return subject if passthrough else result
+
+    run.__name__ = run.__qualname__ = step_name
+    run.__doc__ = fn.__doc__
+    return run

pyflowstep/validators.py

@@ -0,0 +1,29 @@
+import re
+
+from .exceptions import InvalidStepNameError
+
+
+def validate_step_name(name: str) -> str:
+    """Return `name` unchanged if it is a valid ASCII Python identifier.
+
+    Example:
+    ```python
+    >>> validate_step_name("add_milk")
+    'add_milk'
+    >>> validate_step_name("add-milk")
+    Traceback (most recent call last):
+    ...
+    pyflowstep.exceptions.InvalidStepNameError: Invalid step name: 'add-milk', ...
+
+    ```
+
+    """
+    if not isinstance(name, str) or not re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$").match(name):
+        msg = (
+            f"Invalid step name: {name!r}, "
+            "you should follow the python variable naming convention: "
+            "name must start with a letter and can only contain letters, numbers and underscores"
+        )
+        raise InvalidStepNameError(msg)
+
+    return name