# Group

## Group class

class tango.Group(name)

  Bases: `object`

  A Tango Group represents a hierarchy of tango devices. The hierarchy may have more than one level. The main goal is to group devices with same attribute(s)/command(s) to be able to do parallel requests.

  add(self, subgroup, timeout_ms=-1) → None

    > Attaches a (sub)_RealGroup.

    > To remove the subgroup use the remove() method.

    Parameters:
      subgroup:

        (`str`)

      timeout_ms:

        (`int`) If timeout_ms parameter is different from -1, the client side timeout associated to each device composing the _RealGroup added is set to timeout_ms milliseconds. If timeout_ms is -1, timeouts are not changed.

    Return:

      None

    Throws:

      TypeError, ArgumentError

  command_inout(self, cmd_name, forward=True) → sequence<GroupCmdReply>
  command_inout(self, cmd_name, param, forward=True) → sequence<GroupCmdReply>
  command_inout(self, cmd_name, param_list, forward=True) → sequence<GroupCmdReply>

    > Just a shortcut to do:

    >   self.command_inout_reply(self.command_inout_asynch(…))

    Parameters:
      cmd_name:

        (`str`) Command name

      param:

        (`any`) parameter value

      param_list:

        (`tango.DeviceDataList`) sequence of parameters. When given, it’s length must match the group size.

      forward:

        (`bool`) If it is set to true (the default) request is forwarded to subgroups. Otherwise, it is only applied to the local set of devices.

    Return:

      (sequence<`GroupCmdReply`>)

  command_inout_reply(self, req_id, timeout_ms=0) → sequence<GroupCmdReply>

    > Returns the results of an asynchronous command.

    Parameters:
      req_id:

        (`int`) Is a request identifier previously returned by one of the command_inout_asynch methods

      timeout_ms:

        (`int`) For each device in the hierarchy, if the command result is not yet available, command_inout_reply wait timeout_ms milliseconds before throwing an exception. This exception will be part of the global reply. If timeout_ms is set to 0, command_inout_reply waits “indefinitely”.

    Return:

      (sequence<`GroupCmdReply`>)

    Throws:

  contains(self, pattern, forward=True) → bool
    Parameters:
      pattern:

        (`str`) The pattern can be a fully qualified or simple group name, a device name or a device name pattern.

      forward:

        (`bool`) If fwd is set to true (the default), the remove request is also forwarded to subgroups. Otherwise, it is only applied to the local set of elements.

    Return:

      (`bool`) Returns true if the hierarchy contains groups and/or devices which name matches the specified pattern. Returns false otherwise.

    Throws:

  disable(*args, **kwds)

    Disables a group or a device element in a group.

  enable(*args, **kwds)

    Enables a group or a device element in a group.

  get_device_list(self, forward=True) → sequence<str>

    > Considering the following hierarchy:

    >     g2.add("my/device/04")
    >     g2.add("my/device/05")

    >     g4.add("my/device/08")
    >     g4.add("my/device/09")

    >     g3.add("my/device/06")
    >     g3.add(g4)
    >     g3.add("my/device/07")

    >     g1.add("my/device/01")
    >     g1.add(g2)
    >     g1.add("my/device/03")
    >     g1.add(g3)
    >     g1.add("my/device/02")

    > The returned vector content depends on the value of the forward option. If set to true, the results will be organized as follows:

    >         dl = g1.get_device_list(True)

    >     dl[0] contains "my/device/01" which belongs to g1
    >     dl[1] contains "my/device/04" which belongs to g1.g2
    >     dl[2] contains "my/device/05" which belongs to g1.g2
    >     dl[3] contains "my/device/03" which belongs to g1
    >     dl[4] contains "my/device/06" which belongs to g1.g3
    >     dl[5] contains "my/device/08" which belongs to g1.g3.g4
    >     dl[6] contains "my/device/09" which belongs to g1.g3.g4
    >     dl[7] contains "my/device/07" which belongs to g1.g3
    >     dl[8] contains "my/device/02" which belongs to g1

    > If the forward option is set to false, the results are:

    >         dl = g1.get_device_list(False);

    >     dl[0] contains "my/device/01" which belongs to g1
    >     dl[1] contains "my/device/03" which belongs to g1
    >     dl[2] contains "my/device/02" which belongs to g1

    Parameters:
      forward:

        (`bool`) If it is set to true (the default), the request is forwarded to sub-groups. Otherwise, it is only applied to the local set of devices.

    Return:

      (sequence<`str`>) The list of devices currently in the hierarchy.

    Throws:

  get_fully_qualified_name(*args, **kwds)

    Get the complete (dpt-separated) name of the group. This takes into consideration the name of the group and its parents.

  get_name(*args, **kwds)

    Get the name of the group. Eg: Group(‘name’).get_name() == ‘name’

  get_size(self, forward=True) → int
    Parameters:
      forward:

        (`bool`) If it is set to true (the default), the request is forwarded to sub-groups.

    Return:

      (`int`) The number of the devices in the hierarchy

    Throws:

  is_enabled(*args, **kwds)

    Check if a group is enabled. New in PyTango 7.0.0

  name_equals(*args, **kwds)

    New in PyTango 7.0.0

  name_matches(*args, **kwds)

    New in PyTango 7.0.0

  ping(self, forward=True) → bool

    > Ping all devices in a group.

    Parameters:
      forward:

        (`bool`) If fwd is set to true (the default), the request is also forwarded to subgroups. Otherwise, it is only applied to the local set of devices.

    Return:

      (`bool`) This method returns true if all devices in the group are alive, false otherwise.

    Throws:

  read_attribute(self, attr_name, forward=True) → sequence<GroupAttrReply>
    Just a shortcut to do:

      self.read_attribute_reply(self.read_attribute_asynch(…))

  read_attribute_asynch(self, attr_name, forward=True, reserved=-1) → int

    > Reads an attribute on each device in the group asynchronously. The method sends the request to all devices and returns immediately.

    Parameters:
      attr_name:

        (`str`) Name of the attribute to read.

      forward:

        (`bool`) If it is set to true (the default) request is forwarded to subgroups. Otherwise, it is only applied to the local set of devices.

      reserved:

        (`int`) is reserved for internal purpose and should not be used. This parameter may disappear in a near future.

    Return:

      (`int`) request id. Pass the returned request id to Group.read_attribute_reply() to obtain the results.

    Throws:

  read_attribute_reply(self, req_id, timeout_ms=0) → sequence<GroupAttrReply>

    > Returns the results of an asynchronous attribute reading.

    Parameters:
      req_id:

        (`int`) a request identifier previously returned by read_attribute_asynch.

      timeout_ms:

        (`int`) For each device in the hierarchy, if the attribute value is not yet available, read_attribute_reply wait timeout_ms milliseconds before throwing an exception. This exception will be part of the global reply. If timeout_ms is set to 0, read_attribute_reply waits “indefinitely”.

    Return:

      (sequence<`GroupAttrReply`>)

    Throws:

  read_attributes(self, attr_names, forward=True) → sequence<GroupAttrReply>
    Just a shortcut to do:

      self.read_attributes_reply(self.read_attributes_asynch(…))

  read_attributes_asynch(self, attr_names, forward=True, reserved=-1) → int

    > Reads the attributes on each device in the group asynchronously. The method sends the request to all devices and returns immediately.

    Parameters:
      attr_names:

        (sequence<`str`>) Name of the attributes to read.

      forward:

        (`bool`) If it is set to true (the default) request is forwarded to subgroups. Otherwise, it is only applied to the local set of devices.

      reserved:

        (`int`) is reserved for internal purpose and should not be used. This parameter may disappear in a near future.

    Return:

      (`int`) request id. Pass the returned request id to Group.read_attributes_reply() to obtain the results.

    Throws:

  read_attributes_reply(self, req_id, timeout_ms=0) → sequence<GroupAttrReply>

    > Returns the results of an asynchronous attribute reading.

    Parameters:
      req_id:

        (`int`) a request identifier previously returned by read_attribute_asynch.

      timeout_ms:

        (`int`) For each device in the hierarchy, if the attribute value is not yet available, read_attribute_reply ait timeout_ms milliseconds before throwing an exception. This exception will be part of the global reply. If timeout_ms is set to 0, read_attributes_reply waits “indefinitely”.

    Return:

      (sequence<`GroupAttrReply`>)

    Throws:

  remove_all(self) → None

    Removes all elements in the _RealGroup. After such a call, the _RealGroup is empty.

  set_timeout_millis(self, timeout_ms) → bool

    > Set client side timeout for all devices composing the group in milliseconds. Any method which takes longer than this time to execute will throw an exception.

    Parameters:
      timeout_ms:

        (`int`)

    Return:

      None

    Throws:

      (errors are ignored)

    New in PyTango 7.0.0

  write_attribute(self, attr_name, value, forward=True, multi=False) → sequence<GroupReply>
    Just a shortcut to do:

      self.write_attribute_reply(self.write_attribute_asynch(…))

  write_attribute_asynch(self, attr_name, value, forward=True, multi=False) → int

    > Writes an attribute on each device in the group asynchronously. The method sends the request to all devices and returns immediately.

    Parameters:
      attr_name:

        (`str`) Name of the attribute to write.

      value:

        (`any`) Value to write. See DeviceProxy.write_attribute

      forward:

        (`bool`) If it is set to true (the default) request is forwarded to subgroups. Otherwise, it is only applied to the local set of devices.

      multi:

        (`bool`) If it is set to false (the default), the same value is applied to all devices in the group. Otherwise the value is interpreted as a sequence of values, and each value is applied to the corresponding device in the group. In this case len(value) must be equal to group.get_size()!

    Return:

      (`int`) request id. Pass the returned request id to Group.write_attribute_reply() to obtain the acknowledgements.

    Throws:

  write_attribute_reply(self, req_id, timeout_ms=0) → sequence<GroupReply>

    > Returns the acknowledgements of an asynchronous attribute writing.

    Parameters:
      req_id:

        (`int`) a request identifier previously returned by write_attribute_asynch.

      timeout_ms:

        (`int`) For each device in the hierarchy, if the acknowledgment is not yet available, write_attribute_reply wait timeout_ms milliseconds before throwing an exception. This exception will be part of the global reply. If timeout_ms is set to 0, write_attribute_reply waits “indefinitely”.

    Return:

      (sequence<`GroupReply`>)

    Throws:

## GroupReply classes

Group member functions do not return the same as their DeviceProxy counterparts, but objects that contain them. This is:

> - write attribute family returns tango.GroupReplyList

> - read attribute family returns tango.GroupAttrReplyList

> - command inout family returns tango.GroupCmdReplyList

The Group*ReplyList objects are just list-like objects containing `GroupReply`, `GroupAttrReply` and `GroupCmdReply` elements that will be described now.

Note also that GroupReply is the base of GroupCmdReply and GroupAttrReply.

class tango.GroupReply(*args, **kwargs)

  This is the base class for the result of an operation on a PyTangoGroup, being it a write attribute, read attribute, or command inout operation.

  It has some trivial common operations:

  > - has_failed(self) -> bool

  > - group_element_enabled(self) ->bool

  > - dev_name(self) -> str

  > - obj_name(self) -> str

  > - get_err_stack(self) -> DevErrorList

class tango.GroupAttrReply(*args, **kwargs)

  Bases:

  get_data(self, extract_as=ExtractAs.Numpy) → DeviceAttribute

    > Get the DeviceAttribute.

    Parameters:
      extract_as:

        (`ExtractAs`)

    Return:

      (`DeviceAttribute`) Whatever is stored there, or None.

class tango.GroupCmdReply(*args, **kwargs)

  Bases:

  get_data(self) → any

    > Get the actual value stored in the GroupCmdRply, the command output value. It’s the same as self.get_data_raw().extract()

    Parameters:

      None

    Return:

      (`any`) Whatever is stored there, or None.

  get_data_raw(self) → any

    > Get the DeviceData containing the output parameter of the command.

    Parameters:

      None

    Return:

      (`DeviceData`) Whatever is stored there, or None.