stageflow-framework 0.12.0__tar.gz → 0.13.0__tar.gz

{stageflow_framework-0.12.0/stageflow_framework.egg-info → stageflow_framework-0.13.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stageflow-framework
-Version: 0.12.0
+Version: 0.13.0
 Summary: StageFlow: pipeline framework for stages
 Author-email: лень <pzrnqt1vrss@protonmail.com>
 License-Expression: MIT
@@ -29,6 +29,8 @@ Requires-Dist: twine; extra == "dev"
 Provides-Extra: docs
 Requires-Dist: mkdocs-material; extra == "docs"
 Requires-Dist: mkdocs-static-i18n; extra == "docs"
+Provides-Extra: i18n
+Requires-Dist: babel; extra == "i18n"
 Dynamic: license-file
 
 <div align="center">
@@ -129,6 +131,7 @@ against it, so a wrong argument name is an error before anything runs.
 | **Budgets that hold** | counters and gauges for time, steps, tokens, fan-out and depth; a ceiling a `try` block cannot catch |
 | **Gradual typing** | declare the variables that matter; checked at validation and on every write |
 | **Step debugging** | stop between nodes, read and edit the frame, replay the event stream |
+| **Answers in a language** | a locale per request, not per process, for the framework's own messages; stage specs carry every language at once and let the client choose |
 
 ## Documentation
 
@@ -144,6 +147,7 @@ The reference covers the rest:
 [Policy](https://leo-need-more-coffee.github.io/stageflow/policy/) ·
 [Limits](https://leo-need-more-coffee.github.io/stageflow/limits/) ·
 [Variable typing](https://leo-need-more-coffee.github.io/stageflow/variable-typing/) ·
+[Localization](https://leo-need-more-coffee.github.io/stageflow/localization/) ·
 [Session control](https://leo-need-more-coffee.github.io/stageflow/session-control/) ·
 [Step debugging](https://leo-need-more-coffee.github.io/stageflow/step-debugging/)
 

{stageflow_framework-0.12.0 → stageflow_framework-0.13.0}/README.md

@@ -96,6 +96,7 @@ against it, so a wrong argument name is an error before anything runs.
 | **Budgets that hold** | counters and gauges for time, steps, tokens, fan-out and depth; a ceiling a `try` block cannot catch |
 | **Gradual typing** | declare the variables that matter; checked at validation and on every write |
 | **Step debugging** | stop between nodes, read and edit the frame, replay the event stream |
+| **Answers in a language** | a locale per request, not per process, for the framework's own messages; stage specs carry every language at once and let the client choose |
 
 ## Documentation
 
@@ -111,6 +112,7 @@ The reference covers the rest:
 [Policy](https://leo-need-more-coffee.github.io/stageflow/policy/) ·
 [Limits](https://leo-need-more-coffee.github.io/stageflow/limits/) ·
 [Variable typing](https://leo-need-more-coffee.github.io/stageflow/variable-typing/) ·
+[Localization](https://leo-need-more-coffee.github.io/stageflow/localization/) ·
 [Session control](https://leo-need-more-coffee.github.io/stageflow/session-control/) ·
 [Step debugging](https://leo-need-more-coffee.github.io/stageflow/step-debugging/)
 

{stageflow_framework-0.12.0 → stageflow_framework-0.13.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stageflow-framework"
-version = "0.12.0"
+version = "0.13.0"
 description = "StageFlow: pipeline framework for stages"
 readme = "README.md"
 license = "MIT"
@@ -45,10 +45,23 @@ docs = [
     "mkdocs-material",
     "mkdocs-static-i18n",
 ]
+# only for working ON the translations — running StageFlow in any language
+# needs nothing beyond the compiled catalogs in the package
+i18n = [
+    "babel",
+]
 
 [tool.setuptools.packages.find]
 where = ["."]
 include = ["stageflow*"]
 
 [tool.setuptools.package-data]
-"stageflow" = ["py.typed", "docs/schemas/pipeline.json"]
+"stageflow" = [
+    "py.typed",
+    "docs/schemas/pipeline.json",
+    # the compiled catalogs are what the runtime reads; the .po ships next to
+    # them so a translator who has the wheel has the source too
+    "locale/*/LC_MESSAGES/*.mo",
+    "locale/*/LC_MESSAGES/*.po",
+    "locale/*.pot",
+]

{stageflow_framework-0.12.0 → stageflow_framework-0.13.0}/stageflow/__init__.py

@@ -54,6 +54,15 @@ from .exceptions import (
     TypeCheckError,
     TypeDeclarationError,
 )
+from .i18n import (
+    SOURCE_LOCALE,
+    available_locales,
+    get_locale,
+    negotiate,
+    register_domain,
+    set_locale,
+    use_locale,
+)
 
 __all__ = [
     "__version__",
@@ -96,6 +105,13 @@ __all__ = [
     "parse_type",
     "generate_stages_yaml",
     "generate_stages_json",
+    "SOURCE_LOCALE",
+    "available_locales",
+    "get_locale",
+    "negotiate",
+    "register_domain",
+    "set_locale",
+    "use_locale",
     "StageFlowError",
     "RegistryError",
     "PipelineDefinitionError",

{stageflow_framework-0.12.0 → stageflow_framework-0.13.0}/stageflow/builtins/_args.py

@@ -3,12 +3,14 @@ from __future__ import annotations
 from typing import Any
 
 from ..exceptions import StageContractError
+from ..i18n import _
 
 
 def require_list(stage_name: str, field: str, value: Any) -> list:
     if not isinstance(value, list):
         raise StageContractError(
-            f"{stage_name}: '{field}' must be a list, got {type(value).__name__}"
+            _("{stage}: '{field}' must be a list, got {got}",
+              stage=stage_name, field=field, got=type(value).__name__)
         )
     return value
 
@@ -16,7 +18,8 @@ def require_list(stage_name: str, field: str, value: Any) -> list:
 def require_dict(stage_name: str, field: str, value: Any) -> dict:
     if not isinstance(value, dict):
         raise StageContractError(
-            f"{stage_name}: '{field}' must be an object, got {type(value).__name__}"
+            _("{stage}: '{field}' must be an object, got {got}",
+              stage=stage_name, field=field, got=type(value).__name__)
         )
     return value
 
@@ -24,12 +27,15 @@ def require_dict(stage_name: str, field: str, value: Any) -> dict:
 def require_number(stage_name: str, field: str, value: Any) -> int | float:
     if isinstance(value, bool) or not isinstance(value, (int, float)):
         raise StageContractError(
-            f"{stage_name}: '{field}' must be a number, got {type(value).__name__}"
+            _("{stage}: '{field}' must be a number, got {got}",
+              stage=stage_name, field=field, got=type(value).__name__)
         )
     return value
 
 
 def require_present(stage_name: str, field: str, value: Any) -> Any:
     if value is None:
-        raise StageContractError(f"{stage_name}: argument '{field}' is required")
+        raise StageContractError(
+            _("{stage}: argument '{field}' is required", stage=stage_name, field=field)
+        )
     return value

stageflow_framework-0.13.0/stageflow/builtins/_base.py

@@ -0,0 +1,16 @@
+"""The base of the stages that ship with the framework.
+
+It exists for one attribute. The prose of a built-in stage is the framework's
+own text, translated in the framework's own catalog, while a host's stage is
+translated by whoever wrote it — and the difference has to be written down
+somewhere. Written here, it is written once.
+"""
+
+from __future__ import annotations
+
+from ..core.stage import BaseStage
+from ..i18n import DOMAIN
+
+
+class BuiltinStage(BaseStage):
+    i18n_domain = DOMAIN

{stageflow_framework-0.12.0 → stageflow_framework-0.13.0}/stageflow/builtins/dicts.py

@@ -1,9 +1,10 @@
-from ..core.stage import BaseStage, register_stage
+from ..core.stage import register_stage
 from ._args import require_dict, require_list
+from ._base import BuiltinStage
 
 
 @register_stage("PickKeysStage")
-class PickKeysStage(BaseStage):
+class PickKeysStage(BuiltinStage):
     """
     description: "Pick only specified keys from a dict and return new object"
     icon: "⊂"
@@ -30,7 +31,7 @@ class PickKeysStage(BaseStage):
 
 
 @register_stage("DropKeysStage")
-class DropKeysStage(BaseStage):
+class DropKeysStage(BuiltinStage):
     """
     description: "Remove specified keys from dict and return cleaned object"
     icon: "⊘"

{stageflow_framework-0.12.0 → stageflow_framework-0.13.0}/stageflow/builtins/lists.py

@@ -1,11 +1,13 @@
 from ..core.context import Context
-from ..core.stage import BaseStage, register_stage
+from ..core.stage import register_stage
+from ._base import BuiltinStage
 from ..exceptions import StageContractError
+from ..i18n import _
 from ._args import require_list
 
 
 @register_stage("AppendListStage")
-class AppendListStage(BaseStage):
+class AppendListStage(BuiltinStage):
     """
     description: "Append value to list (creates list if missing)"
     icon: "⊕"
@@ -29,14 +31,17 @@ class AppendListStage(BaseStage):
     async def run(self):
         args = self.get_arguments()
         if "value" not in args:
-            raise StageContractError("AppendListStage: argument 'value' is required")
+            raise StageContractError(
+                _("{stage}: argument '{field}' is required",
+                  stage="AppendListStage", field="value")
+            )
         value = args["value"]
         base = require_list("AppendListStage", "list", args.get("list") or [])
         self.set_outputs({"list": [*base, value]})
 
 
 @register_stage("ExtendListStage")
-class ExtendListStage(BaseStage):
+class ExtendListStage(BuiltinStage):
     """
     description: "Extend list with items from arguments"
     icon: "⊞"
@@ -63,13 +68,14 @@ class ExtendListStage(BaseStage):
         items = args.get("items", [])
         if not isinstance(items, (list, tuple)):
             raise StageContractError(
-                f"ExtendListStage: 'items' must be a list, got {type(items).__name__}"
+                _("{stage}: '{field}' must be a list, got {got}",
+                  stage="ExtendListStage", field="items", got=type(items).__name__)
             )
         self.set_outputs({"list": [*base, *items]})
 
 
 @register_stage("FilterListStage")
-class FilterListStage(BaseStage):
+class FilterListStage(BuiltinStage):
     """
     description: "Filter list items by CEL condition; current element is bound as `item`"
     icon: "▽"
@@ -95,7 +101,10 @@ class FilterListStage(BaseStage):
         args = self.get_arguments()
         condition = args.pop("condition", None)
         if condition is None:
-            raise StageContractError("FilterListStage: argument 'condition' is required")
+            raise StageContractError(
+                _("{stage}: argument '{field}' is required",
+                  stage="FilterListStage", field="condition")
+            )
         items = require_list("FilterListStage", "items", args.pop("items", []))
         scope = Context(vars=args)
         result = [item for item in items if self.session.cel.eval(condition, scope, item=item)]
@@ -103,7 +112,7 @@ class FilterListStage(BaseStage):
 
 
 @register_stage("UniqueListStage")
-class UniqueListStage(BaseStage):
+class UniqueListStage(BuiltinStage):
     """
     description: "Deduplicate list while preserving original order"
     icon: "≠"
@@ -131,7 +140,7 @@ class UniqueListStage(BaseStage):
 
 
 @register_stage("PopListStage")
-class PopListStage(BaseStage):
+class PopListStage(BuiltinStage):
     """
     description: "Pop element from list (default last) and return list+popped value"
     icon: "⊟"
@@ -159,13 +168,16 @@ class PopListStage(BaseStage):
         args = self.get_arguments()
         items = require_list("PopListStage", "items", args.get("items", []))
         if not items:
-            raise StageContractError("PopListStage: cannot pop from an empty list")
+            raise StageContractError(
+                _("PopListStage: cannot pop from an empty list")
+            )
         index = args.get("index", -1)
         remaining = list(items)
         try:
             popped = remaining.pop(index)
         except IndexError:
             raise StageContractError(
-                f"PopListStage: index {index} is out of range for a list of length {len(items)}"
+                _("PopListStage: index {index} is out of range for a list of "
+                  "length {length}", index=index, length=len(items))
             ) from None
         self.set_outputs({"list": remaining, "popped": popped})

{stageflow_framework-0.12.0 → stageflow_framework-0.13.0}/stageflow/builtins/logic.py

@@ -1,12 +1,14 @@
 import asyncio
 
 from ..core.context import Context
-from ..core.stage import BaseStage, register_stage
+from ..core.stage import register_stage
+from ..i18n import _
 from ._args import require_number, require_present
+from ._base import BuiltinStage
 
 
 @register_stage("AssertStage")
-class AssertStage(BaseStage):
+class AssertStage(BuiltinStage):
     """
     description: "Validate CEL condition against stage arguments, raise on failure"
     icon: "✓"
@@ -30,14 +32,14 @@ class AssertStage(BaseStage):
     async def run(self):
         args = self.get_arguments()
         condition = require_present("AssertStage", "condition", args.pop("condition", None))
-        message = args.pop("message", "assertion failed")
+        message = args.pop("message", None) or _("assertion failed")
         scope = Context(vars=args)
         if not self.session.cel.eval(condition, scope):
             raise AssertionError(message)
 
 
 @register_stage("FailStage")
-class FailStage(BaseStage):
+class FailStage(BuiltinStage):
     """
     description: "Always raise a runtime error with provided message"
     icon: "✕"
@@ -57,7 +59,7 @@ class FailStage(BaseStage):
 
 
 @register_stage("LogStage")
-class LogStage(BaseStage):
+class LogStage(BuiltinStage):
     """
     description: "Emit log event with message and the stage's own arguments"
     icon: "≡"
@@ -80,7 +82,7 @@ class LogStage(BaseStage):
 
 
 @register_stage("SleepStage")
-class SleepStage(BaseStage):
+class SleepStage(BuiltinStage):
     """
     description: "Async sleep for the given number of seconds"
     icon: "⏱"

{stageflow_framework-0.12.0 → stageflow_framework-0.13.0}/stageflow/builtins/strings.py

@@ -1,7 +1,9 @@
 import string
 
-from ..core.stage import BaseStage, register_stage
+from ..core.stage import register_stage
+from ._base import BuiltinStage
 from ..exceptions import StageContractError
+from ..i18n import _
 from ._args import require_list, require_present
 
 
@@ -9,19 +11,21 @@ class _NameOnlyFormatter(string.Formatter):
     def get_field(self, field_name, args, kwargs):
         if not field_name.isidentifier():
             raise StageContractError(
-                f"TemplateStage: placeholder '{{{field_name}}}' is not an argument name; "
-                "attributes, indexes and positional numbers are not allowed"
+                _("TemplateStage: placeholder '{{{field}}}' is not an argument name; "
+                  "attributes, indexes and positional numbers are not allowed",
+                  field=field_name)
             )
         if field_name not in kwargs:
             raise StageContractError(
-                f"TemplateStage: template references '{field_name}', "
-                f"but there is no such argument (available: {sorted(kwargs)})"
+                _("TemplateStage: template references '{field}', "
+                  "but there is no such argument (available: {available})",
+                  field=field_name, available=sorted(kwargs))
             )
         return kwargs[field_name], field_name
 
 
 @register_stage("ConcatStage")
-class ConcatStage(BaseStage):
+class ConcatStage(BuiltinStage):
     """
     description: "Concatenate stringified parts with separator"
     icon: "⧺"
@@ -50,7 +54,7 @@ class ConcatStage(BaseStage):
 
 
 @register_stage("TemplateStage")
-class TemplateStage(BaseStage):
+class TemplateStage(BuiltinStage):
     """
     description: "Format template string with the stage's own arguments"
     icon: "{}"

{stageflow_framework-0.12.0 → stageflow_framework-0.13.0}/stageflow/builtins/vars.py

@@ -1,10 +1,12 @@
-from ..core.stage import BaseStage, register_stage
+from ..core.stage import register_stage
+from ._base import BuiltinStage
 from ..exceptions import StageContractError
+from ..i18n import _
 from ._args import require_dict, require_number
 
 
 @register_stage("SetValueStage")
-class SetValueStage(BaseStage):
+class SetValueStage(BuiltinStage):
     """
     description: "Set value from arguments to the target path"
     icon: "="
@@ -23,12 +25,15 @@ class SetValueStage(BaseStage):
     async def run(self):
         args = self.get_arguments()
         if "value" not in args:
-            raise StageContractError("SetValueStage: argument 'value' is required")
+            raise StageContractError(
+                _("{stage}: argument '{field}' is required",
+                  stage="SetValueStage", field="value")
+            )
         self.set_outputs({"value": args["value"]})
 
 
 @register_stage("CopyValueStage")
-class CopyValueStage(BaseStage):
+class CopyValueStage(BuiltinStage):
     """
     description: "Copy value to output path, falling back to default when absent"
     icon: "⧉"
@@ -57,7 +62,7 @@ class CopyValueStage(BaseStage):
 
 
 @register_stage("IncrementStage")
-class IncrementStage(BaseStage):
+class IncrementStage(BuiltinStage):
     """
     description: "Increment numeric value by delta"
     icon: "＋"
@@ -86,7 +91,7 @@ class IncrementStage(BaseStage):
 
 
 @register_stage("MergeDictStage")
-class MergeDictStage(BaseStage):
+class MergeDictStage(BuiltinStage):
     """
     description: "Shallow merge src dict into dst"
     icon: "⋈"

{stageflow_framework-0.12.0 → stageflow_framework-0.13.0}/stageflow/capabilities.py

@@ -6,6 +6,7 @@ from typing import Any
 from .core.nodes import get_node_types
 from .core.policy import Policy
 from .core.stage import get_stages
+from .i18n import available_locales
 
 DISTRIBUTION = "stageflow-framework"
 
@@ -38,6 +39,9 @@ def capabilities(policy: Policy | None = None) -> dict[str, Any]:
     - `stages` — how many stages may be used. The specs themselves are a
       separate, much larger answer (`get_stages`), so this is only a hint that
       a registry is there at all.
+    - `locales` — the languages the core can put its own text into, the source
+      language first. A client cannot guess this: a catalog is a file in the
+      build, so the build has to say.
 
     With a `policy` the answer narrows to what that policy allows, which is
     what a backend should serve to a client: an editor needs to know what
@@ -59,4 +63,5 @@ def capabilities(policy: Policy | None = None) -> dict[str, Any]:
         "stageflow": __version__,
         "node_types": node_types,
         "stages": len(stages),
+        "locales": available_locales(),
     }

{stageflow_framework-0.12.0 → stageflow_framework-0.13.0}/stageflow/core/cel.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from typing import Any
 
 from ..exceptions import ExpressionError
+from ..i18n import _
 from .context import Context
 
 CelError = ExpressionError
@@ -28,8 +29,8 @@ class CelEngine:
         self._compiled: dict[str, Any] = {}
         if _BACKEND is None:  # pragma: no cover
             raise ExpressionError(
-                "No CEL backend found. Install "
-                "'common-expression-language' (recommended) or 'cel-python'."
+                _("No CEL backend found. Install "
+                  "'common-expression-language' (recommended) or 'cel-python'.")
             )
 
     @property
@@ -46,7 +47,9 @@ class CelEngine:
                     env = _celpy.Environment()
                     program = env.program(env.compile(expr))
             except Exception as exc:  # noqa: BLE001
-                raise ExpressionError(f"Cannot compile CEL {expr!r}: {exc}") from exc
+                raise ExpressionError(
+                    _("Cannot compile CEL {expr}: {reason}", expr=repr(expr), reason=exc)
+                ) from exc
             self._compiled[expr] = program
         return program
 
@@ -75,4 +78,6 @@ class CelEngine:
                 return program.execute(activation)
             return program.evaluate(activation)  # pragma: no cover
         except Exception as exc:  # noqa: BLE001
-            raise ExpressionError(f"Cannot evaluate CEL {expr!r}: {exc}") from exc
+            raise ExpressionError(
+                _("Cannot evaluate CEL {expr}: {reason}", expr=repr(expr), reason=exc)
+            ) from exc

{stageflow_framework-0.12.0 → stageflow_framework-0.13.0}/stageflow/core/context.py

@@ -5,6 +5,7 @@ from typing import Any
 import immutables
 
 from ..exceptions import PipelineDefinitionError
+from ..i18n import _
 
 
 class Context:
@@ -39,8 +40,8 @@ class Context:
     def from_dict(cls, data: dict[str, Any]) -> "Context":
         if "local" in data and "vars" not in data:
             raise PipelineDefinitionError(
-                "Snapshot contains the 'local' scope (pre-0.7.0); "
-                "the frame is now called 'vars'"
+                _("Snapshot contains the 'local' scope (pre-0.7.0); "
+                  "the frame is now called 'vars'")
             )
         return cls(vars=data.get("vars", {}))
 

{stageflow_framework-0.12.0 → stageflow_framework-0.13.0}/stageflow/core/debug.py

@@ -4,6 +4,7 @@ import asyncio
 import threading
 from typing import Any, Callable
 
+from ..i18n import _
 from .context import Context
 
 RUN = "run"
@@ -124,7 +125,10 @@ class StepDebugger:
         for name, value in values.items():
             try:
                 if types is not None:
-                    types.check_write(name, value, f"debugger before node '{self.node}'")
+                    types.check_write(
+                        name, value,
+                        _("debugger before node '{node}'", node=self.node),
+                    )
             except Exception as exc:  # noqa: BLE001
                 self._emit("var_rejected", name=name, error=str(exc))
                 continue

{stageflow_framework-0.12.0 → stageflow_framework-0.13.0}/stageflow/core/nodes/base.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING
 
 from ...exceptions import PipelineDefinitionError
+from ...i18n import _
 from ..context import Context
 from ..registry import Registry
 from .recovery import Retrier
@@ -46,7 +47,9 @@ class Node:
     def from_dict(data: dict) -> "Node":
         node_type = data.get("type")
         if node_type not in _node_types:
-            raise PipelineDefinitionError(f"Unknown node type: {node_type!r}")
+            raise PipelineDefinitionError(
+                _("Unknown node type: {type}", type=repr(node_type))
+            )
         return _node_types.get(node_type)._parse(data)
 
     @classmethod
@@ -77,11 +80,14 @@ class Node:
         errors: list[str] = []
         for src, dst in self.expose.items():
             malformed = False
-            for path, side in ((src, "source"), (dst, "destination")):
+            # a whole sentence per side rather than the English noun dropped
+            # into one — see the reason in `registry.py`
+            for path, message in (
+                (src, _("{node}: expose source '{path}' must be a variable name")),
+                (dst, _("{node}: expose destination '{path}' must be a variable name")),
+            ):
                 if not isinstance(path, str) or not path.isidentifier():
-                    errors.append(
-                        f"{self.id}: expose {side} '{path}' must be a variable name"
-                    )
+                    errors.append(message.format(node=self.id, path=path))
                     malformed = True
             if malformed:
                 continue
@@ -90,8 +96,10 @@ class Node:
             dst_type = ts.declared(dst)
             if src_type and dst_type and not ts.expose_compatible(src_type, dst_type):
                 errors.append(
-                    f"{self.id}: expose {src} -> {dst}: incompatible types "
-                    f"'{src_type}' and '{dst_type}'"
+                    _("{node}: expose {source} -> {target}: incompatible types "
+                      "'{source_type}' and '{target_type}'",
+                      node=self.id, source=src, target=dst,
+                      source_type=src_type, target_type=dst_type)
                 )
         return errors
 

{stageflow_framework-0.12.0 → stageflow_framework-0.13.0}/stageflow/core/nodes/bindings.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any
 
 from ...exceptions import PipelineDefinitionError, StageOutputError
+from ...i18n import _
 from ..context import Context
 
 if TYPE_CHECKING:  # pragma: no cover
@@ -20,7 +21,7 @@ def normalize_bucket(bucket: Any) -> dict[str, str]:
     if isinstance(bucket, dict):
         return dict(bucket)
     raise PipelineDefinitionError(
-        f"Bucket must be a list or an object, got {type(bucket).__name__}"
+        _("Bucket must be a list or an object, got {got}", got=type(bucket).__name__)
     )
 
 
@@ -75,7 +76,8 @@ def apply_outputs(
             dest = spec
             if key not in output_ns:
                 raise StageOutputError(
-                    f"Stage did not return field '{key}' (available: {sorted(output_ns)})"
+                    _("Stage did not return field '{field}' (available: {available})",
+                      field=key, available=sorted(output_ns))
                 )
             value = output_ns[key]
         writes.append((dest, value))