Common API

These calls are shared between async and blocking API.

D-Bus connections calls

async sdbus.request_default_bus_name_async(new_name, allow_replacement, replace_existing, queue)

Acquire a name on the default bus async.

Parameters:

new_name (str) – the name to acquire. Must be a valid D-Bus service name.
new_name – the name to acquire. Must be a valid D-Bus service name.
allow_replacement (bool) – If name was acquired allow other peers to take away the name.
replace_existing (bool) – If current name owner allows, take away the name.
queue (bool) – Queue up for name acquisition. SdBusRequestNameInQueueError will be raised when successfully placed in queue. Ownership change signal should be monitored get notified when the name was acquired.

Raises:

Name request exceptions and other D-Bus exceptions.

sdbus.request_default_bus_name(new_name, allow_replacement, replace_existing, queue)

Acquire a name on the default bus.

Parameters:

new_name (str) – the name to acquire. Must be a valid D-Bus service name.
allow_replacement (bool) – If name was acquired allow other peers to take away the name.
replace_existing (bool) – If current name owner allows, take away the name.
queue (bool) – Queue up for name acquisition. SdBusRequestNameInQueueError will be raised when successfully placed in queue. Ownership change signal should be monitored get notified when the name was acquired.

Raises:

Name request exceptions and other D-Bus exceptions.

sdbus.set_default_bus(new_default)

Sets default bus.

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

Default bus can be replaced but the change will only affect newly created objects.

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

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

from sdbus import encode_object_path


# System uses /org/freedesktop/systemd1/unit as prefix of all units
# dbus.service is a name of D-Bus 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.