techui-builder 0.3.0a1__py3-none-any.whl

techui_builder/generate.py

@@ -0,0 +1,405 @@
+import logging
+import os
+from collections import defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+from lxml import objectify
+from phoebusgen import screen as Screen
+from phoebusgen import widget as Widget
+from phoebusgen.widget.widgets import ActionButton, EmbeddedDisplay, Group
+
+from techui_builder.models import Entity
+
+LOGGER = logging.getLogger(__name__)
+
+
+@dataclass
+class Generator:
+    services_dir: Path = field(repr=False)
+
+    screen_name: str = field(init=False)
+    screen_components: list[Entity] = field(init=False)
+
+    # These are global params for the class (not accessible by user)
+    ibek_map: dict = field(init=False, repr=False)
+    default_size: int = field(default=100, init=False, repr=False)
+    P: str = field(default="P", init=False, repr=False)
+    M: str = field(default="M", init=False, repr=False)
+    R: str = field(default="R", init=False, repr=False)
+    widgets: list[ActionButton | EmbeddedDisplay] = field(
+        default_factory=list[ActionButton | EmbeddedDisplay], init=False, repr=False
+    )
+
+    # Add group padding, and self.widget_x for placing widget in x direction relative to
+    # other widgets, with a widget count to reset the self.widget_x dimension when the
+    # allowed number of horizontal stacks is exceeded.
+    widget_x: int = field(default=0, init=False, repr=False)
+    widget_count: int = field(default=0, init=False, repr=False)
+    group_padding: int = field(default=50, init=False, repr=False)
+
+    def __post_init__(self):
+        self._read_map()
+
+    def _read_map(self):
+        """Read the ibek-mapping.yaml file from techui-support."""
+        ibek_map = self.services_dir.parent.parent.joinpath(
+            "src/techui_support/ibek_mapping.yaml"
+        ).absolute()
+        LOGGER.debug(f"ibek_mapping.yaml location: {ibek_map}")
+
+        with open(ibek_map) as map:
+            self.ibek_map = yaml.safe_load(map)
+
+    def load_screen(self, screen_name: str, screen_components: list[Entity]):
+        self.screen_name = screen_name
+        self.screen_components = screen_components
+
+    def _get_screen_dimensions(self, file: str) -> tuple[int, int]:
+        """
+        Parses the bob files for information on the height
+        and width of the screen
+        """
+        # Read the bob file
+        tree = objectify.parse(file)
+        root = tree.getroot()
+        height_element = root.height
+        if height_element is not None:
+            height = (
+                self.default_size if (val := height_element.text) is None else int(val)
+            )
+        else:
+            height = self.default_size
+            assert "Could not obtain the size of the widget"
+
+        width_element = root.width
+        if width_element is not None:
+            width = (
+                self.default_size if (val := width_element.text) is None else int(val)
+            )
+        else:
+            width = self.default_size
+            assert "Could not obtain the size of the widget"
+
+        return (height, width)
+
+    def _get_widget_dimensions(
+        self, widget: EmbeddedDisplay | ActionButton
+    ) -> tuple[int, int]:
+        """
+        Parses the widget for information on the height
+        and width of the widget
+        """
+        # Read the bob file
+        root = objectify.fromstring(str(widget))
+        height_element = root.height
+        if height_element is not None:
+            height = (
+                self.default_size if (val := height_element.text) is None else int(val)
+            )
+        else:
+            height = self.default_size
+            assert "Could not obtain the size of the widget"
+
+        width_element = root.width
+        if width_element is not None:
+            width = (
+                self.default_size if (val := width_element.text) is None else int(val)
+            )
+        else:
+            width = self.default_size
+            assert "Could not obtain the size of the widget"
+
+        return (height, width)
+
+    def _get_widget_position(
+        self, object: EmbeddedDisplay | ActionButton
+    ) -> tuple[int, int]:
+        """
+        Parses the widget for information on the y
+        and x of the widget
+        """
+        # Read the bob file
+        root = objectify.fromstring(str(object))
+        y_element = root.y
+        if y_element is not None:
+            y = self.default_size if (val := y_element.text) is None else int(val)
+        else:
+            y = self.default_size
+            assert "Could not obtain the size of the widget"
+
+        x_element = root.x
+        if x_element is not None:
+            x = self.default_size if (val := x_element.text) is None else int(val)
+        else:
+            x = self.default_size
+            assert "Could not obtain the size of the widget"
+
+        return (y, x)
+
+    # Make groups
+    def _get_group_dimensions(self, widget_list: list[EmbeddedDisplay | ActionButton]):
+        """
+        Takes in a list of widgets and finds the
+        maximum height in the list
+        """
+        x_list: list[int] = []
+        y_list: list[int] = []
+        height_list: list[int] = []
+        width_list: list[int] = []
+        for widget in widget_list:
+            root = objectify.fromstring(str(widget))
+            x = root.x
+            if x is not None:
+                x_list.append(
+                    self.default_size if (val := x.text) is None else int(val)
+                )
+            else:
+                x_list.append(self.default_size)
+
+            height = root.height
+            if height is not None:
+                height_list.append(
+                    self.default_size if (val := height.text) is None else int(val)
+                )
+            else:
+                height_list.append(self.default_size)
+
+            width = root.width
+            if width is not None:
+                width_list.append(
+                    self.default_size if (val := width.text) is None else int(val)
+                )
+            else:
+                width_list.append(self.default_size)
+
+            y = root.y
+            if y is not None:
+                y_list.append(
+                    self.default_size if (val := y.text) is None else int(val)
+                )
+            else:
+                y_list.append(self.default_size)
+
+        return (
+            max(y_list) + max(height_list) + self.group_padding,
+            max(x_list) + max(width_list) + self.group_padding,
+        )
+
+    def _create_widget(
+        self, component: Entity
+    ) -> EmbeddedDisplay | ActionButton | None:
+        # if statement below is check if the suffix is
+        # missing from the component description. If
+        # not missing, use as name of widget, if missing,
+        # use type as name.
+        if component.M is not None:
+            name: str = component.M
+            suffix: str = component.M
+            suffix_label: str | None = self.M
+        elif component.R is not None:
+            name = component.R
+            suffix = component.R
+            suffix_label = self.R
+        else:
+            name = component.type
+            suffix = ""
+            suffix_label = None
+
+        base_dir = self.services_dir.parent.parent.parent
+
+        # Get the relative path to techui-support
+        support_path = base_dir.joinpath("src/techui_support")
+
+        try:
+            scrn_mapping = self.ibek_map[component.type]
+        except KeyError:
+            LOGGER.warning(
+                f"No available widget for {component.type} in screen \
+{self.screen_name}. Skipping..."
+            )
+            return None
+
+        # Get relative path to screen
+        scrn_path = support_path.joinpath(f"bob/{scrn_mapping['file']}")
+        LOGGER.debug(f"Screen path: {scrn_path}")
+
+        # Path of screen relative to data/ so it knows where to open the file from
+        data_scrn_path = scrn_path.relative_to(
+            self.services_dir.joinpath("synoptic/opis"), walk_up=True
+        )
+
+        # Get dimensions of screen from TechUI repository
+        if scrn_mapping["type"] == "embedded":
+            height, width = self._get_screen_dimensions(str(scrn_path))
+            new_widget = Widget.EmbeddedDisplay(
+                name,
+                str(data_scrn_path),
+                0,
+                0,  # Change depending on the order
+                width,
+                height,
+            )
+            # Add macros to the widgets
+            new_widget.macro(self.P, component.P)
+            if suffix_label is not None:
+                new_widget.macro(f"{suffix_label}", suffix)
+
+        # The only other option is for related displays
+        else:
+            height, width = (40, 100)
+
+            new_widget = Widget.ActionButton(
+                name,
+                component.P,
+                f"{component.P}:{suffix_label}",
+                0,
+                0,
+                width,
+                height,
+            )
+
+            # Add action to action button: to open related display
+            if suffix_label is not None:
+                new_widget.action_open_display(
+                    file=str(data_scrn_path),
+                    target="tab",
+                    macros={
+                        "P": component.P,
+                        f"{suffix_label}": suffix,
+                    },
+                )
+            else:
+                new_widget.action_open_display(
+                    file=str(data_scrn_path),
+                    target="tab",
+                    macros={
+                        "P": component.P,
+                    },
+                )
+
+            # For some reason the version of action buttons is 3.0.0?
+            new_widget.version("2.0.0")
+
+        return new_widget
+
+    def layout_widgets(self, widgets: list[EmbeddedDisplay | ActionButton]):
+        group_spacing: int = 30
+        max_group_height: int = 800
+        spacing_x: int = 20
+        spacing_y: int = 30
+        # Group tiles by size
+        groups: dict[tuple[int, int], list[EmbeddedDisplay | ActionButton]] = (
+            defaultdict(list)
+        )
+        for widget in widgets:
+            key = self._get_widget_dimensions(widget)
+
+            groups[key].append(widget)
+
+        # Sort groups by width (optional)
+        sorted_widgets: list[EmbeddedDisplay | ActionButton] = []
+        sorted_groups = sorted(groups.items(), key=lambda g: g[0][0], reverse=True)
+        current_x: int = 0
+        current_y: int = 0
+        column_width: int = 0
+        column_levels: list[list[EmbeddedDisplay | ActionButton]] = []
+
+        for (h, w), group in sorted_groups:
+            for widget in group:
+                placed = False
+                for level in column_levels:
+                    level_y, _ = self._get_widget_position(level[0])
+                    _, widget_width = self._get_widget_dimensions(widget)
+                    level_width = (
+                        sum(
+                            (self._get_widget_dimensions(t))[1] + spacing_x
+                            for t in level
+                        )
+                        - spacing_x
+                    )  # Find the width of the row
+                    if (
+                        level_y + h <= max_group_height
+                        and level_width + widget_width <= column_width
+                    ):
+                        _, width_1 = self._get_widget_dimensions(level[-1])
+                        _, x_1 = self._get_widget_position(level[-1])
+                        widget.x(x_1 + width_1 + spacing_x)
+                        widget.y(level_y)
+                        level.append(widget)
+                        placed = True
+                        break
+
+                if not placed:
+                    if current_y + h > max_group_height:
+                        # Moves to the next column
+                        current_x += column_width + group_spacing
+                        current_y = 0
+                        column_width = 0
+                        column_levels = []
+                    # Places widgets in rows in one column
+                    widget.x(current_x)
+                    widget.y(current_y)
+                    column_levels.append([widget])
+                    current_y += h + spacing_y
+                    column_width = max(column_width, w)
+                sorted_widgets.append(widget)
+
+        return sorted_widgets
+
+    def build_groups(self):
+        """
+        Create a group to fill with widgets
+        """
+        # Create screen
+        self.screen_ = Screen.Screen(self.screen_name)
+        # Empty widget buffer
+        self.widgets = []
+
+        # create widget and group objects
+
+        # order is an enumeration of the components, used to list them,
+        # and serves as functionality in the math for formatting.
+        for component in self.screen_components:
+            new_widget = self._create_widget(component=component)
+            if new_widget is None:
+                continue
+            self.widgets.append(new_widget)
+
+        if self.widgets == []:
+            # No widgets found, so just back out
+            return
+
+        self.widgets = self.layout_widgets(self.widgets)
+
+        # Create a list of dimensions for the groups
+        # that will be created.
+        height, width = self._get_group_dimensions(self.widgets)
+
+        self.group = Group(
+            self.screen_name,
+            0,
+            0,
+            width,
+            height,
+        )
+
+        self.group.version("2.0.0")
+        self.group.add_widget(self.widgets)
+        self.screen_.add_widget(self.group)
+
+    def write_screen(self, directory: Path):
+        """Write the screen to file"""
+
+        if self.widgets == []:
+            LOGGER.warning(
+                f"Could not write screen: {self.screen_name} \
+as no widgets were available"
+            )
+            return
+
+        if not directory.exists():
+            os.mkdir(directory)
+        self.screen_.write_screen(f"{directory}/{self.screen_name}.bob")
+        LOGGER.info(f"{self.screen_name}.bob has been created successfully")

techui_builder/models.py

@@ -0,0 +1,173 @@
+import logging
+import re
+from typing import Annotated, Literal
+
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    RootModel,
+    StringConstraints,
+    computed_field,
+    field_validator,
+)
+
+LOGGER = logging.getLogger(__name__)
+
+
+# Patterns:
+#   long:  'bl23b'
+#   short: 'b23'   (non-branch)
+#   branch short: 'j23'
+
+
+_DLS_PREFIX_RE = re.compile(
+    r"""
+            ^           # start of string
+            (?=         # lookahead to ensure the following pattern matches
+                [A-Za-z0-9-]{13,16} # match 13 to 16 alphanumeric characters or hyphens
+                [:A-Za-z0-9]* # match zero or more colons or alphanumeric characters
+                [.A-Za-z0-9]  # match a dot or alphanumeric character
+            )
+            (?!.*--)    # negative lookahead to ensure no double hyphens
+            (?!.*:\..)  # negative lookahead to ensure no colon followed by a dot
+            (           # start of capture group 1
+                (?:[A-Za-z0-9]{2,5}-){3} # match 2 to 5 alphanumeric characters followed
+                                    # by a hyphen, repeated 3 times
+                [\d]*   # match zero or more digits
+                [^:]?   # match zero or one non-colon character
+            )
+            (?::([a-zA-Z0-9:]*))? # match zero or one colon followed by zero or more
+                                # alphanumeric characters or colons (capture group 2)
+            (?:\.([a-zA-Z0-9]+))? # match zero or one dot followed by one or more
+                                # alphanumeric characters (capture group 3)
+            $           # end of string
+        """,
+    re.VERBOSE,
+)
+_LONG_DOM_RE = re.compile(r"^[a-z]{2}\d{2}[a-z]$")
+_SHORT_DOM_RE = re.compile(r"^[a-z]\d{2}$")
+_BRANCH_SHORT_DOM_RE = re.compile(r"^[a-z]\d{2}-\d$")
+
+
+class Beamline(BaseModel):
+    dom: str = Field(
+        description="Domain e.g. 'bl23b' (long), 'b23' (short), or 'j23' (branch short)"
+    )
+    desc: str = Field(description="Description")
+    model_config = ConfigDict(extra="forbid")
+
+    @field_validator("dom")
+    @classmethod
+    def normalize_dom(cls, v: str) -> str:
+        v = v.strip().lower()
+        if _LONG_DOM_RE.fullmatch(v):
+            # already long: bl23b
+            return v
+        if _SHORT_DOM_RE.fullmatch(v):
+            # e.g. b23 -> bl23b
+            return f"bl{v[1:3]}{v[0]}"
+        if _BRANCH_SHORT_DOM_RE.fullmatch(v):
+            # e.g. j23 -> bl23j
+            return f"bl{v[1:3]}j"
+        raise ValueError("Invalid dom. Expected long or short")
+
+    @computed_field
+    @property
+    def long_dom(self) -> str:
+        # dom is normalized to long already
+        return self.dom
+
+    @computed_field
+    @property
+    def short_dom(self) -> str:
+        # Convert long -> short form: bl23b -> b23, bl23j -> j23
+        # long form is 'bl' + digits + tail-letter
+        return f"{self.dom[4]}{self.dom[2:4]}"
+
+
+class Component(BaseModel):
+    prefix: str
+    desc: str | None = None
+    extras: list[str] | None = None
+    file: str | None = None
+    model_config = ConfigDict(extra="forbid")
+
+    @field_validator("prefix")
+    @classmethod
+    def _check_prefix(cls, v: str) -> str:
+        if not _DLS_PREFIX_RE.match(v):
+            raise ValueError(f"prefix '{v}' does not match DLS prefix pattern")
+        return v
+
+    @field_validator("extras")
+    @classmethod
+    def _check_extras(cls, v: list[str]) -> list[str]:
+        for p in v:
+            if not _DLS_PREFIX_RE.match(p):
+                raise ValueError(f"extras item '{p}' does not match DLS prefix pattern")
+        # ensure unique (schema enforces too)
+        if len(set(v)) != len(v):
+            raise ValueError("extras must contain unique items")
+        return v
+
+    @computed_field
+    @property
+    def P(self) -> str | None:
+        match = re.match(_DLS_PREFIX_RE, self.prefix)
+        if match:
+            return match.group(1)
+
+    @computed_field
+    @property
+    def R(self) -> str | None:
+        match = re.match(_DLS_PREFIX_RE, self.prefix)
+        if match:
+            return match.group(2)
+
+    @computed_field
+    @property
+    def attribute(self) -> str | None:
+        match = re.match(_DLS_PREFIX_RE, self.prefix)
+        if match:
+            return match.group(3)
+
+
+class TechUi(BaseModel):
+    beamline: Beamline
+    components: dict[str, Component]
+    model_config = ConfigDict(extra="forbid")
+
+
+"""
+Ibek mapping models
+"""
+
+BobPath = Annotated[
+    str, StringConstraints(pattern=r"^(?:[A-Za-z0-9_.-]+/)*[A-Za-z0-9_.-]+\.bob$")
+]
+# Must contain at least one $(NAME) macro
+MacroString = Annotated[
+    str,
+    StringConstraints(pattern=r"^[A-Za-z0-9_:\-./\s\$\(\)]+$"),
+]
+ScreenType = Literal["embedded", "related"]
+
+
+class GuiComponentEntry(BaseModel):
+    file: BobPath
+    prefix: MacroString
+    type: ScreenType
+    model_config = ConfigDict(extra="forbid")
+
+
+class GuiComponents(RootModel[dict[str, GuiComponentEntry]]):
+    pass
+
+
+class Entity(BaseModel):
+    type: str
+    P: str
+    desc: str | None = None
+    M: str | None
+    R: str | None

techui_builder/schema_generator.py

@@ -0,0 +1,28 @@
+from pathlib import Path
+
+import yaml
+
+from techui_builder.models import (
+    GuiComponents,
+    TechUi,
+)
+
+SCHEMAS_DIR = Path("schemas")
+SCHEMAS_DIR.mkdir(exist_ok=True)
+
+
+def write_yaml_schema(model_name: str, schema_dict: dict) -> None:
+    out = SCHEMAS_DIR / f"{model_name}.schema.yml"
+    with out.open("w", encoding="utf-8") as f:
+        yaml.safe_dump(schema_dict, f, sort_keys=False)
+    print(f"✅ Wrote {out}")
+
+
+def schema_generator() -> None:
+    # techui
+    tu = TechUi.model_json_schema()
+    write_yaml_schema("techui", tu)
+
+    # ibek_mapping
+    ibek = GuiComponents.model_json_schema()
+    write_yaml_schema("ibek_mapping", ibek)

techui_builder-0.3.0a1.dist-info/METADATA

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: techui-builder
+Version: 0.3.0a1
+Summary: A package for building Phoebus GUIs
+Author-email: Oliver Copping <oliver.copping@diamond.ac.uk>, Adedamola Sode <adedamola.sode@diamond.ac.uk>, Niamh Dougan <niamh.dougan@diamond.ac.uk>
+Project-URL: GitHub, https://github.com/DiamondLightSource/techui-builder
+Classifier: Development Status :: 3 - Alpha
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <4.0,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pyyaml>=6.0.2
+Requires-Dist: phoebusgen>=3.0.0
+Requires-Dist: lxml>=5.4.0
+Requires-Dist: typer>=0.16.0
+Requires-Dist: rich>=14.1.0
+Requires-Dist: pydantic>=2.11.7
+Dynamic: license-file
+
+[![CI](https://github.com/DiamondLightSource/techui-builder/actions/workflows/ci.yml/badge.svg)](https://github.com/DiamondLightSource/techui-builder/actions/workflows/ci.yml)
+[![Coverage](https://codecov.io/gh/DiamondLightSource/techui-builder/branch/main/graph/badge.svg)](https://codecov.io/gh/DiamondLightSource/techui-builder)
+[![PyPI](https://img.shields.io/pypi/v/techui-builder.svg)](https://pypi.org/project/techui-builder)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
+
+# techui_builder
+
+A package for building Phoebus GUIs
+
+Techui-builder is a module for building and organising phoebus gui screens using a builder-ibek yaml description of an IOC, with a user created create_gui.yaml file containing a description of the screens the user wants to create.
+
+Source          | <https://github.com/DiamondLightSource/techui-builder>
+:---:           | :---:
+PyPI            | `pip install techui-builder`
+Releases        | <https://github.com/DiamondLightSource/techui-builder/releases>
+
+The process to use this module goes as follows (WIP): 
+
+## Requirements
+1. Docker
+2. VSCode
+3. CS-Studio (Phoebus)
+
+## Installation
+1. Clone this module with the `--recursive` flag to pull in [techui-support](git@github.com:DiamondLightSource/techui-support.git). 
+2. Open the project using VSCode.
+3. Reopen the project in a container. Make sure you are using the vscode extension: Dev Containers by Microsoft.
+    
+## Setting Up
+
+> [!WARNING]
+> This module currently only works for `example-synoptic/bl23b-services` - use this directory file structure as a guideline.
+
+1. Add the beamline `ixx-services` repo to your VSCode workspace, ensuring each IOC service has been converted to the [ibek](git@github.com:epics-containers/ibek.git) format:
+    ```
+    |-- ixx-services
+    |   |-- services
+    |   |   |-- $(dom)-my-device-01
+    |   |   |   |-- config
+    |   |   |   |   |-- ioc.yaml
+    ```
+2. Create your handmade synoptic screen in Phoebus and place in `ixx-services/src-bob/$(dom)-synoptic-src.bob`.
+3. Amend any references to `example-synoptic` with the path to your local `ixx-services` - [generate_synoptic.py](example-synoptic/generate_synoptic.py) and [generate.py](src/techui_builder/generate.py).
+4. Construct a `create_gui.yaml` file at the root of `ixx-services` containing all the components from the services:
+
+    ```
+    beamline:
+        dom: {beamline name}
+        desc: {beamline description}
+
+    components:
+        {component name}:
+            desc: {component description}
+            prefix: {PV prefix}
+            extras: 
+                - {extra prefix 1}
+                - {extra prefix 2}
+    ```
+    > [!NOTE] 
+    > `extras` is optional, but allows any embedded screen to be added to make a summary screen e.g. combining all imgs, pirgs and ionps associated with a vacuum space.
+
+## Generating Synoptic
+> [!WARNING]
+> Again, this is hardcoded to work for `example-synoptic/bl23b-services` so amend filepaths accordingly.
+
+`$ python example-synoptic/generate_synoptic.py`
+
+This generates the filled, top level blxxx-synoptic.bob and all component screens inside `ixx-services/services/data`.
+
+## Viewing the Synoptic
+
+```
+$ module load phoebus
+$ phoebus.sh -resource /path/to/blxxx-synoptic.bob
+```