Groups

PyRogue groups are string tags attached to each node (Device, Variable, Command, etc.). They are intentionally open-ended: users can define any custom group name and use it with incGroups / excGroups filters.

How group filtering works

Most tree APIs that accept incGroups and excGroups use the same logic:

  • include check passes when incGroups is empty, or the node is in at least one include group

  • exclude check passes when excGroups is empty, or the node is in none of the exclude groups

  • a node is processed only if both checks pass

Built-in group names and behavior

The following names have built-in meaning in the current PyRogue implementation:

  • Hidden

    • Added automatically when hidden=True is used in node constructors.

    • Used by GUI and helper defaults to hide nodes unless explicitly included.

  • NoConfig

    • Excluded by root configuration APIs/commands such as SaveConfig, LoadConfig, SetYamlConfig, and GetYamlConfig.

    • Use for runtime/status items that should not be persisted as configuration.

  • NoState

    • Excluded by root state-export APIs/commands such as SaveState and GetYamlState.

    • Use for values that should not be captured in state snapshots.

  • NoStream

    • Excluded by default in variable streaming interfaces. E.g. pyrogue.interfaces.stream.Variable.

    • Use for nodes that should not appear in stream output.

    • Typically used to prevent Variable logging from being set to a StreamWriter.

  • NoSql

    • Excluded by default in SQL logging interfaces.

    • Use for nodes that should not be recorded in SQL logs.

  • NoServe

    • Excluded from served remote node lists (for example ZMQ/virtual tree exposure).

    • Use for nodes that should remain local-only and not be exposed remotely.

  • Enable

    • Used by the built-in EnableVariable class as a semantic label.

    • This is a convention used by framework components, not a hard filter category by itself.

    • Should not be used for any other purpose.

Other names you may see

  • NoAlarm appears in examples/tutorial content, but there is no core framework behavior tied to this name in the current codebase. Treat it as a project-level convention unless your application defines logic for it.

Best practices

  • Keep built-in names for their existing semantics.

  • Add project-specific groups for your own workflows (for example deployment phases, GUI views, ownership).

  • Document custom groups near your root/device definitions so downstream users know how to filter them.

  • Prefer incGroups / excGroups in bulk operations instead of ad-hoc per-node conditionals.