Core API

Message constructors

jeepney.new_method_call(remote_obj, method, signature=None, body=())

Construct a new method call message

This is a relatively low-level method. In many cases, this will be called from a MessageGenerator subclass which provides a more convenient API.

Parameters

• remote_obj (DBusAddress) – The object to call a method on

• method (str) – The name of the method to call

• signature (str) – The DBus signature of the body data

• body (tuple) – Body data (i.e. method parameters)

jeepney.new_method_return(parent_msg, signature=None, body=())

Construct a new response message

Parameters

• parent_msg (Message) – The method call this is a reply to

• signature (str) – The DBus signature of the body data

• body (tuple) – Body data

jeepney.new_error(parent_msg, error_name, signature=None, body=())

Construct a new error response message

Parameters

• parent_msg (Message) – The method call this is a reply to

• error_name (str) – The name of the error

• signature (str) – The DBus signature of the body data

• body (tuple) – Body data

jeepney.new_signal(emitter, signal, signature=None, body=())

Construct a new signal message

Parameters

• emitter (DBusAddress) – The object sending the signal

• signal (str) – The name of the signal

• signature (str) – The DBus signature of the body data

• body (tuple) – Body data

class jeepney.DBusAddress(object_path, bus_name=None, interface=None)

This identifies the object and interface a message is for.

e.g. messages to display desktop notifications would have this address:

DBusAddress('/org/freedesktop/Notifications',
            bus_name='org.freedesktop.Notifications',
            interface='org.freedesktop.Notifications')

class jeepney.MessageGenerator(object_path, bus_name)

Subclass this to define the methods available on a DBus interface.

jeepney.bindgen can automatically create subclasses using introspection.

See also

Generating D-Bus wrappers

Parsing

class jeepney.Parser

Parse DBus messages from a stream of incoming data.

add_data(data: bytes, fds=())

Provide newly received data to the parser

get_next_message() → Optional[jeepney.low_level.Message]

Parse one message, if there is enough data.

Returns None if it doesn’t have a complete message.

Message objects

class jeepney.Message(header, body)

Object representing a DBus message.

It’s not normally necessary to construct this directly: use higher level functions and methods instead.

header

A Header object

body

A tuple of the data in this message. The number and types of the elements depend on the message’s signature:

D-Bus type	D-Bus code	Python type
BYTE	y	int
BOOLEAN	b	bool
INT16	n	int
UINT16	q	int
INT32	i	int
UINT32	u	int
INT64	x	int
UINT64	t	int
DOUBLE	d	float
STRING	s	str
OBJECT_PATH	o	str
SIGNATURE	g	str
ARRAY	a	list
STRUCT	()	tuple
VARIANT	v	2-tuple (signature, value)
DICT_ENTRY	{}	dict (for array of dict entries)
UNIX_FD	h	See Sending & receiving file descriptors

serialise(serial=None, fds=None) → bytes

Convert this message to bytes.

Specifying serial overrides the msg.header.serial field, so a connection can use its own serial number without modifying the message.

If file-descriptor support is in use, fds should be a array.array object with type 'i'. Any file descriptors in the message will be added to the array. If the message contains FDs, it can’t be serialised without this array.

class jeepney.Header(endianness, message_type, flags, protocol_version, body_length, serial, fields)

endianness

Endianness object, affecting message serialisation.

message_type

MessageType object.

flags

MessageFlag object.

protocol_version

Currently always 1.

body_length

The length of the raw message body in bytes.

serial

Sender’s serial number for this message. This is not necessarily set for outgoing messages - see Message.serialise().

fields

Mapping of HeaderFields values to the relevant Python objects.

Exceptions

exception jeepney.SizeLimitError

Raised when trying to (de-)serialise data exceeding D-Bus’ size limit.

This is currently only implemented for arrays, where the maximum size is 64 MiB.

exception jeepney.DBusErrorResponse(msg)

Raised by proxy method calls when the reply is an error message

name

The error name from the remote end.

body

Any data fields contained in the error message.

Enums & Flags

class jeepney.Endianness

little = 1

big = 2

class jeepney.HeaderFields

path = 1

interface = 2

member = 3

error_name = 4

reply_serial = 5

destination = 6

sender = 7

signature = 8

unix_fds = 9

class jeepney.MessageFlag

no_reply_expected = 1

On a method call message, indicates that a reply should not be sent.

no_auto_start = 2

D-Bus includes a mechanism to start a service on demand to handle messages. If this flag is set, it will avoid that, only handling the message if the target is already running.

allow_interactive_authorization = 4

Signals that the recipient may prompt the user for elevated privileges to handle the request. The D-Bus specification has more details.

class jeepney.MessageType

method_call = 1

method_return = 2

error = 3

signal = 4

Matching messages

class jeepney.MatchRule(*, type=None, sender=None, interface=None, member=None, path=None, path_namespace=None, destination=None, eavesdrop=False)

Construct a match rule to subscribe to DBus messages.

e.g.:

mr = MatchRule(
    interface='org.freedesktop.DBus',
    member='NameOwnerChanged',
    type='signal'
)
msg = message_bus.AddMatch(mr)
# Send this message to subscribe to the signal

MatchRule objects are used both for filtering messages internally, and for setting up subscriptions in the message bus.

add_arg_condition(argno: int, value: str, kind='string')

Add a condition for a particular argument

argno: int, 0-63 kind: ‘string’, ‘path’, ‘namespace’

matches(msg: jeepney.low_level.Message) → bool

Returns True if msg matches this rule

serialise() → str

Convert to a string to use in an AddMatch call to the message bus