pycontrol-core 3.0.0b2__tar.gz → 3.0.0b3__tar.gz

{pycontrol_core-3.0.0b2 → pycontrol_core-3.0.0b3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pycontrol-core
-Version: 3.0.0b2
+Version: 3.0.0b3
 Summary: Sans-IO host library for the pyControl behavioural-experiment framework.
 Project-URL: Homepage, https://github.com/pyControl/core
 Author: pyControl contributors

{pycontrol_core-3.0.0b2 → pycontrol_core-3.0.0b3}/docs/changelog.md

@@ -2,6 +2,13 @@
 
 ## Unreleased
 
+### Styled status text
+
+- `TaskHandler.update_status(...)` accepts a `StyledText(*parts)` value, drawn
+  as text whose `Span(text, color=None, bold=False)` parts are coloured or bold.
+  Its `StatusField` has `kind == "styled"` and the spans in the new `spans`
+  attribute; `value` is still the plain text.
+
 ### Breakout naming
 
 - Breakout filenames and classes now identify port count, PCB revision, and

{pycontrol_core-3.0.0b2 → pycontrol_core-3.0.0b3}/docs/public-api.md

@@ -39,7 +39,9 @@ from pycontrol.addons import (
     Log,
     Print,
     Progress,
+    Span,
     State,
+    StyledText,
     TaskHandler,
     Var,
 )
@@ -47,8 +49,9 @@ from pycontrol.addons import (
 
 See `docs/task-handlers.md`. A task handler publishes frontend status with
 `update_status(...)` (a mapping of labels to values, where a `Progress` value
-draws a bar) and reports problems with the diagnostics helpers; it does not
-reach into the subscriber registry. Its `set_variable()` and `trigger_event()`
+draws a bar and a `StyledText` value draws coloured or bold `Span`s) and
+reports problems with the diagnostics helpers; it does not reach into the
+subscriber registry. Its `set_variable()` and `trigger_event()`
 are recorded with source `task_handler`.
 
 ### Experiment handlers
@@ -109,6 +112,7 @@ from pycontrol.bus import (
     SessionEnded,
     SessionEndReason,
     SessionStarted,
+    Span,
     StatusField,
     Subscriber,
     TaskStatusUpdated,
@@ -126,10 +130,11 @@ A subscriber implements any of `on_session_start`, `on_data`,
 `TaskStatusUpdated` is emitted by host-side task handlers through
 `TaskHandler.update_status(...)` and forwarded through the normal subscriber
 registry. Its `fields` are `StatusField` records (`label`, `value`, `kind`,
-`fraction`, `fill_color`, `text_color`). `value` is always a display string, so a
+`fraction`, `fill_color`, `text_color`, `spans`). `value` is always a display string, so a
 consumer that only handles `kind == "text"` renders every field correctly; a
-field is `kind == "progress"` when the task handler passed a `Progress` value.
-`clean_color` is the colour check frontends apply before styling a bar.
+field is `kind == "progress"` when the task handler passed a `Progress` value,
+and `kind == "styled"`, with its `Span`s in `spans`, for a `StyledText` value.
+`clean_color` is the colour check frontends apply before styling a bar or span.
 
 `SessionEnded.reason` (a `SessionEndReason` literal: `"stopped"`,
 `"task_ended"`, `"task_error"`, `"connection_lost"`, `"pump_crashed"`) is the

{pycontrol_core-3.0.0b2 → pycontrol_core-3.0.0b3}/docs/task-handlers.md

@@ -214,6 +214,16 @@ class WaterBudget(TaskHandler):
         })
 ```
 
+A `StyledText` value is drawn as text with coloured or bold runs. Each part is a
+plain string or a `Span(text, color=None, bold=False)`, with colours checked like
+`Progress`'s:
+
+```python
+from pycontrol.addons import Span, StyledText
+
+self.update_status({"Side": StyledText("last: ", Span("L", color="#FF9A00", bold=True))})
+```
+
 Every field also carries a plain display string, so a frontend that only renders
 text still shows the value, and the run bundle records `label: "0.75 / 1.50 mL"`
 either way.

{pycontrol_core-3.0.0b2 → pycontrol_core-3.0.0b3}/src/pycontrol/__init__.py

@@ -1,5 +1,5 @@
 """pycontrol host library: sans-IO core + addon points."""
 
-__version__ = "3.0.0b2"
+__version__ = "3.0.0b3"
 
 __all__ = ["__version__"]

{pycontrol_core-3.0.0b2 → pycontrol_core-3.0.0b3}/src/pycontrol/addons/__init__.py

@@ -5,6 +5,8 @@ A minimal, Qt-free contract for user code to plug into a session:
 - :class:`TaskHandler` -- subscriber base that converts native row batches
   into ergonomic ``State``/``Event``/``Var``/``Analog`` namedtuples.
 - :class:`Progress` -- a live status value a frontend draws as a progress bar.
+- :class:`StyledText` and :class:`Span` -- a live status value drawn as text
+  with coloured or bold runs.
 - :class:`ExperimentHandler` -- host-side experiment lifecycle callbacks.
 - :class:`TaskControlsContext` -- Qt-free runtime API passed to custom task
   controls built by a frontend.
@@ -29,7 +31,7 @@ from pycontrol.addons.loader import (
     loaded_module_for_path,
 )
 from pycontrol.addons.task_api import Analog, Event, Log, Print, State, TaskHandler, Var
-from pycontrol.bus.status import Progress
+from pycontrol.bus.status import Progress, Span, StyledText
 
 __all__ = [
     "AddonDiscoveryFailure",
@@ -40,7 +42,9 @@ __all__ = [
     "Log",
     "Print",
     "Progress",
+    "Span",
     "State",
+    "StyledText",
     "TaskControlsContext",
     "TaskControlsDefinition",
     "TaskControlsWidgetBuilder",

{pycontrol_core-3.0.0b2 → pycontrol_core-3.0.0b3}/src/pycontrol/bus/__init__.py

@@ -16,7 +16,7 @@ from pycontrol.bus.events import (
     TaskStatusUpdated,
     Warning,
 )
-from pycontrol.bus.status import Progress, StatusField, clean_color, normalise_status_fields
+from pycontrol.bus.status import Progress, Span, StatusField, StyledText, clean_color, normalise_status_fields
 from pycontrol.bus.subscriber import Subscriber, SubscriberRegistry
 
 __all__ = [
@@ -28,7 +28,9 @@ __all__ = [
     "SessionEndReason",
     "SessionEnded",
     "SessionStarted",
+    "Span",
     "StatusField",
+    "StyledText",
     "Subscriber",
     "SubscriberRegistry",
     "TaskStatusUpdated",

{pycontrol_core-3.0.0b2 → pycontrol_core-3.0.0b3}/src/pycontrol/bus/status.py

@@ -4,7 +4,8 @@ A task handler publishes a snapshot as a plain mapping of label to value.
 Values are normalised here into :class:`StatusField` records so every frontend
 renders the same thing, and so a richer field kind (a progress bar) can travel
 on the bus without breaking a consumer that only understands text: ``value`` is
-always the display string, whatever the kind.
+always the display string, whatever the kind. Richer kinds are a progress bar
+and styled text with coloured or bold spans.
 """
 
 from __future__ import annotations
@@ -16,6 +17,7 @@ from typing import Any
 
 TEXT = "text"
 PROGRESS = "progress"
+STYLED = "styled"
 
 # Frontends may paste these into a stylesheet, so only simple colour forms pass.
 _COLOR_RE = re.compile(
@@ -42,6 +44,34 @@ class Progress:
     text_color: str | None = None
 
 
+@dataclass(frozen=True, slots=True)
+class Span:
+    """One run of :class:`StyledText`: ``text`` drawn in ``color``, optionally bold.
+
+    ``color`` is a CSS colour like :class:`Progress`'s; anything else is ignored.
+    """
+
+    text: str
+    color: str | None = None
+    bold: bool = False
+
+
+@dataclass(frozen=True, slots=True, init=False)
+class StyledText:
+    """A status value a frontend renders as text with coloured or bold runs.
+
+    Each part is a plain string or a :class:`Span`::
+
+        StyledText("Block ", Span("L", color="#FF9A00", bold=True))
+    """
+
+    spans: tuple[Span, ...]
+
+    def __init__(self, *parts: str | Span) -> None:
+        spans = tuple(part if isinstance(part, Span) else Span(str(part)) for part in parts)
+        object.__setattr__(self, "spans", spans)
+
+
 @dataclass(frozen=True, slots=True)
 class StatusField:
     """One normalised field of a live status snapshot."""
@@ -52,6 +82,7 @@ class StatusField:
     fraction: float | None = None
     fill_color: str | None = None
     text_color: str | None = None
+    spans: tuple[Span, ...] = ()
 
 
 def normalise_status_fields(status: Mapping[str, Any]) -> tuple[StatusField, ...]:
@@ -74,6 +105,8 @@ def clean_color(color: object) -> str | None:
 def _status_field(label: str, value: Any) -> StatusField:
     if isinstance(value, Progress):
         return _progress_field(label, value)
+    if isinstance(value, StyledText):
+        return _styled_field(label, value)
     return StatusField(label=label, value="" if value is None else str(value))
 
 
@@ -97,10 +130,25 @@ def _progress_field(label: str, progress: Progress) -> StatusField:
     )
 
 
+def _styled_field(label: str, styled: StyledText) -> StatusField:
+    spans = tuple(Span(str(span.text), clean_color(span.color), bool(span.bold)) for span in styled.spans)
+    return StatusField(label=label, value="".join(span.text for span in spans), kind=STYLED, spans=spans)
+
+
 def _format_number(value: float) -> str:
     if value == int(value):
         return str(int(value))
     return f"{value:.3f}".rstrip("0").rstrip(".")
 
 
-__all__ = ["PROGRESS", "TEXT", "Progress", "StatusField", "clean_color", "normalise_status_fields"]
+__all__ = [
+    "PROGRESS",
+    "STYLED",
+    "TEXT",
+    "Progress",
+    "Span",
+    "StatusField",
+    "StyledText",
+    "clean_color",
+    "normalise_status_fields",
+]

{pycontrol_core-3.0.0b2 → pycontrol_core-3.0.0b3}/src/pycontrol/firmware/pycontrol/framework.py

@@ -6,7 +6,7 @@ from . import state_machine as sm
 from . import hardware as hw
 from . import utility as ut
 
-VERSION = "3.0.0b2"
+VERSION = "3.0.0b3"
 
 
 class FrameworkError(BaseException):  # Exception for pycontrol framework errors.

{pycontrol_core-3.0.0b2 → pycontrol_core-3.0.0b3}/tests/unit/test_status_fields.py

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import pytest
 
-from pycontrol.bus.status import Progress, StatusField, clean_color, normalise_status_fields
+from pycontrol.bus.status import STYLED, Progress, Span, StatusField, StyledText, clean_color, normalise_status_fields
 
 
 def test_plain_values_become_text_fields() -> None:
@@ -71,3 +71,17 @@ def test_a_rejected_color_leaves_the_field_unstyled() -> None:
     [status_field] = normalise_status_fields({"Bar": Progress(1, 2, fill_color="}; evil")})
 
     assert status_field.fill_color is None
+
+
+def test_styled_text_keeps_spans_and_a_plain_display_string() -> None:
+    [status_field] = normalise_status_fields({"Block": StyledText("1X ", Span("L", color="#FF9A00", bold=True))})
+
+    assert status_field.kind == STYLED
+    assert status_field.value == "1X L"
+    assert status_field.spans == (Span("1X "), Span("L", color="#FF9A00", bold=True))
+
+
+def test_styled_text_drops_rejected_span_colors() -> None:
+    [status_field] = normalise_status_fields({"Block": StyledText(Span("L", color="red; } * { x"))})
+
+    assert status_field.spans == (Span("L"),)