phoebusgen.v4 package

Subpackages

Submodules

phoebusgen.v4.screen module

phoebusgen.screen Module

This module contains a Python class representation of a Phoebus screen. A screen can be created via the Screen class and then widgets from Phoebusgen.widget can be added to the Python screen object. At the end, the screen object can write the XML to a .bob file which can be opened immeditaely into Phoebus

Example:
>>> import phoebusgen.v4.screen
>>> import phoebusgen.v4.widgets
>>> my_screen = phoebusgen.v4.screen.Screen("my screen")
>>> print(my_screen)
<?xml version="1.0" ?>
<display version="2.0.0">
  <name>my screen</name>
</display>

>>> my_widget = phoebusgen.v4.widgets.TextUpdate("test", "test:PV", 10, 10 ,10 ,10)
>>> my_screen.add_widget(my_widget)
>>> print(my_screen)
<?xml version="1.0" ?>
<display version="2.0.0">
  <name>my screen</name>
  <widget type="textupdate" version="2.0.0">
    <name>test</name>
    <x>10</x>
    <y>10</y>
    <width>10</width>
    <height>10</height>
    <pv_name>test:PV</pv_name>
  </widget>
</display>
class phoebusgen.v4.screen.NavigationEdge(source, target, macros=<factory>)

Bases: object

A directed edge in the navigation graph.

macros: Dict[str, str]
source: Path
target: Path
class phoebusgen.v4.screen.NavigationGraph(screens=<factory>, transitions=<factory>)

Bases: object

A graph of screen navigation paths.

Nodes are screen file paths. Edges are transitions between screens, each carrying the macros passed during that transition.

screens: Set[Path]
transitions: List[NavigationEdge]
class phoebusgen.v4.screen.Screen(name=None, f_name=None, overwrite=False)

Bases: HasWidgets, HasPosition, HasBackgroundColor, HasMacros, HasName, HasGrid, HasActionsRulesAndScripts

Phoebus Screen object that holds widgets and can be written to .bob file

BUILTIN_MACROS = frozenset({'DID', 'DNAME'})
PV_WIDGET_MACROS = frozenset({'pv_value'})
property actions
add_widget(elem)

Add widget or list of widgets to screen.

Parameters:

elem (Union[Widget, Sequence[Widget]]) – <list/Phoebusgen.widget> List of Phoebusgen.widget’s or a single widget to add

Return type:

None

property background_color
bring_forward(widget)

Bring a widget one step forward in the container.

Parameters:

widget (Widget) – The widget instance to bring forward

Return type:

None

bring_to_front(widget)

Bring a widget to the front of the container.

Parameters:

widget (Widget) – The widget instance to bring to the front

Return type:

None

build_navigation_graph(base_dir=None)

Build a navigation graph starting from this screen, recursively following all linked screens.

Parameters:

base_dir (Optional[Path]) – Base directory to resolve relative file paths. If None, uses bob_file’s parent or cwd.

Return type:

NavigationGraph

Returns:

NavigationGraph with all reachable screens and transitions

classmethod from_element(element)

Create a PhoebusElement from an XML Element.

Parameters:

element (Element) – XML Element to create from

Return type:

TypeVar(PhoebusElementT, bound= PhoebusElement)

Returns:

PhoebusElement instance

get_all_widgets()

Get a list of all widgets contained within the container, including nested widgets.

Returns:

List of all Widget instances contained within the container

Return type:

List[Widget]

get_linked_screens()

Get all screens linked from this screen via actions, embedded displays, nav tabs, etc.

Return type:

List[ScreenTransition]

Returns:

List of ScreenTransition objects describing each link

classmethod get_property_classes()

Return a list of all property mixins this class inheritys, including itself if it is a property mixin.

Return type:

List[Type[PropertyBase]]

Returns:

List of property mixin classes

classmethod get_property_names(property_cls=None)

Return a list of property names for a given property class or all property classes if none is specified.

Parameters:

property_cls (Optional[Type[PropertyBase]]) – The property class to get names for, or None to get names for all property classes

Return type:

List[str]

Returns:

List of property names

classmethod get_property_type_by_name(property_name)

Given a property name, return the type of that property by looking it up in the _all_properties dictionary.

Parameters:

property_name (str) – The name of the property to get the type for

Return type:

Type[Union[int, float, str, bool, Tuple, Enum, Color, Font, ObservableDict, ObservableList, ObservableDataclass, Rule, RuleExpression]]

Returns:

The type of the property

get_used_macros()

Get all macro names referenced in this screen via the $(MACRO) pattern.

Scans all text content and attribute values in the screen’s XML tree for macro references like $(PV_PREFIX), $(DEVICE), etc.

Macros that always specify a default via $(NAME=DEFAULT) are returned in a separate set. If a macro appears both with and without a default, it is included only in the required (no-default) set.

Excludes references that match property names of the widget they appear in, since Phoebus resolves those from the widget’s own properties rather than macros. Also excludes Phoebus built-in macros (DID, DNAME) that are always available at runtime.

Return type:

Tuple[Set[str], Set[str]]

Returns:

Tuple of (set of macros without defaults, set of macros that always have defaults)

get_widget_names()

Get a set of widget names contained within the container.

Returns:

Set of widget names contained within the container

Return type:

Set[str]

get_widgets()

Get a list of all widgets contained within the container.

Widgets are returned in the order they appear in the XML, which is the order they are rendered in Phoebus (i.e. widgets later in the XML will be rendered on top of widgets earlier in the XML).

Returns:

List of Widget instances for each widget element contained within the container

Return type:

List[Widget]

get_widgets_by_property(property_name)

Get a list of widgets contained within the container that have a property named property_name.

Parameters:

property_name (str) – Name of property to filter by

Returns:

List of Widget instances that have a property named property_name

Return type:

List[Widget]

get_widgets_by_property_class(prop_type)

Get a list of widgets contained within the container that have a property of type prop_type.

Parameters:

prop_type (Type[TypeVar(PropertyT, bound= PropertyBase)]) – Property type to filter by

Returns:

List of Widget instances that have a property of type prop_type

Return type:

List[PropertyT]

get_widgets_by_type(widget_type)

Get a list of widgets contained within the container that are of type widget_type.

Parameters:

widget_type (Type[TypeVar(WidgetT, bound= Widget)]) – Widget type to filter by

Returns:

List of Widget instances of type widget_type contained within the container

Return type:

List[WidgetT]

property grid_color
property grid_step_x
property grid_step_y
property grid_visible
property height
index_of(widget)
Return type:

int

property macros
property name
remove_widget(widget)

Remove a widget from the container by reference.

Parameters:

widget (Widget) – The widget instance to remove

Return type:

None

root: Element
property rules
property scripts
send_backward(widget)

Send a widget one step backward in the container.

Parameters:

widget (Widget) – The widget instance to send backward

Return type:

None

send_to_back(widget)

Send a widget to the back of the container.

Parameters:

widget (Widget) – The widget instance to send to the back

Return type:

None

property widgets: List[Widget]

Get the list of widgets and set their parent to the container.

property width
write_screen(file_name=None)

Writes screen XML to file. File name parameter is optional, if not given Screen bob_file member will be used

Parameters:

file_name (Union[Path, str, None]) – File name to write to

Return type:

bool

Returns:

True is successful write, False otherwise

property x
property y
class phoebusgen.v4.screen.ScreenTransition(target, macros=<factory>)

Bases: object

A transition from one screen to another, with the macros that are passed.

macros: Dict[str, str]
target: Path

phoebusgen.v4.utils module

class phoebusgen.v4.utils.PhoebusElement(root)

Bases: object

Base class for all Phoebus elements, including screens, widgets, and properties.

Attributes

rootElement

The XML element that represents this PhoebusElement object.

classmethod from_element(element)

Create a PhoebusElement from an XML Element.

Parameters:

element (Element) – XML Element to create from

Return type:

TypeVar(PhoebusElementT, bound= PhoebusElement)

Returns:

PhoebusElement instance

root: Element
phoebusgen.v4.utils.prettify_xml(elem)

Return a pretty-printed XML string for the Element. From: https://pymotw.com/3/xml.etree.ElementTree/create.html

Module contents

phoebusgen Module

This module contains a Python class representation of a Phoebus screen and all widgets. With the module, you can create Python scripts to write Phoebus screens to a .bob file. Almost all possible functionality should exist in Phoebusgen that you can do in the Display Builder Editor.

In addition, phoebusgen.colors and phoebusgen.fonts are Enum objects that are available to use to add predefined colors/fonts to widgets.

Example: text_update_widget.predefined_foreground_color(phoebusgen.colors.OK)

A custom site specific color.def or font.def in ~/.phoebusgen/ to force phoebusgen.colors or phoebusgen.fonts to reflect your site’s custom definitions.

class phoebusgen.v4.Screen(name=None, f_name=None, overwrite=False)

Bases: HasWidgets, HasPosition, HasBackgroundColor, HasMacros, HasName, HasGrid, HasActionsRulesAndScripts

Phoebus Screen object that holds widgets and can be written to .bob file

BUILTIN_MACROS = frozenset({'DID', 'DNAME'})
PV_WIDGET_MACROS = frozenset({'pv_value'})
property actions
add_widget(elem)

Add widget or list of widgets to screen.

Parameters:

elem (Union[Widget, Sequence[Widget]]) – <list/Phoebusgen.widget> List of Phoebusgen.widget’s or a single widget to add

Return type:

None

property background_color
bring_forward(widget)

Bring a widget one step forward in the container.

Parameters:

widget (Widget) – The widget instance to bring forward

Return type:

None

bring_to_front(widget)

Bring a widget to the front of the container.

Parameters:

widget (Widget) – The widget instance to bring to the front

Return type:

None

build_navigation_graph(base_dir=None)

Build a navigation graph starting from this screen, recursively following all linked screens.

Parameters:

base_dir (Optional[Path]) – Base directory to resolve relative file paths. If None, uses bob_file’s parent or cwd.

Return type:

NavigationGraph

Returns:

NavigationGraph with all reachable screens and transitions

classmethod from_element(element)

Create a PhoebusElement from an XML Element.

Parameters:

element (Element) – XML Element to create from

Return type:

TypeVar(PhoebusElementT, bound= PhoebusElement)

Returns:

PhoebusElement instance

get_all_widgets()

Get a list of all widgets contained within the container, including nested widgets.

Returns:

List of all Widget instances contained within the container

Return type:

List[Widget]

get_linked_screens()

Get all screens linked from this screen via actions, embedded displays, nav tabs, etc.

Return type:

List[ScreenTransition]

Returns:

List of ScreenTransition objects describing each link

classmethod get_property_classes()

Return a list of all property mixins this class inheritys, including itself if it is a property mixin.

Return type:

List[Type[PropertyBase]]

Returns:

List of property mixin classes

classmethod get_property_names(property_cls=None)

Return a list of property names for a given property class or all property classes if none is specified.

Parameters:

property_cls (Optional[Type[PropertyBase]]) – The property class to get names for, or None to get names for all property classes

Return type:

List[str]

Returns:

List of property names

classmethod get_property_type_by_name(property_name)

Given a property name, return the type of that property by looking it up in the _all_properties dictionary.

Parameters:

property_name (str) – The name of the property to get the type for

Return type:

Type[Union[int, float, str, bool, Tuple, Enum, Color, Font, ObservableDict, ObservableList, ObservableDataclass, Rule, RuleExpression]]

Returns:

The type of the property

get_used_macros()

Get all macro names referenced in this screen via the $(MACRO) pattern.

Scans all text content and attribute values in the screen’s XML tree for macro references like $(PV_PREFIX), $(DEVICE), etc.

Macros that always specify a default via $(NAME=DEFAULT) are returned in a separate set. If a macro appears both with and without a default, it is included only in the required (no-default) set.

Excludes references that match property names of the widget they appear in, since Phoebus resolves those from the widget’s own properties rather than macros. Also excludes Phoebus built-in macros (DID, DNAME) that are always available at runtime.

Return type:

Tuple[Set[str], Set[str]]

Returns:

Tuple of (set of macros without defaults, set of macros that always have defaults)

get_widget_names()

Get a set of widget names contained within the container.

Returns:

Set of widget names contained within the container

Return type:

Set[str]

get_widgets()

Get a list of all widgets contained within the container.

Widgets are returned in the order they appear in the XML, which is the order they are rendered in Phoebus (i.e. widgets later in the XML will be rendered on top of widgets earlier in the XML).

Returns:

List of Widget instances for each widget element contained within the container

Return type:

List[Widget]

get_widgets_by_property(property_name)

Get a list of widgets contained within the container that have a property named property_name.

Parameters:

property_name (str) – Name of property to filter by

Returns:

List of Widget instances that have a property named property_name

Return type:

List[Widget]

get_widgets_by_property_class(prop_type)

Get a list of widgets contained within the container that have a property of type prop_type.

Parameters:

prop_type (Type[TypeVar(PropertyT, bound= PropertyBase)]) – Property type to filter by

Returns:

List of Widget instances that have a property of type prop_type

Return type:

List[PropertyT]

get_widgets_by_type(widget_type)

Get a list of widgets contained within the container that are of type widget_type.

Parameters:

widget_type (Type[TypeVar(WidgetT, bound= Widget)]) – Widget type to filter by

Returns:

List of Widget instances of type widget_type contained within the container

Return type:

List[WidgetT]

property grid_color
property grid_step_x
property grid_step_y
property grid_visible
property height
index_of(widget)
Return type:

int

property macros
property name
remove_widget(widget)

Remove a widget from the container by reference.

Parameters:

widget (Widget) – The widget instance to remove

Return type:

None

root: Element
property rules
property scripts
send_backward(widget)

Send a widget one step backward in the container.

Parameters:

widget (Widget) – The widget instance to send backward

Return type:

None

send_to_back(widget)

Send a widget to the back of the container.

Parameters:

widget (Widget) – The widget instance to send to the back

Return type:

None

property widgets: List[Widget]

Get the list of widgets and set their parent to the container.

property width
write_screen(file_name=None)

Writes screen XML to file. File name parameter is optional, if not given Screen bob_file member will be used

Parameters:

file_name (Union[Path, str, None]) – File name to write to

Return type:

bool

Returns:

True is successful write, False otherwise

property x
property y
phoebusgen.v4.change_phoebus_version(version)