Common API

These calls are shared between async and blocking API.

Dbus connections calls

async sdbus.request_default_bus_name_async(new_name)

Acquire a name on the default bus async.

Parameters

new_name (str) – the name to acquire. Must be a valid dbus service name.

sdbus.request_default_bus_name(new_name)

Acquire a name on the default bus.

Parameters

new_name (str) – the name to acquire. Must be a valid dbus service name.

sdbus.set_default_bus(new_default)

Sets default bus.

Should be called before you create any objects that might use default bus.

Parameters

new_default (SdBus) – The bus object to set default to.

Raises

RuntimeError – if default bus is already set.

sdbus.get_default_bus(new_default)

Gets default bus.

Returns

default bus

Return type

SdBus

sdbus.sd_bus_open_user()

Opens a new user session bus connection.

Returns

session bus

Return type

SdBus

sdbus.sd_bus_open_system()

Opens a new system bus connection.

Returns

system bus

Return type

SdBus

sdbus.sd_bus_open_system_remote(host)

Opens a new system bus connection on a remote host through SSH. Host can be prefixed with username@ and followed by :port and /machine_name as in systemd-nspawn container name.

Parameters

host (str) – Host name to connect.

Returns

Remote system bus

Return type

SdBus

sdbus.sd_bus_open_system_machine(machine)

Opens a new system bus connection in a systemd-nspawn container. Machine name can be prefixed with username@. Special machine name .host indicates local system.

Parameters

machine (str) – Machine (container) name.

Returns

Remote system bus

Return type

SdBus

sdbus.sd_bus_open_user_machine(machine)

Opens a new user session bus connection in a systemd-nspawn container. Opens root user bus session or can be prefixed with username@ for a specific user.

Parameters

machine (str) – Machine (container) name.

Returns

Remote system bus

Return type

SdBus

Helper functions

sdbus.encode_object_path(prefix, external)

Encode that arbitrary string as a valid object path prefixed with prefix.

Parameters
  • prefix (str) – Prefix path. Must be a valid object path.

  • external (str) – Arbitrary string to identify object.

Returns

valid object path

Return type

str

Example on how systemd encodes unit names on dbus:

from sdbus import encode_object_path


# System uses /org/freedesktop/systemd1/unit as prefix of all units
# dbus.service is a name of dbus unit but dot . is not a valid object path
s = encode_object_path('/org/freedesktop/systemd1/unit', 'dbus.service')
print(s)
# Prints: /org/freedesktop/systemd1/unit/dbus_2eservice
sdbus.decode_object_path(prefix, full_path)

Decode object name that was encoded with encode_object_path().

Parameters
  • prefix (str) – Prefix path. Must be a valid object path.

  • full_path (str) – Full path to be decoded.

Returns

Arbitrary name

Return type

str

Example decoding systemd unit name:

from sdbus import decode_object_path


s = decode_object_path(
    '/org/freedesktop/systemd1/unit',
    '/org/freedesktop/systemd1/unit/dbus_2eservice'
)
print(s)
# Prints: dbus.service

Flags

Flags are int values that should be ORed to combine.

Example, DbusDeprecatedFlag plus DbusHiddenFlag: DbusDeprecatedFlag | DbusHiddenFlag

sdbus.DbusDeprecatedFlag: int

Mark this method or property as deprecated in introspection data.

sdbus.DbusHiddenFlag: int

Method or property will not show up in introspection data.

sdbus.DbusUnprivilegedFlag: int

Mark this method or property as unprivileged. This means anyone can call it. Only works for system bus as user session bus is fully trusted by default.

sdbus.DbusNoReplyFlag: int

This method does not have a reply message. It instantly returns and does not have any errors.

sdbus.DbusPropertyConstFlag: int

Mark that this property does not change during object life time.

sdbus.DbusPropertyEmitsChangeFlag: int

This property emits signal when it changes.

sdbus.DbusPropertyEmitsInvalidationFlag: int

This property emits signal when it invalidates. (means the value changed but does not include new value in the signal)

sdbus.DbusPropertyExplicitFlag: int

This property is too heavy to calculate so its not included in GetAll method call.

sdbus.DbusSensitiveFlag: int

Data in messages in sensitive and will be scrubbed from memory after message is red.