# 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() → Message | None

    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: 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