Common API

These calls are shared between async and blocking API.

Default bus

sdbus.default_bus.get_default_bus() → SdBus

Get default bus.

Returns context-local default bus if set or thread-local otherwise.

If no default bus is set initializes a new bus using sdbus.sd_bus_open() and sets it as a thread-local default bus.

sdbus.default_bus.set_default_bus(new_default: SdBus) → None

Set thread-local default bus.

Should be called before creating any objects that will use default bus.

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

sdbus.default_bus.set_context_default_bus(new_default: SdBus) → Token[SdBus]

Set context-local default bus.

Should be called before creating any objects that will use default bus.

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

Context-local default bus has higher priority over thread-local one but has to be explicitly set.

Returns:: Token that can be used to reset context bus back. See contextvars documentation for details.

async sdbus.default_bus.request_default_bus_name_async(new_name: str, allow_replacement: bool = False, replace_existing: bool = False, queue: bool = False) → None

Asynchronously acquire a name on the default bus.

Parameters:

new_name – Name to acquire. Must be a valid D-Bus service name.
allow_replacement – If name was acquired allow other D-Bus peers to take away the name.
replace_existing – If current name owner allows, take away the name.
queue – 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.default_bus.request_default_bus_name(new_name: str, allow_replacement: bool = False, replace_existing: bool = False, queue: bool = False) → None

Acquire a name on the default bus.

Blocks until a reply is received from D-Bus daemon.

Parameters:

new_name – Name to acquire. Must be a valid D-Bus service name.
allow_replacement – If name was acquired allow other D-Bus peers to take away the name.
replace_existing – If current name owner allows, take away the name.
queue – 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.

D-Bus connections calls

sdbus.sd_bus_open()

Opens a new bus connection. The session bus will be opened when available or system bus otherwise.

Returns:: Session or system 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.