pytestflow 0.2.0__py3-none-any.whl

pytestflow/core/README.md

@@ -0,0 +1,110 @@
+# PyTestFlow Core
+
+The `pytestflow.core` package hosts the building blocks of the framework: the
+Prefect-integrated `Step` wrapper, shared execution context, sequence and
+process-model flows, and the state objects returned by each step. These pieces
+realize PyTestFlow's philosophy of **steps-as-tasks**, a **shared context**, and
+**composable flows**.
+
+See the [project README](../../readme.md) for an overview and
+[steps documentation](../steps/README.md) for available step implementations.
+
+## Context management
+
+`ptf_context` is a singleton `TestContext` that exposes four useful attributes:
+
+- `globals` – values shared across the entire process model run.
+- `locals` – values scoped to the currently executing sequence.
+- `results` – optional history of step execution results.
+- `current_step` – pointer to the `Step` instance currently executing.
+
+Steps can access the context implicitly through autowired parameters or
+explicitly by importing `ptf_context`:
+
+```python
+from pytestflow.core import ptf_context, step
+
+
+@step(name="load_config")
+def load_config():
+    ptf_context.globals["serial"] = "ABC123"
+```
+
+## Step wrapper
+
+`@step` wraps a plain function with the `Step` class, which in turn wraps the
+function with Prefect's `@task`. The wrapper collects metadata (`get_meta_info`),
+allows enrichment (`add_additional_info`), and exposes Prefect task helpers like
+`.submit()`.
+
+```python
+from pytestflow.core import step
+from pytestflow.core.pytestflow_states import PyTestflowDone
+
+
+@step(name="greet")
+def greet(user: str) -> PyTestflowDone:
+    print(f"Hello {user}")
+    return PyTestflowDone(ptf_result={"step_status": "done", "output": user})
+```
+
+If `user` is not provided explicitly, the decorator will look for
+`ptf_context.locals["user"]` or `ptf_context.globals["user"]`.
+
+Specialized decorators like `@numeric_limit_step` or `@action_step` rely on this
+core wrapper and simply post-process the return value into the appropriate
+`PyTestflowState` subclass.
+
+## Sequences as flows
+
+Steps execute through the `Sequence` and `TestSequence` classes, both declared as
+Prefect flows. A `Sequence` runs an ordered list of steps, manages context scope,
+and aggregates child `PyTestflowState` instances. `TestSequence` extends this
+behavior with setup/main/cleanup sections.
+
+```python
+from pytestflow.core import Sequence, step
+
+
+@step(name="measure")
+def measure():
+    return 42
+
+
+seq = Sequence("demo", [measure])
+state = seq.run()
+```
+
+Sequences accept `default_parameters` merged with runtime overrides. Nested
+sequences execute in isolated local namespaces; constructing a subsequence with
+`allow_parent_mutation=True` grants controlled write access to the parent's
+locals via `ptf_context.locals`.
+
+## Process models
+
+Process models inherit from `Sequence` and coordinate the broader UUT lifecycle.
+`SequentialProcessModel` wires callbacks for `pre_uut`, `post_uut`, `report`, and
+`database_logging` around a main sequence and stores intermediate results in
+`ptf_context.locals` for later callbacks.
+
+## State objects
+
+Every step returns a subclass of `PyTestflowState`. The most common ones are:
+
+- `PyTestflowPassed`
+- `PyTestflowFailed`
+- `PyTestflowDone`
+- `PyTestflowError`
+
+Each state carries a `ptf_result` dictionary and optional child states when
+returned from sequences or process models.
+
+```python
+result = seq.run()
+print(result.ptf_result["step_status"])  # sequence_passed/failed
+for name, child in result.children:
+    print(name, child.ptf_result)
+```
+
+Back to [steps documentation](../steps/README.md) or the
+[project README](../../readme.md).

pytestflow/core/__init__.py

@@ -0,0 +1,15 @@
+from .core import step,StepWrapper
+from .context import ptf_context
+from .pytestflow_states import PyTestflowPassed, PyTestflowFailed, PyTestflowDone, PyTestflowError
+from .sequence import Sequence
+
+__all__ = [
+    "step",
+    "StepWrapper",
+    "ptf_context",
+    "PyTestflowPassed",
+    "PyTestflowFailed",
+    "PyTestflowDone",
+    "PyTestflowError",
+    "Sequence",
+]

pytestflow/core/context.py

@@ -0,0 +1,41 @@
+from datetime import datetime
+from collections import defaultdict
+from typing import Any, Dict, List, Optional
+
+
+class TestContext:
+    """Manages local/global variables and step results for test execution."""
+
+    def __init__(self) -> None:
+        self.locals: Dict[str, Any] = {}               # Per-sequence or per-step local vars
+        self.globals: Dict[str, Any] = {}              # Shared across all steps
+        self.results: Dict[str, List[Dict[str, Any]]] = defaultdict(list)  # step_name -> list of result dicts
+        self.this_context: "Context" = self            # Self-ref (TestStand-style)
+        self.contex_created_timestamp: datetime = datetime.now()
+
+    # # The following methods are commented out as they are not used in the current context.
+    # def log_result(self, step_name: str, result_dict: Dict[str, Any]) -> None:
+    #     """Append a structured result to the results dict."""
+    #     self.results[step_name].append(result_dict)
+
+    # def get_last_result(self, step_name: str) -> Optional[Dict[str, Any]]:
+    #     """Get last execution result for a given step."""
+    #     return self.results[step_name][-1] if self.results[step_name] else None
+
+    # def __repr__(self) -> str:
+    #     return (
+    #         f"<Context locals={list(self.locals.keys())} "
+    #         f"globals={list(self.globals.keys())} "
+    #         f"results={len(self.results)}>"
+    #     )
+    # <=== End of commented-out methods ===>  
+
+    def __repr__(self) -> str:
+        return (
+            f"<Context locals={list(self.locals.keys())} "
+            f"globals={list(self.globals.keys())}>"
+        )
+
+
+# Global singleton instance
+ptf_context = TestContext()  # ptf_context = PyTestFlow execution context

pytestflow/core/core.py

@@ -0,0 +1,112 @@
+# core/core.py
+from functools import wraps
+from datetime import datetime
+import uuid
+from prefect import task
+from pytestflow.core.utils import get_data_for_gui, resolve_args
+from pytestflow.core.context import ptf_context  # Import ptf_context for step injection
+
+
+def safe_getattr(obj, attr):
+    """Safe getattr that returns None if attribute is missing or context unavailable."""
+    try:
+        return getattr(obj, attr, None)
+    except Exception:
+        return None
+
+
+class StepWrapper:
+    """
+    A callable wrapper around a user function that integrates with Prefect @task,
+    while capturing runtime metadata (start time, duration, flow/task IDs).
+    Also supports user-supplied additional_info for inclusion in ptf_result.
+    """
+
+    def __init__(self, fn, name=None, autowire=True, **task_kwargs):
+        self.fn = fn
+        self.name = name or fn.__name__
+        self.static_uuid: uuid.UUID | None = None
+        self.autowire = autowire
+        self.task_kwargs = task_kwargs
+
+        # Metadata and additional info
+        self._stepmeta = {}
+        self.additional_info = {}
+
+        # Wrap the function with Prefect's @task
+        self.prefect_task = task(name=self.name, **task_kwargs)(self._run)
+
+    def _run(self, *args, **kwargs):
+        # Reset metadata before every run
+        self._stepmeta = {}
+        self.additional_info = {}
+
+        # Start time
+        start_time = datetime.utcnow()
+
+        # Inject the current step into ptf_context
+        ptf_context.current_step = self
+
+        # Send start to GUI
+        get_data_for_gui(self, start_time)
+
+        try:
+            # Resolve arguments if autowire is enabled
+            if self.autowire:
+                args, kwargs = resolve_args(self.fn, args, kwargs)
+
+            # Execute the original function
+            result = self.fn(*args, **kwargs)
+
+        finally:
+            # Always clear the pointer to avoid leaking across steps
+            ptf_context.current_step = None
+
+        # End time and duration
+        end_time = datetime.utcnow()
+        duration = (end_time - start_time).total_seconds()
+
+        # Collect core metadata
+        self._stepmeta = {
+            "start_time": start_time.isoformat(),
+            "end_time": end_time.isoformat(),
+            "duration_s": duration,
+        }
+
+        return result
+
+    def get_meta_info(self):
+        """Return collected metadata + any user-supplied additional_info."""
+        meta = dict(self._stepmeta) if self._stepmeta else {}
+        if self.additional_info:
+            meta["additional_info"] = dict(self.additional_info)
+        return meta
+
+    def add_additional_info(self, key, value):
+        """Add additional information to the step (will be included in ptf_result)."""
+        self.additional_info[key] = value
+
+    def __call__(self, *args, **kwargs):
+        """Delegate execution to the Prefect task."""
+        return self.prefect_task(*args, **kwargs)
+
+    def __getattr__(self, name):
+        """
+        Delegate attribute access to the Prefect task.
+        This allows the StepWrapper to behave like a Prefect task
+        (e.g., .fn, .name, .submit, etc.).
+        """
+        return getattr(self.prefect_task, name)
+
+
+def step(name=None, autowire=True, **task_kwargs):
+    """
+    Decorator factory that produces a StepWrapper object.
+    Usage:
+        @step(name="my_step")
+        def foo():
+            return 42
+    """
+    def decorator(fn):
+        return StepWrapper(fn, name=name, autowire=autowire, **task_kwargs)
+    return decorator

pytestflow/core/pytestflow_states.py

@@ -0,0 +1,88 @@
+from prefect.states import State
+from pydantic import Field
+from typing import Optional, List, Tuple, Dict
+
+class PyTestflowState(State):
+    """
+    Base class for all PyTestFlow states.
+    Uses `ptf_result` for internal step data and sets Prefect `.data` field
+    to `ptf_result["output"]` if available.
+    """
+    ptf_result: Dict = Field(default_factory=dict)
+    children: Optional[List[Tuple[str, State]]] = Field(default_factory=list)
+
+    def __init__(self, *, ptf_result=None, message=None, children=None, **kwargs):
+        ptf_result = ptf_result or {}
+
+        # Set internal .data result from ptf_result["output"]
+        data: Any = ptf_result.get("output", None)
+        kwargs.setdefault("data", data)  # directly sets self.data
+
+        # Set default type if missing
+        kwargs.setdefault("type", "COMPLETED")
+
+        super().__init__(
+            message=message,
+            **kwargs
+        )
+
+        object.__setattr__(self, "ptf_result", ptf_result)
+        object.__setattr__(self, "children", children or [])
+
+    def add_child(self, name: str, state: State):
+        self.children.append((name, state))
+
+    def summarize(self):
+        return {
+            "name": self.name,
+            "status": self.ptf_result.get("step_status"),
+            "children": [name for name, _ in self.children]
+        }
+
+
+class PyTestflowPassed(PyTestflowState):
+    def __init__(self, ptf_result=None, message="Step passed", children=None, **kwargs):
+        super().__init__(
+            name="Passed",
+            type="COMPLETED",
+            ptf_result=ptf_result,
+            message=message,
+            children=children,
+            **kwargs
+        )
+
+
+class PyTestflowFailed(PyTestflowState):
+    def __init__(self, ptf_result=None, message="Step failed", children=None, **kwargs):
+        super().__init__(
+            name="Failed",
+            type="COMPLETED",
+            ptf_result=ptf_result,
+            message=message,
+            children=children,
+            **kwargs
+        )
+
+
+class PyTestflowDone(PyTestflowState):
+    def __init__(self, ptf_result=None, message="Step done", children=None, **kwargs):
+        super().__init__(
+            name="Done",
+            type="COMPLETED",
+            ptf_result=ptf_result,
+            message=message,
+            children=children,
+            **kwargs
+        )
+
+
+class PyTestflowError(PyTestflowState):
+    def __init__(self, ptf_result=None, message="Unhandled error", children=None, **kwargs):
+        super().__init__(
+            name="Error",
+            type="CRASHED",
+            ptf_result=ptf_result,
+            message=message,
+            children=children,
+            **kwargs
+        )

pytestflow/core/runtime_control.py

@@ -0,0 +1,164 @@
+import threading
+import time
+import uuid
+import asyncio
+import queue
+
+
+class RuntimeControl:
+    def __init__(self, default_throttle_ms: float = 5.0):
+        self._shutdown = False
+        # --- PAUSE / THROTTLE / STOP DOMAIN ---
+        self._lock = threading.Lock()
+        self._resume_condition = threading.Condition(self._lock)
+        self._paused = False
+        self._throttle_ms = max(0.0, float(default_throttle_ms))
+        self._stop_requested = False
+
+        # --- POPUP DOMAIN (another lock) ---
+        self._popup_lock = threading.Lock()
+        self._popup_condition = threading.Condition(self._popup_lock)
+        self._pending_popups = {}  # request_id -> selected
+
+        # GUI update queue for in-process communication (step -> backend)
+        self._gui_update_queue = queue.Queue()
+
+    def shutdown(self):
+        with self._popup_condition:
+            self._shutdown = True
+            self._popup_condition.notify_all()
+
+        with self._resume_condition:
+            self._resume_condition.notify_all()
+
+    # =========================================================
+    # PAUSE / THROTTLE / STOP
+    # =========================================================
+
+    def set_stop_requested(self, stop_requested: bool) -> None:
+        with self._lock:
+            self._stop_requested = bool(stop_requested)
+
+    def set_paused(self, paused: bool) -> None:
+        with self._resume_condition:
+            self._paused = bool(paused)
+            if not self._paused:
+                self._resume_condition.notify_all()
+
+    def is_paused(self) -> bool:
+        with self._lock:
+            return self._paused
+
+    def wait_until_resumed(self) -> None:
+        with self._resume_condition:
+            while self._paused:
+                self._resume_condition.wait(timeout=0.2)
+
+    def set_throttle_ms(self, throttle_ms: float) -> None:
+        with self._lock:
+            self._throttle_ms = max(0.0, float(throttle_ms))
+
+    def get_throttle_ms(self) -> float:
+        with self._lock:
+            return self._throttle_ms
+
+    def get_throttle_seconds(self) -> float:
+        return self.get_throttle_ms() / 1000.0
+
+    def sleep_with_pause(self, delay_seconds: float) -> None:
+        if delay_seconds <= 0:
+            return
+
+        end_time = time.monotonic() + delay_seconds
+        while True:
+            self.wait_until_resumed()
+            remaining = end_time - time.monotonic()
+            if remaining <= 0:
+                break
+            time.sleep(min(remaining, 0.05))
+
+    def checkpoint_before_step(self, step_index: int, apply_throttle: bool = True) -> None:
+        if self._stop_requested:
+            raise RuntimeError("Stop requested")
+
+        self.wait_until_resumed()
+        if apply_throttle and step_index > 0:
+            self.sleep_with_pause(self.get_throttle_seconds())
+        self.wait_until_resumed()
+
+    def snapshot(self) -> dict:
+        with self._lock:
+            return {
+                "paused": self._paused,
+                "throttle_ms": self._throttle_ms,
+                "stop_requested": self._stop_requested
+            }
+
+    # =========================================================
+    # POPUP (lock separato)
+    # =========================================================
+
+    def show_popup(self, popup_data: dict = None) -> dict:
+        request_id = str(uuid.uuid4())
+
+        with self._popup_condition:
+            self._pending_popups[request_id] = None
+
+            payload = {
+                "cmd": "display_modal_popup",
+                "args": {
+                    "request_id": request_id,
+                    "popup_data": popup_data
+                }
+            }
+
+            # Always enqueue payload so backend can deliver it when a GUI connects
+            self.send_gui_update(payload)
+
+            # Also try immediate in-process emit to reach already-connected clients
+            try:
+                import pytestflow.backend.event_bus as _eb
+                if getattr(_eb.event_bus, "loop", None):
+                    print("[RuntimeControl] Enqueued popup and sending immediate in-process event_bus emit")
+                    asyncio.run_coroutine_threadsafe(
+                        _eb.event_bus.emit("outbound", payload),
+                        _eb.event_bus.loop
+                    )
+            except Exception as e:
+                print("[RuntimeControl] immediate event_bus emit failed (will rely on queue). Error:", e)
+
+            while self._pending_popups.get(request_id) is None and not self._shutdown:
+                self._popup_condition.wait(timeout=0.2)
+
+            if self._shutdown:
+                self._pending_popups.pop(request_id, None)
+                raise RuntimeError("Shutdown requested")
+
+            return self._pending_popups.pop(request_id)
+
+    def set_popup_response(self, request_id, button_pressed, response_text=None):
+        with self._popup_condition:
+            if request_id in self._pending_popups:
+                self._pending_popups[request_id] = {
+                    "button": button_pressed,
+                    "text": response_text
+                }
+                self._popup_condition.notify_all()
+
+    # GUI update queue API
+    def send_gui_update(self, update_data: dict) -> None:
+        """Called by steps/other threads to enqueue a GUI update payload."""
+        self._gui_update_queue.put(update_data)
+
+    def get_gui_update(self, timeout: float = 0.5):
+        """Called by backend consumer (in executor) to dequeue a GUI update.
+
+        Returns the update dict or None if timeout expires.
+        """
+        try:
+            return self._gui_update_queue.get(timeout=timeout)
+        except queue.Empty:
+            return None
+
+
+runtime_control = RuntimeControl()

pytestflow/core/seq_file_runner.py

@@ -0,0 +1,38 @@
+import importlib.util
+import sys
+from pathlib import Path
+from prefect import flow
+from prefect.context import get_run_context
+from pytestflow.config.config_manager import ConfigManager
+
+config = ConfigManager()
+process_models_dir = config.get_path("process_models")
+
+def load_process_model(process_models_dir: str, model_name: str):
+    file_path = Path(process_models_dir) / f"{model_name}.py"
+
+    spec = importlib.util.spec_from_file_location(
+        f"user_{model_name}",
+        file_path
+    )
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[f"user_{model_name}"] = module
+    spec.loader.exec_module(module)
+
+    return module.PROCESS_MODEL
+
+
+@flow()
+def run_sequence_file(process_model_callbacks, model_name):
+    # Following line are because we cannot do @flow(name=test_sequence.name)
+    ctx = get_run_context()
+
+    ctx.flow_run.name = process_model_callbacks["main_sequence"].name
+
+    my_proc_model = load_process_model(process_models_dir, model_name)
+
+    process_model = my_proc_model(
+        name=process_model_callbacks["main_sequence"].name,
+        callbacks=process_model_callbacks
+    )
+    return process_model.run(return_state=True)