urban-workflow 0.1.0__py3-none-any.whl

urban_workflow/__init__.py

@@ -0,0 +1,118 @@
+"""urban-workflow — moteur de workflow piloté par un DSL métier.
+
+Portage Python de `Black-Beard-Sdk/Workflow
+<https://github.com/Black-Beard-Sdk/Workflow>`_, avec normalisation des
+sorties JSON par `urban-json <https://pypi.org/project/urban-json/>`_.
+"""
+
+from .clock import WorkflowClock
+from .config import (
+    DeclaredEventConfig,
+    IncomingEventConfig,
+    InitializationConfig,
+    InitializationOnEventConfig,
+    ResultActionConfig,
+    ResultRuleConfig,
+    StateConfig,
+    TransitionConfig,
+    WorkflowConfig,
+    WorkflowsConfig,
+)
+from .engine import (
+    ActionTranslator,
+    DefaultActionTranslator,
+    WorkflowEngine,
+    WorkflowFactory,
+    WorkflowProcessor,
+    parse_incoming_event,
+)
+from .exceptions import (
+    DuplicatedArgumentNameError,
+    InvalidArgumentNameError,
+    InvalidIncomingEventFormatError,
+    InvalidMethodReferenceError,
+    LockFailedError,
+    MissingArgumentNameError,
+    MissingConfigurationError,
+    MissingStateError,
+    ResolutionArgumentError,
+    WorkflowError,
+)
+from .models import (
+    ChangeEnum,
+    CurrentEvaluation,
+    Event,
+    IncomingEvent,
+    PushedAction,
+    ResultAction,
+    RuleSpan,
+    RunContext,
+    Workflow,
+)
+from .outputs import (
+    DoNothingTransaction,
+    LockObject,
+    MemoryLocker,
+    MemoryStorage,
+    OutputAction,
+    PushBusOutputAction,
+    PushModelOutputAction,
+    SetPropertiesOutputAction,
+    Transaction,
+)
+from .registry import FunctionRegistry
+from .values import ContextRef, make_value, resolve_value
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ActionTranslator",
+    "ChangeEnum",
+    "ContextRef",
+    "CurrentEvaluation",
+    "DefaultActionTranslator",
+    "DoNothingTransaction",
+    "LockObject",
+    "MemoryLocker",
+    "MemoryStorage",
+    "OutputAction",
+    "PushBusOutputAction",
+    "PushModelOutputAction",
+    "SetPropertiesOutputAction",
+    "Transaction",
+    "WorkflowEngine",
+    "WorkflowFactory",
+    "WorkflowProcessor",
+    "parse_incoming_event",
+    "DeclaredEventConfig",
+    "DuplicatedArgumentNameError",
+    "Event",
+    "FunctionRegistry",
+    "IncomingEvent",
+    "IncomingEventConfig",
+    "InitializationConfig",
+    "InitializationOnEventConfig",
+    "InvalidArgumentNameError",
+    "InvalidIncomingEventFormatError",
+    "InvalidMethodReferenceError",
+    "LockFailedError",
+    "MissingArgumentNameError",
+    "MissingConfigurationError",
+    "MissingStateError",
+    "PushedAction",
+    "ResolutionArgumentError",
+    "ResultAction",
+    "ResultActionConfig",
+    "ResultRuleConfig",
+    "RuleSpan",
+    "RunContext",
+    "StateConfig",
+    "TransitionConfig",
+    "Workflow",
+    "WorkflowClock",
+    "WorkflowConfig",
+    "WorkflowError",
+    "WorkflowsConfig",
+    "make_value",
+    "resolve_value",
+]

urban_workflow/clock.py

@@ -0,0 +1,45 @@
+"""Horloge du moteur, injectable pour les tests.
+
+Portage de ``WorkflowClock`` : tout le moteur date ses objets via
+``WorkflowClock.now()`` et jamais via ``datetime.now`` directement, ce qui
+permet de figer le temps dans les tests (expirations, rappels différés).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from datetime import datetime, timezone
+
+
+def _default_provider() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class WorkflowClock:
+    """Source de temps unique du moteur (UTC, avec fuseau)."""
+
+    _provider: Callable[[], datetime] = staticmethod(_default_provider)
+
+    @classmethod
+    def now(cls) -> datetime:
+        return cls._provider()
+
+    @classmethod
+    def set_provider(cls, provider: Callable[[], datetime]) -> None:
+        cls._provider = staticmethod(provider)
+
+    @classmethod
+    def reset(cls) -> None:
+        cls._provider = staticmethod(_default_provider)
+
+    @classmethod
+    @contextmanager
+    def frozen(cls, instant: datetime) -> Iterator[datetime]:
+        """Fige l'horloge sur ``instant`` le temps du bloc ``with``."""
+        previous = cls._provider
+        cls._provider = staticmethod(lambda: instant)
+        try:
+            yield instant
+        finally:
+            cls._provider = previous

urban_workflow/config/__init__.py

@@ -0,0 +1,32 @@
+"""Modèle de configuration des workflows (cible du visiteur DSL)."""
+
+from .rules import (
+    DeclaredEventConfig,
+    ResultActionConfig,
+    ResultRuleConfig,
+    Rule,
+    append_rule_actions,
+)
+from .states import (
+    IncomingEventConfig,
+    InitializationConfig,
+    InitializationOnEventConfig,
+    StateConfig,
+    TransitionConfig,
+)
+from .workflow import WorkflowConfig, WorkflowsConfig
+
+__all__ = [
+    "DeclaredEventConfig",
+    "IncomingEventConfig",
+    "InitializationConfig",
+    "InitializationOnEventConfig",
+    "ResultActionConfig",
+    "ResultRuleConfig",
+    "Rule",
+    "StateConfig",
+    "TransitionConfig",
+    "WorkflowConfig",
+    "WorkflowsConfig",
+    "append_rule_actions",
+]

urban_workflow/config/rules.py

@@ -0,0 +1,85 @@
+"""Configuration des règles conditionnées et des actions à produire."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..clock import WorkflowClock
+from ..models import ResultAction, RuleSpan, RunContext
+from ..values import ContextValue, make_value
+
+#: Une règle ``WHEN`` compilée : prédicat sur le contexte d'exécution.
+Rule = Callable[[RunContext], bool]
+
+
+@dataclass
+class DeclaredEventConfig:
+    """Événement déclaré (``DEFINE EVENT``) ou technique."""
+
+    name: str = ""
+    label: str = ""
+
+
+@dataclass
+class ResultActionConfig:
+    """Action à produire (``EXECUTE action(args)`` / ``STORE (…)``)."""
+
+    name: str = ""
+    label: str = ""
+    delay: int = 0
+    kind: str = ""
+    arguments: dict[str, ContextValue] = field(default_factory=dict)
+
+    def add_argument(self, key: str, value: Any) -> ResultActionConfig:
+        """Ajoute un argument ; les chaînes ``@a.b.c`` deviennent des références."""
+        self.arguments[key] = make_value(value)
+        return self
+
+    def map(self, ctx: RunContext) -> ResultAction:
+        """Instancie l'action pour un contexte donné (arguments non résolus)."""
+        return ResultAction(
+            name=self.name,
+            label=self.name,
+            delay=self.delay,
+            kind=self.kind,
+            event=ctx.event,
+            event_date=WorkflowClock.now(),
+            arguments=dict(self.arguments),
+        )
+
+
+@dataclass
+class ResultRuleConfig:
+    """Un bloc ``WHEN règle → actions`` (règle absente = toujours vrai)."""
+
+    when_rule: Rule | None = None
+    when_rule_text: str = ""
+    when_rule_code: str = ""
+    when_rule_position: RuleSpan = field(default_factory=RuleSpan.none)
+    actions: list[ResultActionConfig] = field(default_factory=list)
+
+    def add_actions(self, *actions: ResultActionConfig) -> ResultRuleConfig:
+        self.actions.extend(actions)
+        return self
+
+
+def append_rule_actions(
+    rules: list[ResultRuleConfig],
+    when_rule: Rule | None,
+    *actions: ResultActionConfig,
+) -> ResultRuleConfig:
+    """Accroche ``actions`` au bloc portant ``when_rule``, créé au besoin.
+
+    Reprend le comportement des extensions ``AddAction``/``AddIncomingActions``
+    du source : les actions partageant la même règle sont regroupées.
+    """
+    for rule in rules:
+        if rule.when_rule is when_rule:
+            rule.add_actions(*actions)
+            return rule
+    rule = ResultRuleConfig(when_rule=when_rule)
+    rule.add_actions(*actions)
+    rules.append(rule)
+    return rule

urban_workflow/config/states.py

@@ -0,0 +1,118 @@
+"""Configuration des états, transitions et initialisations."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from ..models import RuleSpan
+from .rules import ResultActionConfig, ResultRuleConfig, Rule, append_rule_actions
+
+
+@dataclass
+class TransitionConfig:
+    """``(WHEN règle)? … SWITCH état`` au sein d'un ``ON EVENT``."""
+
+    target_state_name: str = ""
+    when_rule: Rule | None = None
+    when_rule_text: str = ""
+    when_rule_code: str = ""
+    when_rule_position: RuleSpan = field(default_factory=RuleSpan.none)
+    rule_actions: list[ResultRuleConfig] = field(default_factory=list)
+
+    #: Résolu par :meth:`WorkflowConfig.build`.
+    target_state: StateConfig | None = None
+    label: str = ""
+
+    def add_actions(
+        self, when_rule: Rule | None, *actions: ResultActionConfig
+    ) -> TransitionConfig:
+        append_rule_actions(self.rule_actions, when_rule, *actions)
+        return self
+
+
+@dataclass
+class IncomingEventConfig:
+    """``ON EVENT nom`` d'un état : règles exécutées et transitions."""
+
+    name: str = ""
+    transitions: list[TransitionConfig] = field(default_factory=list)
+    rules: list[ResultRuleConfig] = field(default_factory=list)
+
+    def add_transition(self, transition: TransitionConfig) -> IncomingEventConfig:
+        self.transitions.append(transition)
+        return self
+
+    def add_action(
+        self, when_rule: Rule | None, action: ResultActionConfig
+    ) -> IncomingEventConfig:
+        append_rule_actions(self.rules, when_rule, action)
+        return self
+
+
+@dataclass
+class StateConfig:
+    """``DEFINE STATE`` : événements écoutés et règles d'entrée/sortie."""
+
+    name: str = ""
+    label: str = ""
+    events: dict[str, IncomingEventConfig] = field(default_factory=dict)
+    incoming_rules: list[ResultRuleConfig] = field(default_factory=list)
+    outcoming_rules: list[ResultRuleConfig] = field(default_factory=list)
+
+    def add_event(self, event: IncomingEventConfig) -> StateConfig:
+        self.events[event.name] = event
+        return self
+
+    def add_incoming_actions(
+        self, when_rule: Rule | None, *actions: ResultActionConfig
+    ) -> StateConfig:
+        append_rule_actions(self.incoming_rules, when_rule, *actions)
+        return self
+
+    def add_outcoming_actions(
+        self, when_rule: Rule | None, *actions: ResultActionConfig
+    ) -> StateConfig:
+        append_rule_actions(self.outcoming_rules, when_rule, *actions)
+        return self
+
+
+@dataclass
+class InitializationConfig:
+    """Un ``SWITCH`` d'initialisation : ``(WHEN règle)? SWITCH état``."""
+
+    target_state_name: str = ""
+    when_rule: Rule | None = None
+    when_rule_text: str = ""
+    when_rule_code: str = ""
+    when_rule_position: RuleSpan = field(default_factory=RuleSpan.none)
+
+    #: Résolu par :meth:`WorkflowConfig.build`.
+    target_state: StateConfig | None = None
+
+
+@dataclass
+class InitializationOnEventConfig:
+    """``INITIALIZE WORKFLOW ON EVENT nom`` : création de workflow."""
+
+    event_name: str = ""
+    recursive: bool = False
+    switchs: list[InitializationConfig] = field(default_factory=list)
+
+    def add_switch(
+        self,
+        target_state_name: str,
+        when_rule: Rule | None = None,
+        when_rule_text: str = "",
+        when_rule_code: str = "",
+        when_rule_position: RuleSpan | None = None,
+    ) -> InitializationOnEventConfig:
+        self.switchs.append(
+            InitializationConfig(
+                target_state_name=target_state_name,
+                when_rule=when_rule,
+                when_rule_text=when_rule_text,
+                when_rule_code=when_rule_code,
+                when_rule_position=when_rule_position or RuleSpan.none(),
+            )
+        )
+        return self

urban_workflow/config/workflow.py

@@ -0,0 +1,189 @@
+"""Configuration d'un workflow et collection multi-configurations."""
+
+from __future__ import annotations
+
+import threading
+from collections.abc import Iterator
+from dataclasses import dataclass, field
+
+from .. import constants
+from ..exceptions import MissingConfigurationError, MissingStateError
+from ..models import IncomingEvent
+from .rules import DeclaredEventConfig
+from .states import InitializationOnEventConfig, StateConfig
+
+_TECHNICAL_EVENT_LABELS = {
+    constants.RESULT_ACTION_NAME: (
+        "technical result of execution of an order pushed by the current workflow"
+    ),
+    constants.EXPIRED_EVENT_NAME: "Expiration of the state",
+}
+
+
+@dataclass
+class WorkflowConfig:
+    """Machine à états déclarée (une version d'un workflow)."""
+
+    name: str = ""
+    label: str = ""
+    version: int = 0
+    concurrency: int = 1
+    crc: int = 0
+    filters: dict[str, str] = field(default_factory=dict)
+    initializers: dict[str, InitializationOnEventConfig] = field(default_factory=dict)
+    declared_events: dict[str, DeclaredEventConfig] = field(default_factory=dict)
+    states: dict[str, StateConfig] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        self._built = False
+        self._build_lock = threading.Lock()
+
+    # ------------------------------------------------------------------
+    # Construction fluide
+    # ------------------------------------------------------------------
+
+    def add_state(self, state: StateConfig) -> WorkflowConfig:
+        self.states[state.name] = state
+        return self
+
+    def add_initializer(self, initializer: InitializationOnEventConfig) -> WorkflowConfig:
+        self.initializers[initializer.event_name] = initializer
+        return self
+
+    def add_filter(self, key: str, value: str) -> WorkflowConfig:
+        """``MATCHING (key = 'value')`` : filtre de routage des événements."""
+        self.filters[key] = value
+        return self
+
+    # ------------------------------------------------------------------
+    # Construction / résolution
+    # ------------------------------------------------------------------
+
+    def build(self) -> WorkflowConfig:
+        """Résout les références et prépare la configuration (idempotent)."""
+        if self._built:
+            return self
+        with self._build_lock:
+            if self._built:
+                return self
+            self._build_declared_events()
+            self._resolve_target_states()
+            self._build_transition_labels()
+            self._built = True
+        return self
+
+    def _build_declared_events(self) -> None:
+        def declare(name: str) -> None:
+            if name not in self.declared_events:
+                self.declared_events[name] = DeclaredEventConfig(
+                    name=name,
+                    label=_TECHNICAL_EVENT_LABELS.get(name, ""),
+                )
+
+        declare(constants.RESULT_ACTION_NAME)
+
+        for event_name in self.initializers:
+            declare(event_name)
+
+        for state in self.states.values():
+            for event_name in state.events:
+                declare(event_name)
+
+    def _resolve_target_states(self) -> None:
+        def resolve(target_state_name: str) -> StateConfig:
+            state = self.states.get(target_state_name)
+            if state is None:
+                raise MissingStateError(f"missing state name {target_state_name}")
+            return state
+
+        for initializer in self.initializers.values():
+            for switch in initializer.switchs:
+                switch.target_state = resolve(switch.target_state_name)
+
+        for state in self.states.values():
+            for event in state.events.values():
+                for transition in event.transitions:
+                    transition.target_state = resolve(transition.target_state_name)
+
+    def _build_transition_labels(self) -> None:
+        for state_name, state in self.states.items():
+            for event in state.events.values():
+                for transition in event.transitions:
+                    transition.label = f"{state_name} -> {transition.target_state_name}"
+
+    # ------------------------------------------------------------------
+    # Routage
+    # ------------------------------------------------------------------
+
+    def evaluate_filter(self, event: IncomingEvent) -> bool:
+        """Vrai si les données étendues de l'événement satisfont ``MATCHING``."""
+        self.build()
+        for key, expected in self.filters.items():
+            actual = event.extended_datas.get(key)
+            if actual is None or str(actual) != expected:
+                return False
+        return True
+
+
+class WorkflowsConfig:
+    """Ensemble des configurations chargées dans le processeur.
+
+    Gère le versionnage (plusieurs versions d'un même workflow) et le
+    routage d'un événement vers les configurations dont les filtres
+    ``MATCHING`` correspondent.
+    """
+
+    def __init__(self) -> None:
+        self._configs: list[WorkflowConfig] = []
+        self._by_name_version: dict[tuple[str, int], WorkflowConfig] = {}
+        self._selectable: list[WorkflowConfig] = []
+        self._version_selectors: dict[str, set[int]] = {}
+        self._lock = threading.Lock()
+
+    def set_version_selector(self, workflow_name: str, version: int) -> WorkflowsConfig:
+        """Restreint la création de nouveaux workflows ``workflow_name`` à ``version``.
+
+        Sans sélecteur, toutes les versions chargées sont candidates ; les
+        workflows déjà créés continuent, eux, d'utiliser leur version d'origine.
+        """
+        with self._lock:
+            self._version_selectors.setdefault(workflow_name, set()).add(version)
+            self._rebuild_selectable()
+        return self
+
+    def add_document(self, config: WorkflowConfig) -> WorkflowsConfig:
+        config.build()
+        with self._lock:
+            self._configs.append(config)
+            self._by_name_version[(config.name, config.version)] = config
+            self._rebuild_selectable()
+        return self
+
+    def _rebuild_selectable(self) -> None:
+        self._selectable = [
+            config
+            for config in self._configs
+            if config.name not in self._version_selectors
+            or config.version in self._version_selectors[config.name]
+        ]
+
+    def matching(self, event: IncomingEvent) -> Iterator[WorkflowConfig]:
+        """Configurations candidates pour un événement entrant."""
+        for config in self._selectable:
+            if config.evaluate_filter(event):
+                yield config
+
+    def get(self, workflow_name: str, version: int) -> WorkflowConfig:
+        config = self._by_name_version.get((workflow_name, version))
+        if config is None:
+            raise MissingConfigurationError(f"{workflow_name} V {version}")
+        return config
+
+    def try_get(self, workflow_name: str, version: int) -> WorkflowConfig | None:
+        return self._by_name_version.get((workflow_name, version))
+
+    def get_all(self, workflow_name: str) -> list[WorkflowConfig]:
+        return [config for config in self._configs if config.name == workflow_name]
+
+    def __len__(self) -> int:
+        return len(self._configs)

urban_workflow/constants.py

@@ -0,0 +1,22 @@
+"""Noms techniques du moteur (événements et actions réservés).
+
+Portage de ``Bb.Workflows.Constants`` — les valeurs sont conservées à
+l'identique pour rester compatible avec les configurations existantes.
+"""
+
+CURRENT_WORKFLOW = "_workflow"
+
+SET_VALUE_ACTION_NAME = "$_update"
+PUSH_ACTION_NAME = "$_push"
+PUSH_REMINDER = "$_reminder"
+
+EVENT_ID = "EventId"
+TASK_UUID = "TaskId"
+
+# Événements techniques
+RESULT_ACTION_NAME = "$_result"
+EXPIRED_EVENT_NAME = "__expired"
+CANCEL_REMINDER_ACTION = "__cancelReminderAction"
+
+# Propriétés réservées des données étendues
+WORKFLOW_ID_PROPERTY = "WorkflowId"

urban_workflow/dsl/__init__.py

@@ -0,0 +1,54 @@
+"""DSL de déclaration des workflows.
+
+Grammaires ANTLR reprises telles quelles du projet source
+(``urban_workflow/dsl/grammar/``), parseur Python généré
+(``urban_workflow/dsl/generated/``, ANTLR 4.13.2), visiteur de construction
+:class:`WorkflowConfigVisitor` et chargeur de répertoires avec
+``INCLUDE``/``FRAGMENT``.
+
+Point d'entrée simple ::
+
+    from urban_workflow import FunctionRegistry
+    from urban_workflow.dsl import parse_config
+
+    rules = FunctionRegistry("rule")
+    rules.add("IsMajor", is_major)
+    config = parse_config(script_text, rules=rules, filename="demo.wf")
+"""
+
+from __future__ import annotations
+
+from ..config import WorkflowConfig
+from ..registry import FunctionRegistry
+from .errors import DslErrorModel
+from .loader import load_directory, parse_directory
+from .parser import WorkflowScriptParser
+from .visitor import ConstantModel, DeclaredFunction, WorkflowConfigVisitor
+
+__all__ = [
+    "ConstantModel",
+    "DeclaredFunction",
+    "DslErrorModel",
+    "WorkflowConfigVisitor",
+    "WorkflowScriptParser",
+    "load_directory",
+    "parse_config",
+    "parse_directory",
+]
+
+
+def parse_config(
+    source: str,
+    rules: FunctionRegistry | None = None,
+    filename: str = "",
+) -> WorkflowConfig:
+    """Analyse un script DSL complet et construit sa configuration.
+
+    Lève :class:`~urban_workflow.exceptions.DslSyntaxError` sur erreur de
+    syntaxe, et les exceptions de validation positionnées du visiteur sur
+    erreur sémantique (règle non enregistrée, action non déclarée,
+    argument inconnu ou manquant, état ``SWITCH`` absent…).
+    """
+    parser = WorkflowScriptParser.parse_string(source, filename=filename).check()
+    visitor = WorkflowConfigVisitor(rules=rules, filename=filename)
+    return parser.visit(visitor)

urban_workflow/dsl/errors.py

@@ -0,0 +1,23 @@
+"""Erreurs positionnées du parseur DSL (portage de ``ErrorModel``)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class DslErrorModel:
+    """Une erreur de syntaxe positionnée dans un script DSL."""
+
+    message: str = ""
+    filename: str = ""
+    line: int = 0
+    column: int = 0
+    start_index: int = 0
+    text: str = ""
+
+    def __str__(self) -> str:
+        location = f"{self.filename}:{self.line}:{self.column}" if self.filename else (
+            f"{self.line}:{self.column}"
+        )
+        return f"{location}: {self.message}"