API Reference¶

D-Car main API.

This should normally be enough for implementing message bus clients.

Overview¶

`Bus`	Representation of a client’s connection to a message bus.
`MatchRule`	Match rule for signals.
`Variant`	A D-Bus Variant.
`UnixFD`	Wrapper for a unix file descriptor.
`RemoteObject`	An instance of this class is a proxy for an object on the D-Bus.
`Error`	Base class.
`AddressError`	Raised for errors in server addresses.
`AuthenticationError`	Raised when authentication failed.
`TransportError`	Raised for transport related errors.
`ValidationError`	Raised when validation failed.
`RegisterError`	Raised when a signal or method could not be registered.
`MessageError`	Raised for errors in messages.
`DBusError`	Raised for errors from ERROR messages.
`SignatureError`	Raised for errors in signatures.
`TooLongError`	Raised when a message, an array, a name etc.

class dcar.Bus(address='session')[source]¶

Bases: object

Representation of a client’s connection to a message bus.

An instance of this class is the central point for a client to interact with a message bus. It can be used as a context manager. On entering the runtime context the connect() method will be called, on exiting the disconnect() method.

Parameters: address (str or Address) – same as for Address or an Address object

property address¶: Return the actual address the client is connected to.

property bus_type¶: Return the bus type: 'system', 'session' , or None.

New in version 0.3.0.

property connected¶: Return whether the client is connected.

property unique_name¶: Return the unique name of the client’s connection.

property guid¶: Return the GUID of the server.

property unix_fds_enabled¶: Return whether passing of unix file descriptors is enabled.

property error¶

Return transport error or None.

This error is set when the client loses the connection to the message bus because of this error.

raise_on_error()[source]¶: Re-raises the error or does nothing.

connect()[source]¶

Connect to message bus.

Raises

AuthenticationError – if authentication failed
OSError – if connection failed

disconnect()[source]¶: Disconnect the client.

block(timeout=None)[source]¶

Blocks until send-loop and recv-loop are finished or timeout is reached.

The send-loop and recv-loop threads are started when connecting to the D-Bus.

Parameters: timeout (float) – timeout value in seconds (None means no timeout)

Changed in version 0.2.0: Add parameter timeout

send_message(msg, timeout=None)[source]¶

Send a message.

Normally method_call(), method_return(), send_error() or emit_signal() should be used.

Parameters

msg (Message) – the message
timeout (float) – None = no timeout, 0 = no reply expected and > 0 = timeout in seconds

Returns

return values of the message call if a reply is expected else None

Return type

tuple or None

Raises

TransportError – if the message could not be sent

method_call(object_path, interface, method_name, destination, *, sender=None, signature=None, args=(), timeout=25.0, no_auto_start=False, allow_interactive_authorization=False)[source]¶

Send a message of type METHOD_CALL.

Parameters

object_path (str) – object path (required)
interface (str) – interface name
method_name (str) – method name (required)
destination (str) – name of the destination’s connection
sender (str) – name of the sender’s connection
signature (str) – D-Bus types signature of the IN arguments
args (tuple) – the IN arguments
timeout (float) – None = no timeout, 0 = no reply expected and > 0 = timeout in seconds
no_auto_start (bool) – header flag
allow_interactive_authorization (bool) – header flag

Returns

return values of the method call if a reply is expected else None

Return type

tuple or None

Raises

TransportError – if the message could not be sent

method_return(reply_serial, destination, *, sender=None, signature=None, args=())[source]¶

Send a message of type METHOD_RETURN.

Parameters

reply_serial (int) – serial of the message for which this is a reply (required)
destination (str) – name of the destination’s connection
sender (str) – name of the sender’s connection
signature (str) – D-Bus types signature of the OUT arguments of the called method
args (tuple) – the OUT arguments of the called method

Raises

TransportError – if the message could not be sent

send_error(error_name, reply_serial, destination, *, sender=None, signature=None, args=())[source]¶

Send a message of type ERROR.

Parameters

error_name (str) – error name (required)
reply_serial (int) – serial of the message for which this is a reply (required)
destination (str) – name of the destination’s connection
sender (str) – name of the sender’s connection
signature (str) – D-Bus types signature of the arguments
args (tuple) – the arguments

Raises

TransportError – if the message could not be sent

emit_signal(object_path, interface, signal_name, destination=None, *, sender=None, signature=None, args=())[source]¶

Send a message of type SIGNAL.

Parameters

object_path (str) – object path (required)
interface (str) – interface name (required)
signal_name (str) – signal name (required)
destination (str) – name of the destination’s connection
sender (str) – name of the sender’s connection
signature (str) – D-Bus types signature of the arguments
args (tuple) – the arguments

Raises

TransportError – if the message could not be sent

register_signal(rule, handler, unicast=False, timeout=25.0)[source]¶

Register a signal.

The handler function must take one parameter: a MessageInfo object.

Note

The handler functions for incoming method calls and signals will be executed in a separate thread sequentially.

Parameters

rule (MatchRule) – the match rule
handler (callable) – handler function for the signal
unicast (bool) – if True this rule applies to a unicast signal and no AddMatch message will be sent to the message bus
timeout (float) – timeout in seconds

Returns

ID of the signal

Return type

int

Raises

RegisterError – if the signal could not be registered
TransportError – if the AddMatch message could not be sent

unregister_signal(reg_id, timeout=25.0)[source]¶

Unregister a signal.

Parameters

reg_id (int) – ID returned by register_signal()
timeout (float) – timeout in seconds

Raises

TransportError – if RemoveMatch message could not be sent

register_method(object_path, interface, method_name, handler, signature=None)[source]¶

Register a method.

The handler function must take two parameters: a Bus object and a MessageInfo object.

Note

The handler functions for incoming method calls and signals will be executed in a separate thread sequentially.

Parameters

object_path (str) – object path
interface (str) – interface name
method_name (str) – method name
signature (str) – D-Bus type signatures of the arguments

Returns

ID of the method

Return type

int

Raises

RegisterError – if the method could not be registered

unregister_method(meth_id)[source]¶

Unregister a method.

Parameters: meth_id (int) – ID returned by register_method()

class dcar.MatchRule(object_path: str = None, interface: str = None, signal_name: str = None, sender: str = None, path_namespace: str = None, destination: str = None, arg0namespace: str = None)[source]¶

Bases: object

Match rule for signals.

All parameters are explained in the D-Bus specification.

object_path: str = None¶

interface: str = None¶

signal_name: str = None¶

sender: str = None¶

path_namespace: str = None¶

destination: str = None¶

arg0namespace: str = None¶

args: dict¶

argpaths: dict¶

add_arg(idx, arg)[source]¶: Add an arg match at idx.

add_argpath(idx, argpath)[source]¶: Add an argpath match at idx.

class dcar.Variant(signature, value)¶

Bases: tuple

A D-Bus Variant.

signature¶: D-Bus type signature

value¶: value of the Variant

class dcar.UnixFD(f, close=False)[source]¶

Bases: object

Wrapper for a unix file descriptor.

The file descriptor will be duplicated. The caller is responsible for closing the original file descriptor.

Parameters

f (int or file-like object) – file descriptor or object that has a fileno() method which returns a file descriptor
close (bool) – if set to True the original file descriptor will be closed after duplicating it

fileno()[source]¶

Return the file descriptor.

Returns: file descriptor
Return type: int

class dcar.RemoteObject(bus, name, path, xml=None)[source]¶

Bases: object

An instance of this class is a proxy for an object on the D-Bus.

Methods, signals, and properties can be accessed as attributes with the same names as on the D-Bus. If a name occurs in more than one interface, only one method, signal, or property can be accessed as an attribute. To access the shadowed names subscription syntax must be used: obj['interface name', 'member name'].

Calling methods and accessing properties (depending on the access attribute) is done in the normal way:

obj.SomeMethod() (returns a single value, a tuple or None)

obj.SomeProperty (only with read access)

obj.SomeProperty = value (only with write access)

Signal handlers can be set by assigning a function that takes a MessageInfo object as its only argument: obj.SomeSignal = function. The handler can be removed by assigning None.

D-Car

Navigation

Related Topics

API Reference¶

Overview¶