dbusapi package

dbusapi.ast module

An implementation of the abstract syntax tree (AST) for a D-Bus introspection document, which fully describes a D-Bus API.

An AST can be built by parsing an XML file (using interfaceparser.InterfaceParser) or by building the tree of objects manually.

class dbusapi.ast.Annotation(name, value=None, log=None)

Bases: dbusapi.ast.BaseNode

AST representation of an <annotation> element.

This represents an arbitrary key-value metadata annotation attached to one of the nodes in an interface. The annotation name can be one of the well-known ones described at http://goo.gl/LgmNUe, or could be something else.

optional_attributes = ['value']

property pretty_name

Format the annotation’s name as a human-readable string

class dbusapi.ast.Argument(name, direction, type_, annotations=None, log=None)

Bases: dbusapi.ast.BaseNode

AST representation of an <arg> element.

This represents an argument to an ast.Signal or ast.Method.

DIRECTION_IN = 'in'

DIRECTION_OUT = 'out'

property index

The index of this argument in its parent’s list of arguments

optional_attributes = ['direction', 'name']

property pretty_name

Format the argument’s name as a human-readable string

required_attributes = ['type']

class dbusapi.ast.AstLog

Bases: dbusapi.log.Log

Specialized Log subclass for AST messages

class dbusapi.ast.BaseNode(name, annotations=None, log=None)

Bases: object

Base class for all D-Bus AST nodes.

DOCSTRING_TAGS = ['{http://telepathy.freedesktop.org/wiki/DbusSpec#extensions-v0}docstring', '{http://www.freedesktop.org/dbus/1.0/doc.dtd}doc']

add_child(child)

Add a child to the node

property comment

Get the comment for this node.

Returns:

str: If the node was annotated with org.gtk.GDBus.DocString,

the value of the annotation, otherwise one of: * A tp:docstring child node * A doc:doc child node * An XML comment immediately preceding the XML node. , whichever is seen last.

format_name()

Format this node’s name as a human-readable string

classmethod from_xml(node, comment, log, parent=None)

Return a new ast.BaseNode instance from an XML node.

optional_attributes = []

parse_xml_children(node)

Parse the XML node’s children.

property pretty_name

Format the node’s name as a human-readable string.

required_attributes = ['name']

walk()

Traverse this node’s children in pre-order.

class dbusapi.ast.Callable(name, args, annotations=None, log=None)

Bases: dbusapi.ast.BaseNode

AST representation of a callable element.

This represents a ‘callable’, such as a method or a signal. All callables contain a list of in and out arguments.

static is_valid_name(name)

Validate a D-Bus member name.

https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-member

Args:

name: callable name

property pretty_name

Format the callable’s name as a human-readable string

class dbusapi.ast.Interface(name, methods=None, properties=None, signals=None, annotations=None, log=None)

Bases: dbusapi.ast.BaseNode

AST representation of an <interface> element.

This represents the most commonly used node of a D-Bus API.

static is_valid_interface_name(name)

Validate a D-Bus interface name.

http://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-names-interface

Args:

name: interface name

class dbusapi.ast.Method(name, args, annotations=None, log=None)

Bases: dbusapi.ast.Callable

AST representation of a <method> element.

This represents a callable method of an interface.

class dbusapi.ast.Node(name=None, interfaces=None, nodes=None, annotations=None, log=None)

Bases: dbusapi.ast.BaseNode

AST representation of a <node> element.

This represents the top level of a D-Bus API.

static is_valid_absolute_object_path(path)

Validate an absolute D-Bus object path.

https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-marshaling-object-path

Args:

path: object path

static is_valid_relative_object_path(path)

Validate a relative D-Bus object path.

https://dbus.freedesktop.org/doc/dbus-specification.html#message-protocol-marshaling-object-path

Args:

path: object path

optional_attributes = ['name']

required_attributes = []

class dbusapi.ast.Property(name, type_, access, annotations=None, log=None)

Bases: dbusapi.ast.BaseNode

AST representation of a <property> element.

This represents a readable or writable property of an interface.

ACCESS_READ = 'read'

ACCESS_READWRITE = 'readwrite'

ACCESS_WRITE = 'write'

property pretty_name

Format the property’s name as a human-readable string

required_attributes = ['name', 'access', 'type']

class dbusapi.ast.Signal(name, args, annotations=None, log=None)

Bases: dbusapi.ast.Callable

AST representation of a <signal> element.

This represents an emittable signal on an interface.

dbusapi.ast.ignore_node(node)

Decide whether to ignore the given node when parsing.

dbusapi.interfaceparser module

Module providing an InterfaceParser object for parsing D-Bus introspection XML files into abstract syntax trees (ASTs).

class dbusapi.interfaceparser.InterfaceParser(filename)

Bases: object

Parse a D-Bus introspection XML file.

This validates the file, but not exceedingly strictly. It is a pragmatic parser, designed for use by the InterfaceComparator rather than more general code. It ignores certain common extensions found in introspection XML files, such as documentation elements, but will fail on other unrecognised elements.

get_output()

Return a list of all logged parser messages.

static get_output_codes()

Return a list of all possible output codes.

parse()

Parse the introspection XML file and build an AST.

Returns:

A non-empty dict of interfaces belonging to the root node in the file, mapping each interface name to an ast.Interface instance. If parsing fails, None is returned.

parse_with_nodes()

Parse the introspection XML file and build an AST.

Returns:

An ast.Node instance, representing the root node. If parsing fails, None is returned.

class dbusapi.interfaceparser.ParsingLog(filename)

Bases: dbusapi.ast.AstLog

A specialized AstLog subclass for parsing issues

dbusapi.typeparser module

Module providing a TypeParser object for parsing D-Bus type strings into abstract syntax trees (ASTs) representing the nested type structure.

class dbusapi.typeparser.TypeParser(signature)

Bases: object

Parse and validate a D-Bus type string.

The D-Bus type system and type strings are explained in detail in the D-Bus specification: https://dbus.freedesktop.org/doc/dbus-specification.html#type-system and in the GVariant documentation for GLib: https://developer.gnome.org/glib/stable/glib-GVariantType.html#id-1.6.18.6.9

get_output()

Return a list of all logged parser messages.

static get_output_codes()

Return a list of all possible output codes.

parse()

Parse the type string and build an AST of the type

Returns:

A non-empty list of types.

If parsing fails, or if the input string is empty, None is returned.

class dbusapi.typeparser.TypeParsingLog

Bases: dbusapi.log.Log

Specialized Log subclass for type parsing messages

dbusapi.types module

A representation of the D-Bus type system as a series of classes which can be built into an abstract syntax tree (AST) for representing complex (nested) types.

An AST can be built by parsing a D-Bus type signature (using typeparser.TypeParser) or by building the tree of objects manually.

class dbusapi.types.Array

Bases: dbusapi.types.Container

AST representation of the D-Bus ARRAY type.

class dbusapi.types.Boolean

Bases: dbusapi.types.Type

AST representation of the D-Bus BOOLEAN type.

Boolean value, 0 is FALSE and 1 is TRUE. Everything else is invalid.

class dbusapi.types.Byte

Bases: dbusapi.types.Type

AST representation of the D-Bus BYTE type.

8-bit unsigned integer.

class dbusapi.types.Container

Bases: dbusapi.types.Type

An abstract class - AST representation of the D-Bus container type.

class dbusapi.types.DictEntry

Bases: dbusapi.types.Container

AST representation of the D-Bus DICT_ENTRY type.

class dbusapi.types.Double

Bases: dbusapi.types.Type

AST representation of the D-Bus DOUBLE type.

IEEE 754 double.

class dbusapi.types.Int16

Bases: dbusapi.types.Type

AST representation of the D-Bus INT16 type.

16-bit signed integer.

class dbusapi.types.Int32

Bases: dbusapi.types.Type

AST representation of the D-Bus INT32 type.

32-bit signed integer.

class dbusapi.types.Int64

Bases: dbusapi.types.Type

AST representation of the D-Bus INT64 type.

64-bit signed integer.

class dbusapi.types.ObjectPath

Bases: dbusapi.types.Type

AST representation of the D-Bus OBJECT_PATH type.

Name of an object instance.

class dbusapi.types.Signature

Bases: dbusapi.types.Type

AST representation of the D-Bus SIGNATURE type.

class dbusapi.types.String

Bases: dbusapi.types.Type

AST representation of the D-Bus STRING type.

UTF-8 string (must be valid UTF-8). Must be nul terminated and contain no other nul bytes.

class dbusapi.types.Struct

Bases: dbusapi.types.Container

AST representation of the D-Bus STRUCT type.

class dbusapi.types.Type

Bases: object

An abstract class - AST representation of a D-Bus type.

See http://dbus.freedesktop.org/doc/dbus-specification.html#type-system

class dbusapi.types.TypeSignature

Bases: object

AST representation of a D-Bus signature - an ordered list of one or more types.

See http://dbus.freedesktop.org/doc/dbus-specification.html#type-system

class dbusapi.types.UInt16

Bases: dbusapi.types.Type

AST representation of the D-Bus UINT16 type.

16-bit unsigned integer.

class dbusapi.types.UInt32

Bases: dbusapi.types.Type

AST representation of the D-Bus UINT32 type.

32-bit unsigned integer.

class dbusapi.types.UInt64

Bases: dbusapi.types.Type

AST representation of the D-Bus UINT64 type.

64-bit unsigned integer.

class dbusapi.types.UnixFD

Bases: dbusapi.types.Type

AST representation of the D-Bus UNIX_FD type.

Unix file descriptor.

class dbusapi.types.Variant

Bases: dbusapi.types.Type

AST representation of the D-Bus VARIANT type.

Variant type - the type of the value is part of the value itself.

dbusapi.typeformatter module

Module providing a BasicTypeFormatter object for formatting D-Bus type abstract syntax trees (ASTs) into human-readable strings describing the type structure.

These strings are intended to be easy to read for a technical reader, but without having to memorise the single-character D-Bus types. They could be used in documentation, for example.

Other type formatters may be added in future which format the type ASTs differently.

class dbusapi.typeformatter.BasicTypeFormatter

Bases: object

Format a D-Bus type AST as a string.

Given a valid D-Bus type structure (see types.Type and types.TypeSignature), format it as a human-readable string. The format mirrors that used by D-Feet when introspecting D-Bus interfaces.

In future, support may be added to this class for choosing the output language for the formatted strings.

format(type_instance)

Format the type instance as a human-readable string.

Note that the type instance must be a valid type structure. For example, this means that any types.Struct instance must have one or more child members; any types.DictEntry instance must have exactly two child members (key and value) and be the immediate child of a types.Array instance.

See the D-Bus documentation for the full details of type system restrictions: https://dbus.freedesktop.org/doc/dbus-specification.html#type-system

The type instance may be a types.Type instance or a types.TypeSignature instance.

Args:

type_instance: valid types.Type or types.TypeSignature instance

dbusapi.log module

An implementation of a base logging class.

class dbusapi.log.Log

Bases: object

Base logging class.

clear()

Clear the issue list.

log_issue(code, message)

Log a new issue.

Args:

code: str, A registered code for that issue. message: str, A message describing the issue.

register_issue_code(code)

Register a new issue code.

Duplicate codes will be silently ignored.

Args:

code: str, an issue code, for example unknown-node