techui-builder 0.5.2a2__py3-none-any.whl

techui_builder/__init__.py

@@ -0,0 +1,16 @@
+"""Top level API.
+
+.. data:: __version__
+    :type: str
+
+    Version number as calculated by poetry-dynamic-versioning
+"""
+
+from techui_builder.builder import Builder
+
+from ._version import __version__
+
+__all__ = [
+    "__version__",
+    "Builder",
+]

techui_builder/__main__.py

@@ -0,0 +1,179 @@
+"""Interface for ``python -m techui_builder``."""
+
+import logging
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.logging import RichHandler
+
+from techui_builder import __version__
+from techui_builder.autofill import Autofiller
+from techui_builder.builder import Builder
+from techui_builder.schema_generator import schema_generator
+
+app = typer.Typer(
+    pretty_exceptions_show_locals=False,
+    help="""
+    A script for building Phoebus GUIs.
+
+    This is the required file structure:\n
+\n
+    ixx-services\n
+    |-- services\n
+    |   |-- blxxi-ea-device-01\n
+    |   |   `-- config\n
+    |   |       `-- ioc.yaml\n
+    |   |-- ...\n
+    |   `-- blxxi-va-device-01\n
+    |       `-- config\n
+    |           `-- ioc.yaml\n
+    `-- synoptic\n
+    .   |-- techui-support/\n
+    |   |   `-- ...\n
+    .   |-- techui.yaml\n
+    .   `-- index.bob\n
+""",
+)
+
+default_bobfile = "index.bob"
+
+
+def version_callback(value: bool):
+    if value:
+        print(f"techui-builder version: {__version__}")
+        raise typer.Exit()
+
+
+def schema_callback(value: bool):
+    if value:
+        schema_generator()
+        raise typer.Exit()
+
+
+def log_level(level: str):
+    logging.basicConfig(
+        level=level,
+        format="%(message)s",
+        handlers=[RichHandler(omit_repeated_times=False, markup=True)],
+    )
+
+
+# This is the default behaviour when no command provided
+@app.callback(invoke_without_command=True)
+def main(
+    filename: Annotated[Path, typer.Argument(help="The path to techui.yaml")],
+    bobfile: Annotated[
+        Path | None,
+        typer.Argument(help="Override for template bob file location."),
+    ] = None,
+    version: Annotated[
+        bool | None, typer.Option("--version", callback=version_callback)
+    ] = None,
+    loglevel: Annotated[
+        str,
+        typer.Option(
+            "--log-level",
+            help="Set log level to INFO, DEBUG, WARNING, ERROR or CRITICAL",
+            case_sensitive=False,
+            callback=log_level,
+        ),
+    ] = "INFO",
+    schema: Annotated[
+        bool | None,
+        typer.Option(
+            "--schema",
+            help="Generate schema for validating techui and ibek-mapping yaml files",
+            callback=schema_callback,
+        ),
+    ] = None,
+) -> None:
+    """Default function called from cmd line tool."""
+
+    logger_ = logging.getLogger(__name__)
+
+    bob_file = bobfile
+
+    gui = Builder(techui=filename)
+
+    # Get the relative path to the techui file from working dir
+    abs_path = filename.absolute()
+    logger_.debug(f"techui.yaml absolute path: {abs_path}")
+
+    # Get the current working dir
+    cwd = Path.cwd()
+    logger_.debug(f"Working directory: {cwd}")
+
+    # Get the relative path of ixx-services to techui.yaml
+    ixx_services_dir = next(
+        (
+            ixx_services.relative_to(cwd, walk_up=True)
+            for parent in abs_path.parents
+            for ixx_services in parent.glob(f"{gui.conf.beamline.short_dom}-services")
+        ),
+        None,
+    )
+    if ixx_services_dir is None:
+        logging.critical("ixx-services not found. Is you file structure correct?")
+        exit()
+    logger_.debug(f"ixx-services relative path: {ixx_services_dir}")
+
+    # Get the synoptic dir relative to the parent dir
+    synoptic_dir = ixx_services_dir.joinpath("synoptic")
+    logger_.debug(f"synoptic relative path: {synoptic_dir}")
+
+    if bob_file is None:
+        # Search default relative dir to techui filename
+        # There will only ever be one file, but if not return None
+        bob_file = next(
+            synoptic_dir.glob("index.bob"),
+            None,
+        )
+        if bob_file is None:
+            logging.critical(
+                f"Source bob file '{default_bobfile}' not found in \
+{synoptic_dir}. Does it exist?"
+            )
+            exit()
+    elif not bob_file.exists():
+        logging.critical(f"Source bob file '{bob_file}' not found. Does it exist?")
+        exit()
+
+    logger_.debug(f"bob file: {bob_file}")
+
+    # # Overwrite after initialised to make sure this is picked up
+    gui._services_dir = ixx_services_dir.joinpath("services")  # noqa: SLF001
+    gui._write_directory = synoptic_dir  # noqa: SLF001
+
+    logger_.debug(
+        f"""
+
+Builder created for {gui.conf.beamline.short_dom}.
+Services directory: {gui._services_dir}
+Write directory: {gui._write_directory}
+""",  # noqa: SLF001
+    )
+
+    gui.setup()
+    gui.create_screens()
+
+    logger_.info(f"Screens generated for {gui.conf.beamline.short_dom}.")
+
+    autofiller = Autofiller(bob_file)
+    autofiller.read_bob()
+    autofiller.autofill_bob(gui)
+
+    dest_bob = gui._write_directory.joinpath("index.bob")  # noqa: SLF001
+
+    autofiller.write_bob(dest_bob)
+
+    logger_.info(f"Screens autofilled for {gui.conf.beamline.short_dom}.")
+
+    gui.write_json_map(synoptic=dest_bob, dest=gui._write_directory)  # noqa: SLF001
+    logger_.info(
+        f"Json map generated for {gui.conf.beamline.short_dom} (from index.bob)"
+    )
+
+
+if __name__ == "__main__":
+    app()

techui_builder/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.5.2a2'
+__version_tuple__ = version_tuple = (0, 5, 2, 'a2')
+
+__commit_id__ = commit_id = None

techui_builder/autofill.py

@@ -0,0 +1,102 @@
+import logging
+import os
+from collections import defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from lxml import objectify
+from lxml.objectify import ObjectifiedElement
+
+from techui_builder.builder import Builder, _get_action_group
+from techui_builder.models import Component
+from techui_builder.utils import read_bob
+
+logger_ = logging.getLogger(__name__)
+
+
+@dataclass
+class Autofiller:
+    path: Path
+    macros: list[str] = field(default_factory=lambda: ["prefix", "desc", "file"])
+    widgets: dict[str, ObjectifiedElement] = field(
+        default_factory=defaultdict, init=False, repr=False
+    )
+
+    def read_bob(self) -> None:
+        self.tree, self.widgets = read_bob(self.path)
+
+    def autofill_bob(self, gui: "Builder"):
+        # Get names from component list
+
+        for symbol_name, child in self.widgets.items():
+            # If the name exists in the component list
+            if symbol_name in gui.conf.components.keys():
+                # Get first copy of component (should only be one)
+                comp = next(
+                    (comp for comp in gui.conf.components if comp == symbol_name),
+                )
+
+                self.replace_content(
+                    widget=child,
+                    component_name=comp,
+                    component=gui.conf.components[comp],
+                )
+
+                # Add option to allow left mouse click to run action
+                child["run_actions_on_mouse_click"] = "true"
+
+    def write_bob(self, filename: Path):
+        # Check if data/ dir exists and if not, make it
+        data_dir = filename.parent
+        if not data_dir.exists():
+            os.mkdir(data_dir)
+
+        # Remove any unnecessary xmlns:py and py:pytype metadata from tags
+        objectify.deannotate(self.tree, cleanup_namespaces=True)
+
+        self.tree.write(
+            filename,
+            pretty_print=True,
+            encoding="utf-8",
+            xml_declaration=True,
+        )
+        logger_.debug(f"Screen filled for {filename}")
+
+    def replace_content(
+        self,
+        widget: ObjectifiedElement,
+        component_name: str,
+        component: Component,
+    ):
+        for macro in self.macros:
+            # Get current component attribute
+            component_attr = getattr(component, macro)
+
+            # Fix to make sure widget is reverted back to widget that was passed in
+            current_widget = widget
+            match macro:
+                case "prefix":
+                    tag_name = "pv_name"
+                    component_attr += ":DEVSTA"
+                case "desc":
+                    tag_name = "description"
+                    current_widget = _get_action_group(widget)
+                    if component_attr is None:
+                        component_attr = component_name
+                case "file":
+                    tag_name = "file"
+                    current_widget = _get_action_group(widget)
+                    if component_attr is None:
+                        component_attr = f"{component_name}.bob"
+                case _:
+                    raise ValueError("The provided macro type is not supported.")
+
+            if current_widget is None:
+                logger_.debug(
+                    f"Skipping replace_content for {component_name} as no action\
+ group found"
+                )
+                continue
+
+            # Set component's tag text to the corresponding widget tag
+            current_widget[tag_name] = component_attr

techui_builder/builder.py

@@ -0,0 +1,346 @@
+import json
+import logging
+import os
+from collections import defaultdict
+from dataclasses import _MISSING_TYPE, dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+from lxml import etree, objectify
+from lxml.objectify import ObjectifiedElement
+
+from techui_builder.generate import Generator
+from techui_builder.models import Entity, TechUi
+from techui_builder.validator import Validator
+
+logger_ = logging.getLogger(__name__)
+
+
+@dataclass
+class JsonMap:
+    file: str
+    exists: bool = True
+    duplicate: bool = False
+    children: list["JsonMap"] = field(default_factory=list)
+    macros: dict[str, str] = field(default_factory=dict)
+    error: str = ""
+
+
+@dataclass
+class Builder:
+    """
+    This class provides the functionality to process the required
+    techui.yaml file into screens mapped from ioc.yaml and
+    *-mapping.yaml files.
+
+    By default it looks for a `techui.yaml` file in the same dir
+    of the script Guibuilder is called in. Optionally a custom path
+    can be declared.
+
+    """
+
+    techui: Path = field(default=Path("techui.yaml"))
+
+    entities: defaultdict[str, list[Entity]] = field(
+        default_factory=lambda: defaultdict(list), init=False
+    )
+    _services_dir: Path = field(init=False, repr=False)
+    _gui_map: dict = field(init=False, repr=False)
+    _write_directory: Path = field(default=Path("opis"), init=False, repr=False)
+
+    def __post_init__(self):
+        # Populate beamline and components
+        self.conf = TechUi.model_validate(
+            yaml.safe_load(self.techui.read_text(encoding="utf-8"))
+        )
+
+    def setup(self):
+        """Run intial setup, e.g. extracting entries from service ioc.yaml."""
+        self._extract_services()
+        synoptic_dir = self._write_directory
+
+        self.clean_files()
+
+        self.generator = Generator(synoptic_dir, self.conf.beamline.url)
+
+    def clean_files(self):
+        exclude = {"index.bob"}
+        bobs = [
+            bob
+            for bob in self._write_directory.glob("*.bob")
+            if bob.name not in exclude
+        ]
+
+        self.validator = Validator(bobs)
+        self.validator.check_bobs()
+
+        # Get bobs that are only present in the bobs list (i.e. generated)
+        self.generated_bobs = list(set(bobs) ^ set(self.validator.validate.values()))
+
+        logger_.info("Preserving edited screens for validation.")
+        logger_.debug(f"Screens to validate: {list(self.validator.validate.keys())}")
+
+        logger_.info("Cleaning synoptic/ of generated screens.")
+
+        try:
+            # Find the JsonMap file
+            json_map_file = next(self._write_directory.glob("JsonMap.json"))
+            # If it exists, we want to remove it too
+            generated_files = [*self.generated_bobs, json_map_file]
+        except StopIteration:
+            generated_files = self.generated_bobs
+
+        # Remove any generated files that exist
+        for file_ in generated_files:
+            logger_.debug(f"Removing generated file: {file_.name}")
+            os.remove(file_)
+
+    def _extract_services(self):
+        """
+        Finds the services folders in the services directory
+        and extracts all entites
+        """
+
+        # Loop over every dir in services, ignoring anything that isn't a service
+        for service in self._services_dir.glob(f"{self.conf.beamline.long_dom}-*-*-*"):
+            # If service doesn't exist, file open will fail throwing exception
+            try:
+                self._extract_entities(ioc_yaml=service.joinpath("config/ioc.yaml"))
+            except OSError:
+                logger_.error(
+                    f"No ioc.yaml file for service: [bold]{service.name}[/bold]. \
+Does it exist?"
+                )
+
+    def _extract_entities(self, ioc_yaml: Path):
+        """
+        Extracts the entries in ioc.yaml matching the defined prefix
+        """
+
+        with open(ioc_yaml) as ioc:
+            ioc_conf: dict[str, list[dict[str, str]]] = yaml.safe_load(ioc)
+            for entity in ioc_conf["entities"]:
+                if "P" in entity.keys():
+                    # Create Entity and append to entity list
+                    new_entity = Entity(
+                        type=entity["type"],
+                        desc=entity.get("desc", None),
+                        P=entity["P"],
+                        M=None if (val := entity.get("M")) is None else val,
+                        R=None if (val := entity.get("R")) is None else val,
+                    )
+                    self.entities[new_entity.P].append(new_entity)
+
+    def _generate_screen(self, screen_name: str):
+        self.generator.build_screen(screen_name)
+        self.generator.write_screen(screen_name, self._write_directory)
+
+    def _validate_screen(self, screen_name: str):
+        # Get the generated widgets to validate against
+        widgets = self.generator.widgets
+        widget_group = self.generator.group
+        assert widget_group is not None
+        widget_group_name = widget_group.get_element_value("name")
+        self.validator.validate_bob(screen_name, widget_group_name, widgets)
+
+    def create_screens(self):
+        """Create the screens for each component in techui.yaml"""
+        if len(self.entities) == 0:
+            logger_.critical("No ioc entities found, has setup() been run?")
+            exit()
+
+        # Loop over every component defined in techui.yaml and locate
+        # any extras defined
+        for component_name, component in self.conf.components.items():
+            screen_entities: list[Entity] = []
+            # ONLY IF there is a matching component and entity, generate a screen
+            if component.prefix in self.entities.keys():
+                screen_entities.extend(self.entities[component.prefix])
+                if component.extras is not None:
+                    # If component has any extras, add them to the entries to generate
+                    for extra_p in component.extras:
+                        if extra_p not in self.entities.keys():
+                            logger_.error(
+                                f"Extra prefix {extra_p} for {component_name} does not \
+exist."
+                            )
+                            continue
+                        screen_entities.extend(self.entities[extra_p])
+
+                # This is used by both generate and validate,
+                # so called beforehand for tidyness
+                self.generator.build_widgets(component_name, screen_entities)
+                self.generator.build_groups(component_name)
+
+                screens_to_validate = list(self.validator.validate.keys())
+
+                if component_name in screens_to_validate:
+                    self._validate_screen(component_name)
+                else:
+                    self._generate_screen(component_name)
+
+            else:
+                logger_.warning(
+                    f"{self.techui.name}: The prefix [bold]{component.prefix}[/bold]\
+ set in the component [bold]{component_name}[/bold] does not match any P field in the\
+ ioc.yaml files in services"
+                )
+
+    def _generate_json_map(
+        self, screen_path: Path, dest_path: Path, visited: set[Path] | None = None
+    ) -> JsonMap:
+        def _get_macros(element: ObjectifiedElement):
+            if hasattr(element, "macros"):
+                macros = element.macros.getchildren()
+                if macros is not None:
+                    return {
+                        str(macro.tag): macro.text
+                        for macro in macros
+                        if macro.text is not None
+                    }
+            return {}
+
+        if visited is None:
+            visited = set()
+
+        current_node = JsonMap(str(screen_path.relative_to(self._write_directory)))
+
+        abs_path = screen_path.absolute()
+        dest_path = dest_path
+        if abs_path in visited:
+            current_node.exists = True
+            current_node.duplicate = True
+            return current_node
+        visited.add(abs_path)
+
+        try:
+            tree = objectify.parse(abs_path)
+            root: ObjectifiedElement = tree.getroot()
+
+            # Find all <widget> elements
+            widgets = [
+                w
+                for w in root.findall(".//widget")
+                if w.get("type", default=None)
+                # in ["symbol", "embedded", "action_button"]
+                in ["symbol", "action_button"]
+            ]
+
+            for widget_elem in widgets:
+                # Obtain macros associated with file_elem
+                macro_dict: dict[str, str] = {}
+                widget_type = widget_elem.get("type", default=None)
+
+                match widget_type:
+                    case "symbol" | "action_button":
+                        open_display = _get_action_group(widget_elem)
+                        if open_display is None:
+                            continue
+                        file_elem = open_display.file
+
+                        macro_dict = _get_macros(open_display)
+                    # case "embedded":
+                    #     file_elem = widget_elem.file
+                    #     macro_dict = _get_macros(widget_elem)
+                    case _:
+                        continue
+
+                # Extract file path from file_elem
+                file_path = Path(file_elem.text.strip() if file_elem.text else "")
+                # If file is already a .bob file, skip it
+                if not file_path.suffix == ".bob":
+                    continue
+
+                # TODO: misleading var name?
+                next_file_path = dest_path.joinpath(file_path)
+
+                # Crawl the next file
+                if next_file_path.is_file():
+                    # TODO: investigate non-recursive approaches?
+                    child_node = self._generate_json_map(
+                        next_file_path, dest_path, visited
+                    )
+                else:
+                    child_node = JsonMap(str(file_path), exists=False)
+
+                child_node.macros = macro_dict
+                # TODO: make this work for only list[JsonMap]
+                assert isinstance(current_node.children, list)
+                # TODO: fix typing
+                current_node.children.append(child_node)
+
+        except etree.ParseError as e:
+            current_node.error = f"XML parse error: {e}"
+        except Exception as e:
+            current_node.error = str(e)
+
+        return current_node
+
+    def write_json_map(
+        self,
+        synoptic: Path = Path("example/t01-services/synoptic/index.bob"),
+        dest: Path = Path("example/t01-services/synoptic"),
+    ):
+        """
+        Maps the valid entries from the ioc.yaml file
+        to the required screen in *-mapping.yaml
+        """
+        if not synoptic.exists():
+            raise FileNotFoundError(
+                f"Cannot generate json map for {synoptic}. Has it been generated?"
+            )
+
+        map = self._generate_json_map(synoptic, dest)
+        with open(dest.joinpath("JsonMap.json"), "w") as f:
+            f.write(
+                json.dumps(map, indent=4, default=lambda o: _serialise_json_map(o))
+                + "\n"
+            )
+
+
+# Function to convert the JsonMap objects into dictionaries,
+# while ignoring default values
+def _serialise_json_map(map: JsonMap) -> dict[str, Any]:
+    def _check_default(key: str, value: Any):
+        # Is a default factory used? (e.g. list, dict, ...)
+        if not isinstance(
+            JsonMap.__dataclass_fields__[key].default_factory, _MISSING_TYPE
+        ):
+            # If so, check if value is the same as default factory
+            default = JsonMap.__dataclass_fields__[key].default_factory()
+        else:
+            # If not, check if value is the default value
+            default = JsonMap.__dataclass_fields__[key].default
+        return value == default
+
+    d = {}
+
+    # Loop over everything in the json map object's dictionary
+    for key, val in map.__dict__.items():
+        # If children has nested JsonMap object, serialise that too
+        if key == "children" and len(val) > 0:
+            val = [_serialise_json_map(v) for v in val]
+
+        # only include any items if they are not the default value
+        if _check_default(key, val):
+            continue
+
+        d[key] = val
+
+    return d
+
+
+# File and desc are under the "actions",
+# so the corresponding tag needs to be found
+def _get_action_group(element: ObjectifiedElement) -> ObjectifiedElement | None:
+    try:
+        actions = element.actions
+        assert actions is not None
+        for action in actions.iterchildren("action"):
+            if action.get("type", default=None) == "open_display":
+                return action
+        return None
+    except AttributeError:
+        # TODO: Find better way of handling there being no "actions" group
+        logger_.error(f"Actions group not found in component: {element.text}")