Google

Edit File: specification.py

#
# Support for DBus XML specifications
#
# Copyright (C) 2019  Red Hat, Inc.  All rights reserved.
#
# This library is free software; you can redistribute it and/or
# modify it under the terms of the GNU Lesser General Public
# License as published by the Free Software Foundation; either
# version 2.1 of the License, or (at your option) any later version.
#
# This library is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
# Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public
# License along with this library; if not, write to the Free Software
# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301
# USA
#
# For more info about DBus specification see:
# https://dbus.freedesktop.org/doc/dbus-specification.html#introspection-format
#
from collections import namedtuple

from dasbus.xml import XMLParser

__all__ = [
    "DBusSpecificationError",
    "DBusSpecification",
    "DBusSpecificationParser"
]

class DBusSpecificationError(Exception):
    """Exception for the DBus specification errors."""
    pass

class DBusSpecification(object):
    """DBus XML specification."""

DIRECTION_IN = "in"
    DIRECTION_OUT = "out"
    ACCESS_READ = "read"
    ACCESS_WRITE = "write"
    ACCESS_READWRITE = "readwrite"
    RETURN_PARAMETER = "return"

STANDARD_INTERFACES = """
    <node>
        <interface name="org.freedesktop.DBus.Introspectable">
            <method name="Introspect">
            <arg type="s" name="xml_data" direction="out"/>
            </method>
        </interface>
        <interface name="org.freedesktop.DBus.Peer">
            <method name="Ping"/>
            <method name="GetMachineId">
                <arg type="s" name="machine_uuid" direction="out"/>
            </method>
       </interface>
        <interface name="org.freedesktop.DBus.Properties">
            <method name="Get">
                <arg type="s" name="interface_name" direction="in"/>
                <arg type="s" name="property_name" direction="in"/>
                <arg type="v" name="value" direction="out"/>
            </method>
            <method name="GetAll">
                <arg type="s" name="interface_name" direction="in"/>
                <arg type="a{sv}" name="properties" direction="out"/>
            </method>
            <method name="Set">
                <arg type="s" name="interface_name" direction="in"/>
                <arg type="s" name="property_name" direction="in"/>
                <arg type="v" name="value" direction="in"/>
            </method>
            <signal name="PropertiesChanged">
                <arg type="s" name="interface_name"/>
                <arg type="a{sv}" name="changed_properties"/>
                <arg type="as" name="invalidated_properties"/>
            </signal>
        </interface>
    </node>
    """

# Representation of specification members.
    Signal = namedtuple("Signal", [
        "name",
        "interface_name",
        "type"
    ])

Method = namedtuple("Method", [
        "name",
        "interface_name",
        "in_type",
        "out_type"
    ])

Property = namedtuple("Property", [
        "name",
        "interface_name",
        "readable",
        "writable",
        "type"
    ])

# Specification data holders.
    __slots__ = ["_members"]

@classmethod
    def from_xml(cls, xml):
        """Return a DBus specification for the given XML."""
        return DBusSpecificationParser.parse_specification(xml, cls)

def __init__(self):
        """Create a new DBus specification."""
        self._members = {}

@property
    def interfaces(self):
        """Interfaces of the DBus specification."""
        return list(dict(self._members.keys()).keys())

@property
    def members(self):
        """Members of the DBus specification."""
        return list(self._members.values())

def add_member(self, member):
        """Add a member of a DBus interface."""
        self._members[(member.interface_name, member.name)] = member

def get_member(self, interface_name, member_name):
        """Get a member of a DBus interface."""
        try:
            return self._members[(interface_name, member_name)]
        except KeyError:
            pass

raise DBusSpecificationError(
            "DBus specification has no member '{}.{}'.".format(
                interface_name, member_name
            )
        )

class DBusSpecificationParser(object):
    """Class for parsing DBus XML specification."""

# The XML parser.
    xml_parser = XMLParser

@classmethod
    def parse_specification(cls, xml, factory=DBusSpecification):
        """Generate a representation of a DBus XML specification.

:param xml: the XML specification to parse
        :param factory: the DBus specification factory
        :return: a representation od the DBus specification
        """
        specification = factory()
        cls._parse_xml(specification, DBusSpecification.STANDARD_INTERFACES)
        cls._parse_xml(specification, xml)
        return specification

@classmethod
    def _parse_xml(cls, specification, xml):
        """Parse the given XML."""
        node = cls.xml_parser.xml_to_element(xml)

# Iterate over interfaces.
        for interface_element in node:
            if not cls.xml_parser.is_interface(interface_element):
                continue

# Parse the interface.
            cls._parse_interface(specification, interface_element)

@classmethod
    def _parse_interface(cls, specification, interface_element):
        """Parse the interface element from the DBus specification."""
        interface_name = cls.xml_parser.get_name(interface_element)

# Iterate over members.
        for member_element in interface_element:

if cls.xml_parser.is_property(member_element):
                member = cls._parse_property(interface_name, member_element)

elif cls.xml_parser.is_signal(member_element):
                member = cls._parse_signal(interface_name, member_element)

elif cls.xml_parser.is_method(member_element):
                member = cls._parse_method(interface_name, member_element)

else:
                continue

# Add the member specification to the mapping.
            specification.add_member(member)

return interface_name

@classmethod
    def _parse_property(cls, interface_name, property_element):
        """Parse the property element from the DBus specification."""
        property_name = cls.xml_parser.get_name(property_element)
        property_type = cls.xml_parser.get_type(property_element)
        property_access = cls.xml_parser.get_access(property_element)

readable = property_access in (
            DBusSpecification.ACCESS_READ,
            DBusSpecification.ACCESS_READWRITE
        )

writable = property_access in (
            DBusSpecification.ACCESS_WRITE,
            DBusSpecification.ACCESS_READWRITE
        )

return DBusSpecification.Property(
            name=property_name,
            interface_name=interface_name,
            readable=readable,
            writable=writable,
            type=property_type
        )

@classmethod
    def _parse_signal(cls, interface_name, signal_element):
        """Parse the signal element from the DBus specification."""
        signal_name = cls.xml_parser.get_name(signal_element)
        signal_type = []

for element in signal_element:
            if not cls.xml_parser.is_parameter(element):
                continue

element_type = cls.xml_parser.get_type(element)
            signal_type.append(element_type)

return DBusSpecification.Signal(
            name=signal_name,
            interface_name=interface_name,
            type=cls._get_type(signal_type)
        )

@classmethod
    def _parse_method(cls, interface_name, method_element):
        """Parse the method element from the DBus specification."""
        method_name = cls.xml_parser.get_name(method_element)
        in_types = []
        out_types = []

for element in method_element:
            if not cls.xml_parser.is_parameter(element):
                continue

direction = cls.xml_parser.get_direction(element)
            element_type = cls.xml_parser.get_type(element)

if direction == DBusSpecification.DIRECTION_IN:
                in_types.append(element_type)

elif direction == DBusSpecification.DIRECTION_OUT:
                out_types.append(element_type)

return DBusSpecification.Method(
            name=method_name,
            interface_name=interface_name,
            in_type=cls._get_type(in_types),
            out_type=cls._get_type(out_types)
        )

@classmethod
    def _get_type(cls, types):
        """Join types into one value."""
        if not types:
            return None

return "({})".format("".join(types))