pyflowstep 0.1.0__py3-none-any.whl

pyflowstep/__init__.py

@@ -0,0 +1,77 @@
+"""Compose functions into readable, reusable, JSON-definable flows.
+
+`pyflowstep` is a functional replacement for the fluent-interface (method chaining)
+pattern. Instead of adding chainable methods to a class, you write small step
+functions and compose them with `>>`:
+
+```python
+>>> from pyflowstep import step
+>>> @step
+... def add(total: int, amount: int) -> int:
+...     return total + amount
+>>> @step
+... def double(total: int) -> int:
+...     return total * 2
+>>> (add(3) >> double() >> add(1))(0)
+7
+
+```
+
+Steps collected in a `StepsRegistry` can also be described as JSON
+(`get_flow_json_schema`) and compiled from JSON (`FlowCompiler`).
+"""
+
+from .compilers import FlowCompiler, FlowDefinition, StepDict, validate_step_dict
+from .exceptions import (
+    ArgumentError,
+    InvalidFlowDefinitionError,
+    InvalidProcessorsError,
+    InvalidStepError,
+    InvalidStepNameError,
+    MissingArgumentError,
+    MultipleValuesArgumentError,
+    PositionalOnlyArgumentError,
+    ProcessArgumentError,
+    PyflowstepError,
+    StepAlreadyRegisteredError,
+    StepDoesNotExistError,
+    TooManyArgumentsError,
+    UnexpectedKeywordArgumentError,
+)
+from .flow import Action, Flow, compose
+from .json_schema import get_flow_json_schema, get_json_schema, get_step_json_schema
+from .registry import StepsRegistry
+from .steps import StepFactory, StepFn, TapFn, step, tap
+
+__all__ = [
+    "Action",
+    "ArgumentError",
+    "Flow",
+    "FlowCompiler",
+    "FlowDefinition",
+    "InvalidFlowDefinitionError",
+    "InvalidProcessorsError",
+    "InvalidStepError",
+    "InvalidStepNameError",
+    "MissingArgumentError",
+    "MultipleValuesArgumentError",
+    "PositionalOnlyArgumentError",
+    "ProcessArgumentError",
+    "PyflowstepError",
+    "StepAlreadyRegisteredError",
+    "StepDict",
+    "StepDoesNotExistError",
+    "StepFactory",
+    "StepFn",
+    "StepsRegistry",
+    "TapFn",
+    "TooManyArgumentsError",
+    "UnexpectedKeywordArgumentError",
+    "compose",
+    "get_flow_json_schema",
+    "get_json_schema",
+    "get_step_json_schema",
+    "step",
+    "tap",
+    "validate_step_dict",
+]

pyflowstep/compilers.py

@@ -0,0 +1,147 @@
+"""Compile flow definitions (lists of step dictionaries, or JSON) into `Flow` objects."""
+
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any, NotRequired, TypedDict
+
+from .exceptions import InvalidFlowDefinitionError, PyflowstepError, StepDoesNotExistError
+from .flow import Flow, compose
+
+_STEP_DICT_SHAPE = '{"name": str, "args"?: list, "kwargs"?: dict[str, Any]}'
+
+
+class StepDict(TypedDict):
+    """The dictionary form of one step.
+
+    Only `name` is required; `args` defaults to `[]` and `kwargs` to `{}`.
+
+        {"name": "fill", "args": ["input[name=q]"], "kwargs": {"value": "pyflowstep"}}
+    """
+
+    name: str
+    args: NotRequired[list[Any]]
+    kwargs: NotRequired[dict[str, Any]]
+
+
+type FlowDefinition = Sequence[StepDict]
+
+
+class FlowCompiler[T]:
+    """Compile a flow definition into a runnable `Flow`.
+
+    A flow definition is a list of `StepDict` objects, one per step, run in
+    order. Every problem is reported while compiling, before anything runs:
+    malformed dictionaries, unknown step names, bad arguments and failing
+    processors. Each error carries a note with its JSON path, e.g. `at $[2]`.
+
+    The compiler works on already-parsed data (lists and dicts), so where the
+    definition comes from (a JSON file, a database, an API) is up to you.
+
+    Args:
+        steps: A mapping from step name to step factory, typically
+            `registry.steps`.
+
+    Example:
+    ```python
+    >>> from pyflowstep import step
+    >>> @step
+    ... def add(total: int, amount: int) -> int:
+    ...     return total + amount
+    >>> @step
+    ... def multiply(total: int, factor: int) -> int:
+    ...     return total * factor
+    >>> compiler = FlowCompiler[int]({"add": add, "multiply": multiply})
+    >>> flow = compiler.compile([
+    ...     {"name": "add", "args": [2]},
+    ...     {"name": "multiply", "kwargs": {"factor": 10}},
+    ... ])
+    >>> flow
+    Flow(add >> multiply)
+    >>> flow(1)
+    30
+
+    ```
+
+    """
+
+    def __init__(self, steps: Mapping[str, Callable[..., Flow[T]]], /) -> None:
+        self._steps = steps
+
+    def compile(self, definition: FlowDefinition) -> Flow[T]:
+        """Compile a list of step dictionaries into a single flat `Flow`."""
+        if isinstance(definition, str | bytes | Mapping) or not isinstance(definition, Sequence):
+            raise InvalidFlowDefinitionError(_invalid_definition_message(definition))
+
+        return compose(
+            *(self._compile_step(item, f"$[{index}]") for index, item in enumerate(definition)),
+        )
+
+    def _compile_step(self, item: Any, path: str) -> Flow[T]:
+        try:
+            step_dict = validate_step_dict(item, path)
+            factory = self._find_step(step_dict["name"])
+            return factory(*step_dict.get("args", []), **step_dict.get("kwargs", {}))
+        except PyflowstepError as error:
+            error.add_note(f"at {path}")
+            raise
+
+    def _find_step(self, name: str) -> Callable[..., Flow[T]]:
+        if name not in self._steps:
+            raise StepDoesNotExistError(name, self._steps.keys())
+        return self._steps[name]
+
+
+def validate_step_dict(item: Any, path: str = "$") -> StepDict:
+    """Return `item` if it is a well-formed `StepDict`, raise otherwise.
+
+    Raises:
+        InvalidFlowDefinitionError: With a message explaining what is wrong at `path`.
+
+    Example:
+    ```python
+    >>> validate_step_dict({"name": "click", "args": ["#go"]})
+    {'name': 'click', 'args': ['#go']}
+    >>> validate_step_dict({"name": "click", "selector": "#go"}, "$[0]")
+    Traceback (most recent call last):
+    ...
+    pyflowstep.exceptions.InvalidFlowDefinitionError: Invalid step at $[0]: unknown keys ...
+
+    ```
+
+    """
+    problem = _step_dict_problem(item)
+
+    if problem is not None:
+        msg = f"Invalid step at {path}: {problem}, expected {_STEP_DICT_SHAPE}, received {item!r}"
+        raise InvalidFlowDefinitionError(msg)
+
+    return item
+
+
+def _step_dict_problem(item: Any) -> str | None:
+    """Describe the first thing wrong with a step dictionary, or `None` if it is valid."""
+    if not isinstance(item, Mapping):
+        return "a step must be an object"
+
+    if unknown_keys := item.keys() - frozenset({"name", "args", "kwargs"}):
+        return f"unknown keys {sorted(map(str, unknown_keys))}"
+
+    if not isinstance(item.get("name"), str):
+        return "'name' is required and must be a string"
+
+    if not isinstance(item.get("args", []), list):
+        return "'args' must be a list"
+
+    if not isinstance(item.get("kwargs", {}), Mapping):
+        return "'kwargs' must be an object"
+
+    if not all(isinstance(key, str) for key in item.get("kwargs", {})):
+        return "'kwargs' keys must be strings"
+
+    return None
+
+
+def _invalid_definition_message(definition: Any) -> str:
+    return (
+        "Invalid flow definition at $: expected a list of steps like "
+        f"[{_STEP_DICT_SHAPE}, ...], received {definition!r}"
+    )

pyflowstep/exceptions.py

@@ -0,0 +1,116 @@
+"""Exceptions raised by pyflowstep.
+
+Every exception derives from `PyflowstepError`, so callers can catch the whole
+family at once. Argument errors additionally derive from `TypeError`, and
+definition errors from `ValueError`, to stay compatible with code that expects
+the built-in exception types.
+"""
+
+import re
+from collections.abc import Iterable
+
+
+class PyflowstepError(Exception):
+    """Base class for every exception raised by pyflowstep."""
+
+
+class StepAlreadyRegisteredError(PyflowstepError):
+    """Raised when a step name is registered twice in the same registry."""
+
+    def __init__(self, name: str) -> None:
+        super().__init__(f"Step '{name}' is already registered.")
+
+
+class StepDoesNotExistError(PyflowstepError, LookupError):
+    """Raised when a step name cannot be found in a registry or a compiler."""
+
+    def __init__(self, name: str, available_steps: Iterable[str] | None = None) -> None:
+        msg = f"Step '{name}' does not exist."
+
+        if available_steps is not None:
+            msg += f" Available steps: {', '.join(sorted(available_steps)) or '(none)'}"
+
+        super().__init__(msg)
+
+
+class InvalidStepError(PyflowstepError, TypeError):
+    """Raised when a function cannot be turned into a step.
+
+    A step function must accept the flow subject as its first positional
+    parameter, for example `def click(page: Page, selector: str) -> Page`.
+    """
+
+
+class InvalidProcessorsError(PyflowstepError, TypeError):
+    """Raised when the `processors` option of a step is malformed.
+
+    It must be a callable, or a mapping of parameter names (or `...`) to
+    callables, and every name must be a parameter of the step.
+    """
+
+
+class InvalidStepNameError(PyflowstepError, ValueError):
+    """Raised when a step name does not follow the Python identifier convention."""
+
+
+class InvalidFlowDefinitionError(PyflowstepError, ValueError):
+    """Raised when a flow definition (a list of step dictionaries) is malformed."""
+
+
+class ArgumentError(PyflowstepError, TypeError):
+    """Base class for errors caused by the arguments given to a step."""
+
+
+class MissingArgumentError(ArgumentError):
+    """Raised when a required step argument is missing."""
+
+
+class TooManyArgumentsError(ArgumentError):
+    """Raised when a step receives more positional arguments than it accepts."""
+
+
+class UnexpectedKeywordArgumentError(ArgumentError):
+    """Raised when a step receives a keyword argument it does not declare."""
+
+
+class MultipleValuesArgumentError(ArgumentError):
+    """Raised when a step argument is given both positionally and by keyword."""
+
+
+class PositionalOnlyArgumentError(ArgumentError):
+    """Raised when a positional-only step argument is passed as a keyword."""
+
+
+class ProcessArgumentError(ArgumentError):
+    """Raised when a processor fails to transform a step argument."""
+
+
+_ARGUMENT_ERROR_PATTERNS: tuple[tuple[str, type[ArgumentError]], ...] = (
+    (r"positional.only.*passed as (a )?keyword", PositionalOnlyArgumentError),
+    (r"missing a required", MissingArgumentError),
+    (r"too many positional arguments", TooManyArgumentsError),
+    (r"got an unexpected keyword argument", UnexpectedKeywordArgumentError),
+    (r"multiple values for argument", MultipleValuesArgumentError),
+)
+
+
+def to_argument_error(error: TypeError, step_name: str) -> ArgumentError:
+    """Translate a `Signature.bind` `TypeError` into the matching `ArgumentError`.
+
+    Example:
+    ```python
+    >>> error = to_argument_error(TypeError("too many positional arguments"), "click")
+    >>> type(error).__name__
+    'TooManyArgumentsError'
+    >>> str(error)
+    "too many positional arguments for step 'click'"
+
+    ```
+
+    """
+    message = str(error)
+    error_type = next(
+        (error for pattern, error in _ARGUMENT_ERROR_PATTERNS if re.search(pattern, message)),
+        ArgumentError,
+    )
+    return error_type(f"{message} for step '{step_name}'")

pyflowstep/flow.py

@@ -0,0 +1,116 @@
+"""The `Flow` type: an immutable, composable pipeline of `T -> T` actions."""
+
+from collections.abc import Callable, Iterator
+from functools import reduce
+from typing import Any
+
+type Action[T] = Callable[[T], T]
+
+
+class Flow[T]:
+    """An immutable sequence of actions applied, in order, to a single subject.
+
+    A flow is a callable `T -> T`. Calling it threads the subject through every
+    action: the output of one action is the input of the next. Flows compose
+    with `>>`, which always returns a *new* flow and never mutates its operands.
+
+    Args:
+        *actions: The callables to run, in order. Each one takes the subject and
+            returns the (possibly new) subject. With no actions the flow is the
+            identity.
+
+    Example:
+    ```python
+    >>> increment = Flow[int](lambda n: n + 1)
+    >>> double = Flow[int](lambda n: n * 2)
+    >>> pipeline = increment >> double >> increment
+    >>> pipeline(3)
+    9
+    >>> len(pipeline)
+    3
+    >>> Flow[int]()(7)  # an empty flow is the identity
+    7
+
+    ```
+
+    """
+
+    __slots__ = ("_actions",)
+
+    def __init__(self, *actions: Action[T]) -> None:
+        self._actions = actions
+
+    @property
+    def actions(self) -> tuple[Action[T], ...]:
+        """The actions of the flow, in execution order."""
+        return self._actions
+
+    def __call__(self, obj: T) -> T:
+        return reduce(lambda obj, action: action(obj), self._actions, obj)
+
+    def __rshift__(self, other: Action[T]) -> "Flow[T]":
+        if not callable(other):
+            return NotImplemented
+        return Flow(*self._actions, *_actions_of(other))
+
+    def __rrshift__(self, other: Action[T]) -> "Flow[T]":
+        if not callable(other):
+            return NotImplemented
+        return Flow(*_actions_of(other), *self._actions)
+
+    def __len__(self) -> int:
+        return len(self._actions)
+
+    def __iter__(self) -> Iterator[Action[T]]:
+        return iter(self._actions)
+
+    def __bool__(self) -> bool:
+        return True
+
+    def __repr__(self) -> str:
+        return f"Flow({' >> '.join(map(action_name, self._actions))})"
+
+
+def compose[T](*actions: Action[T]) -> Flow[T]:
+    """Combine actions and flows into one flat `Flow`, left to right.
+
+    `compose(a, b, c)` is equivalent to `Flow() >> a >> b >> c`. Nested flows
+    are flattened, so the result lists every underlying step.
+
+    Example:
+    ```python
+    >>> add_one = Flow[int](lambda n: n + 1)
+    >>> square = lambda n: n * n
+    >>> compose(add_one, square, add_one)(2)
+    10
+    >>> compose()(5)
+    5
+
+    ```
+
+    """
+    return reduce(Flow.__rshift__, actions, Flow[T]())
+
+
+def action_name(action: Callable[..., Any]) -> str:
+    """Return a human-readable name for an action, used by `repr` and error notes.
+
+    Example:
+    ```python
+    >>> action_name(len)
+    'len'
+    >>> action_name(lambda x: x)
+    '<lambda>'
+    >>> action_name(Flow(len, abs))
+    'Flow(len >> abs)'
+
+    ```
+
+    """
+    if isinstance(action, Flow):
+        return repr(action)
+    return getattr(action, "__name__", None) or repr(action)
+
+
+def _actions_of[T](obj: Action[T] | Flow[T]) -> tuple[Action[T], ...]:
+    return obj.actions if isinstance(obj, Flow) else (obj,)

pyflowstep/json_schema.py

@@ -0,0 +1,244 @@
+"""Generate JSON Schemas describing steps and whole flow definitions.
+
+The schemas describe the exact shape accepted by `FlowCompiler`, so they can be
+handed to a form builder, a validator, or an LLM that writes flows as JSON.
+"""
+
+from collections.abc import Callable, Mapping
+from datetime import date, datetime, time
+from decimal import Decimal
+from enum import Enum
+from inspect import Parameter, get_annotations, signature
+from types import NoneType, UnionType
+from typing import (
+    Annotated,
+    Any,
+    Literal,
+    NotRequired,
+    Required,
+    TypeAliasType,
+    Union,
+    get_args,
+    get_origin,
+    is_typeddict,
+)
+from uuid import UUID
+
+JSON_SCHEMA_DIALECT = "https://json-schema.org/draft/2020-12/schema"
+
+_SCALAR_SCHEMAS: dict[Any, dict[str, Any]] = {
+    str: {"type": "string"},
+    int: {"type": "integer"},
+    float: {"type": "number"},
+    Decimal: {"type": "number"},
+    bool: {"type": "boolean"},
+    None: {"type": "null"},
+    NoneType: {"type": "null"},
+    datetime: {"type": "string", "format": "date-time"},
+    date: {"type": "string", "format": "date"},
+    time: {"type": "string", "format": "time"},
+    UUID: {"type": "string", "format": "uuid"},
+}
+
+_ARRAY_TYPES = (list, tuple, set, frozenset)
+_WRAPPER_ORIGINS = (Annotated, Required, NotRequired)
+_POSITIONAL_KINDS = (Parameter.POSITIONAL_ONLY, Parameter.POSITIONAL_OR_KEYWORD)
+_KEYWORD_KINDS = (Parameter.POSITIONAL_OR_KEYWORD, Parameter.KEYWORD_ONLY)
+
+
+def get_json_schema(annotation: Any) -> dict[str, Any]:
+    """Return the JSON Schema of a Python type annotation.
+
+    Unknown or unannotated types map to `{}`, which accepts any value.
+
+    Example:
+    ```python
+    >>> get_json_schema(int)
+    {'type': 'integer'}
+    >>> get_json_schema(list[str])
+    {'type': 'array', 'items': {'type': 'string'}}
+    >>> get_json_schema(Literal["oat", "soy"])
+    {'enum': ['oat', 'soy'], 'type': 'string'}
+    >>> get_json_schema(int | None)
+    {'anyOf': [{'type': 'integer'}, {'type': 'null'}]}
+
+    ```
+
+    """
+    origin = get_origin(annotation)
+
+    if is_typeddict(annotation):
+        return _typeddict_schema(annotation)
+
+    if isinstance(annotation, type) and issubclass(annotation, Enum):
+        return _enum_schema([member.value for member in annotation])
+
+    if isinstance(annotation, TypeAliasType):
+        return get_json_schema(annotation.__value__)
+
+    if origin in _WRAPPER_ORIGINS:
+        return get_json_schema(get_args(annotation)[0])
+
+    if origin is Literal:
+        return _enum_schema(list(get_args(annotation)))
+
+    if origin in (Union, UnionType):
+        return {"anyOf": [get_json_schema(arg) for arg in get_args(annotation)]}
+
+    if (origin or annotation) in _ARRAY_TYPES:
+        return _array_schema(get_args(annotation))
+
+    if (origin or annotation) is dict:
+        return _dict_schema(get_args(annotation))
+
+    return dict(_SCALAR_SCHEMAS.get(annotation, {}))
+
+
+def get_step_json_schema(name: str, step: Callable[..., Any]) -> dict[str, Any]:
+    """Return the JSON Schema of one step dictionary, e.g. `{"name": ..., "args": [...]}`.
+
+    `step` is a step factory (as returned by `step`, `tap` or a registry), whose
+    signature excludes the subject. Positional parameters are described under
+    `args` (via `prefixItems`), keyword-capable parameters under `kwargs`, and
+    the step docstring becomes the description.
+
+    Example:
+    ```python
+    >>> from pyflowstep import step
+    >>> @step
+    ... def fill(page, selector: str, value: str = "") -> object:
+    ...     '''Type a value into a field.'''
+    ...     return page
+    >>> schema = get_step_json_schema("fill", fill)
+    >>> schema["properties"]["name"]
+    {'const': 'fill'}
+    >>> schema["properties"]["args"]["prefixItems"]
+    [{'type': 'string'}, {'type': 'string', 'default': ''}]
+    >>> schema["description"]
+    'Type a value into a field.'
+
+    ```
+
+    """
+    parameters = list(signature(step).parameters.values())
+    annotations = _resolved_annotations(step)
+
+    def parameter_schema(parameter: Parameter) -> dict[str, Any]:
+        schema = get_json_schema(annotations.get(parameter.name, Any))
+        if parameter.default is not Parameter.empty and _is_json_value(parameter.default):
+            schema["default"] = parameter.default
+        return schema
+
+    schema: dict[str, Any] = {
+        "type": "object",
+        "properties": {
+            "name": {"const": name},
+            "args": _args_schema(parameters, parameter_schema),
+            "kwargs": _kwargs_schema(parameters, parameter_schema),
+        },
+        "required": ["name"],
+        "additionalProperties": False,
+    }
+
+    if step.__doc__:
+        schema["description"] = step.__doc__.strip()
+
+    return schema
+
+
+def get_flow_json_schema(steps: Mapping[str, Callable[..., Any]]) -> dict[str, Any]:
+    """Return the JSON Schema of a whole flow definition: a list of step dictionaries.
+
+    Pass `registry.steps` (or any name-to-step mapping given to `FlowCompiler`).
+
+    Example:
+    ```python
+    >>> from pyflowstep import step
+    >>> @step
+    ... def wait(page, selector: str) -> object:
+    ...     return page
+    >>> schema = get_flow_json_schema({"wait": wait})
+    >>> schema["type"], len(schema["items"]["oneOf"])
+    ('array', 1)
+
+    ```
+
+    """
+    return {
+        "$schema": JSON_SCHEMA_DIALECT,
+        "type": "array",
+        "items": {"oneOf": [get_step_json_schema(name, step) for name, step in steps.items()]},
+    }
+
+
+def _args_schema(
+    parameters: list[Parameter],
+    parameter_schema: Callable[[Parameter], dict[str, Any]],
+) -> dict[str, Any]:
+    positional = [parameter for parameter in parameters if parameter.kind in _POSITIONAL_KINDS]
+    var_positional = next(
+        (parameter for parameter in parameters if parameter.kind is Parameter.VAR_POSITIONAL),
+        None,
+    )
+    return {
+        "type": "array",
+        "prefixItems": [parameter_schema(parameter) for parameter in positional],
+        "items": parameter_schema(var_positional) if var_positional else False,
+    }
+
+
+def _kwargs_schema(
+    parameters: list[Parameter],
+    parameter_schema: Callable[[Parameter], dict[str, Any]],
+) -> dict[str, Any]:
+    keyword = [parameter for parameter in parameters if parameter.kind in _KEYWORD_KINDS]
+    var_keyword = next(
+        (parameter for parameter in parameters if parameter.kind is Parameter.VAR_KEYWORD),
+        None,
+    )
+    return {
+        "type": "object",
+        "properties": {parameter.name: parameter_schema(parameter) for parameter in keyword},
+        "required": [
+            parameter.name
+            for parameter in keyword
+            if parameter.kind is Parameter.KEYWORD_ONLY and parameter.default is Parameter.empty
+        ],
+        "additionalProperties": parameter_schema(var_keyword) if var_keyword else False,
+    }
+
+
+def _enum_schema(values: list[Any]) -> dict[str, Any]:
+    schema: dict[str, Any] = {"enum": values}
+    if values and all(isinstance(value, str) for value in values):
+        schema["type"] = "string"
+    return schema
+
+
+def _array_schema(args: tuple[Any, ...]) -> dict[str, Any]:
+    return {"type": "array", "items": get_json_schema(args[0]) if args else {}}
+
+
+def _dict_schema(args: tuple[Any, ...]) -> dict[str, Any]:
+    return {"type": "object", "additionalProperties": get_json_schema(args[1]) if args else {}}
+
+
+def _typeddict_schema(annotation: Any) -> dict[str, Any]:
+    annotations = get_annotations(annotation)
+    return {
+        "type": "object",
+        "properties": {name: get_json_schema(typ) for name, typ in annotations.items()},
+        "required": [name for name in annotations if name in annotation.__required_keys__],
+    }
+
+
+def _resolved_annotations(fn: Callable[..., Any]) -> dict[str, Any]:
+    """Evaluate string annotations when possible, fall back to the raw ones."""
+    try:
+        return get_annotations(fn, eval_str=True)
+    except NameError:
+        return get_annotations(fn)
+
+
+def _is_json_value(value: Any) -> bool:
+    return value is None or isinstance(value, str | int | float | bool | list | dict)