# Introspection

class dbus_fast.introspection.Node(name: str | None = None, interfaces: list[Interface] | None = None, is_root: bool = True)

  A class that represents a node in an object path in introspection data.

  A node contains information about interfaces exported on this path and child nodes. A node can be converted to and from introspection XML exposed through the `org.freedesktop.DBus.Introspectable` standard DBus interface.

  This class is an essential building block for a high-level DBus interface. This is the underlying data structure for the `ProxyObject`. A `ServiceInterface` definition is converted to this class to expose XML on the introspectable interface.

  Variables:

    - interfaces (list(`Interface`)) – A list of interfaces exposed on this node.

    - nodes (list(`Node`)) – A list of child nodes.

    - name (str) – The object path of this node.

    - is_root (bool) – Whether this is the root node. False if it is a child node.

  Raises:

    - `InvalidIntrospectionError` - If the name is not a valid node name.

  static default(name: str | None = None) → Node

    Create a `Node` with the default interfaces supported by this library.

    The default interfaces include:

    - `org.freedesktop.DBus.Introspectable`

    - `org.freedesktop.DBus.Peer`

    - `org.freedesktop.DBus.Properties`

    - `org.freedesktop.DBus.ObjectManager`

  static from_xml(element: Element, is_root: bool = False, validate_property_names: bool = True) → Node

    Convert an `xml.etree.ElementTree.Element` to a `Node`.

    The element must be valid DBus introspection XML for a `node`.

    Parameters:

      - element (`xml.etree.ElementTree.Element`) – The parsed XML element.

      - is_root (bool) – Whether this is the root node

      - validate_property_names (bool) – Whether to validate property names or not

    Raises:

      - `InvalidIntrospectionError` - If the XML tree is not valid introspection data.

  static parse(data: str, validate_property_names: bool = True) → Node

    Parse XML data as a string into a `Node`.

    The string must be valid DBus introspection XML.

    Parameters:

      - data (str) – The XMl string.

      - validate_property_names (bool) – Whether to validate property names or not

    Raises:

      - `InvalidIntrospectionError` - If the string is not valid introspection data.

  to_xml() → Element

    Convert this `Node` into an `xml.etree.ElementTree.Element`.

  tostring() → str

    Convert this `Node` into a DBus introspection XML string.

class dbus_fast.introspection.Interface(name: str, methods: list[Method] | None = None, signals: list[Signal] | None = None, properties: list[Property] | None = None, annotations: dict[str, str] | None = None)

  A class that represents a DBus interface exported on on object path.

  Contains information about the methods, signals, and properties exposed on this interface.

  Variables:

    - name (str) – The name of this interface.

    - methods (list(`Method`)) – A list of methods exposed on this interface.

    - signals (list(`Signal`)) – A list of signals exposed on this interface.

    - properties (list(`Property`)) – A list of properties exposed on this interface.

    - annotations (dict[str, str]) – The annotations of this interface.

  Raises:

    - `InvalidInterfaceNameError` - If the name is not a valid interface name.

  static from_xml(element: Element, validate_property_names: bool = True) → Interface

    Convert a `xml.etree.ElementTree.Element` into a `Interface`.

    The element must be valid DBus introspection XML for an `interface`.

    Parameters:

      element (`xml.etree.ElementTree.Element`) – The parsed XML element.

    Raises:

      - `InvalidIntrospectionError` - If the XML tree is not valid introspection data.

  to_xml() → Element

    Convert this `Interface` into an `xml.etree.ElementTree.Element`.

class dbus_fast.introspection.Property(name: str, signature: str, access: PropertyAccess = PropertyAccess.READWRITE, annotations: dict[str, str] | None = None, validate: bool = True)

  A class that represents a DBus property exposed on an `Interface`.

  Variables:

    - name (str) – The name of this property.

    - signature (str) – The signature string for this property. Must be a single complete type.

    - access (`PropertyAccess`) – Whether this property is readable and writable.

    - type (`SignatureType`) – The parsed type of this property.

    - annotations (dict[str, str]) – The annotations of this property.

  Raises:

    - `InvalidIntrospectionError` - If the property is not a single complete type.

    - :class InvalidSignatureError <dbus_fast.InvalidSignatureError> - If the given signature is not valid.

    - class:

        InvalidMemberNameError <dbus_fast.InvalidMemberNameError> - If the member name is not valid.

  from_xml(validate: bool = True)

    Convert an `xml.etree.ElementTree.Element` to a `Property`.

    The element must be valid DBus introspection XML for a `property`.

    Parameters:

      element (`xml.etree.ElementTree.Element`) – The parsed XML element.

    Raises:

      - `InvalidIntrospectionError` - If the XML tree is not valid introspection data.

  to_xml() → Element

    Convert this `Property` into an `xml.etree.ElementTree.Element`.

class dbus_fast.introspection.Method(name: str, in_args: list[Arg] = [], out_args: list[Arg] = [], annotations: dict[str, str] | None = None)

  A class that represents a method exposed on an `Interface`.

  Variables:

    - name (str) – The name of this method.

    - in_args (list(Arg)) – A list of input arguments to this method.

    - out_args (list(Arg)) – A list of output arguments to this method.

    - in_signature (str) – The collected signature string of the input arguments.

    - out_signature (str) – The collected signature string of the output arguments.

    - annotations (dict[str, str]) – The annotations of this method.

  Raises:

    - `InvalidMemberNameError` - If the name of this method is not valid.

  from_xml() → Method

    Convert an `xml.etree.ElementTree.Element` to a `Method`.

    The element must be valid DBus introspection XML for a `method`.

    Parameters:

      - element (`xml.etree.ElementTree.Element`) – The parsed XML element.

      - is_root (bool) – Whether this is the root node

    Raises:

      - `InvalidIntrospectionError` - If the XML tree is not valid introspection data.

  to_xml() → Element

    Convert this `Method` into an `xml.etree.ElementTree.Element`.

class dbus_fast.introspection.Signal(name: str | None, args: list[Arg] | None = None, annotations: dict[str, str] | None = None)

  A class that represents a signal exposed on an interface.

  Variables:

    - name (str) – The name of this signal

    - args (list(Arg)) – A list of output arguments for this signal.

    - signature (str) – The collected signature of the output arguments.

    - annotations (dict[str, str]) – The annotations of this signal.

  Raises:

    - `InvalidMemberNameError` - If the name of the signal is not a valid member name.

  from_xml()

    Convert an `xml.etree.ElementTree.Element` to a `Signal`.

    The element must be valid DBus introspection XML for a `signal`.

    Parameters:

      - element (`xml.etree.ElementTree.Element`) – The parsed XML element.

      - is_root (bool) – Whether this is the root node

    Raises:

      - `InvalidIntrospectionError` - If the XML tree is not valid introspection data.

  to_xml() → Element

    Convert this `Signal` into an `xml.etree.ElementTree.Element`.

class dbus_fast.introspection.Arg(signature: SignatureType | str, direction: ArgDirection | None = None, name: str | None = None, annotations: dict[str, str] | None = None)

  A class that represents an input or output argument to a signal or a method.

  Variables:

    - name (str) – The name of this arg.

    - direction (`ArgDirection`) – Whether this is an input or an output argument.

    - type (`SignatureType`) – The parsed signature type of this argument.

    - signature (str) – The signature string of this argument.

    - annotations (dict[str, str]) – The annotations of this arg.

  Raises:

    - `InvalidMemberNameError` - If the name of the arg is not valid.

    - `InvalidSignatureError` - If the signature is not valid.

    - `InvalidIntrospectionError` - If the signature is not a single complete type.

  from_xml(direction: ArgDirection) → Arg

    Convert a `xml.etree.ElementTree.Element` into a `Arg`.

    The element must be valid DBus introspection XML for an `arg`.

    Parameters:

      - element (`xml.etree.ElementTree.Element`) – The parsed XML element.

      - direction (`ArgDirection`) – The direction of this arg. Must be specified because it can default to different values depending on if it’s in a method or signal.

    Raises:

      - `InvalidIntrospectionError` - If the XML tree is not valid introspection data.

  to_xml() → Element

    Convert this `Arg` into an `xml.etree.ElementTree.Element`.