DBusProxy#

Added in version 2.26.

class DBusProxy(**properties: Any)#

Superclasses: Object

Implemented Interfaces: AsyncInitable, DBusInterface, Initable

Provide comfortable and pythonic method calls.

This marshalls the method arguments into a GVariant, invokes the call_sync() method on the DBusProxy object, and unmarshalls the result GVariant back into a Python tuple.

The first argument always needs to be the D-Bus signature tuple of the method call. Example:

proxy = Gio.DBusProxy.new_sync(…) result = proxy.MyMethod(‘(is)’, 42, ‘hello’)

The exception are methods which take no arguments, like proxy.MyMethod(‘()’). For these you can omit the signature and just write proxy.MyMethod().

Optional keyword arguments:

  • timeout: timeout for the call in milliseconds (default to D-Bus timeout)

  • flags: Combination of Gio.DBusCallFlags.*

  • result_handler: Do an asynchronous method call and invoke

    result_handler(proxy_object, result, user_data) when it finishes.

  • error_handler: If the asynchronous call raises an exception, error_handler(proxy_object, exception, user_data) is called when it finishes. If error_handler is not given, result_handler is called with the exception object as result instead.

  • user_data: Optional user data to pass to result_handler for asynchronous calls.

Example for asynchronous calls:

def mymethod_done(proxy, result, user_data):
if isinstance(result, Exception):

# handle error

else:

# do something with result

proxy.MyMethod(‘(is)’, 42, ‘hello’,

result_handler=mymethod_done, user_data=’data’)

Constructors#

class DBusProxy
classmethod new_finish(res: AsyncResult) → DBusProxy#

Finishes creating a DBusProxy.

Added in version 2.26.

Parameters:

res – A AsyncResult obtained from the AsyncReadyCallback function passed to new().

classmethod new_for_bus_finish(res: AsyncResult) → DBusProxy#

Finishes creating a DBusProxy.

Added in version 2.26.

Parameters:

res – A AsyncResult obtained from the AsyncReadyCallback function passed to new_for_bus().

classmethod new_for_bus_sync(bus_type: BusType, flags: DBusProxyFlags, info: DBusInterfaceInfo | None, name: str, object_path: str, interface_name: str, cancellable: Cancellable | None = None) → DBusProxy#

Like new_sync() but takes a BusType instead of a DBusConnection.

DBusProxy is used in this [example][gdbus-wellknown-proxy].

Added in version 2.26.

Parameters:

  • bus_type – A BusType.

  • flags – Flags used when constructing the proxy.

  • info – A DBusInterfaceInfo specifying the minimal interface that proxy conforms to or None.

  • name – A bus name (well-known or unique).

  • object_path – An object path.

  • interface_name – A D-Bus interface name.

  • cancellable – A Cancellable or None.

classmethod new_sync(connection: DBusConnection, flags: DBusProxyFlags, info: DBusInterfaceInfo | None, name: str | None, object_path: str, interface_name: str, cancellable: Cancellable | None = None) → DBusProxy#

Creates a proxy for accessing interface_name on the remote object at object_path owned by name at connection and synchronously loads D-Bus properties unless the DO_NOT_LOAD_PROPERTIES flag is used.

If the DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the DBusProxy::g-signal signal to handle signals from the remote object.

If both DO_NOT_LOAD_PROPERTIES and DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to return immediately without blocking.

If name is a well-known name and the DO_NOT_AUTO_START and DO_NOT_AUTO_START_AT_CONSTRUCTION flags aren’t set and no name owner currently exists, the message bus will be requested to launch a name owner for the name.

This is a synchronous failable constructor. See new() and new_finish() for the asynchronous version.

DBusProxy is used in this [example][gdbus-wellknown-proxy].

Added in version 2.26.

Parameters:

  • connection – A DBusConnection.

  • flags – Flags used when constructing the proxy.

  • info – A DBusInterfaceInfo specifying the minimal interface that proxy conforms to or None.

  • name – A bus name (well-known or unique) or None if connection is not a message bus connection.

  • object_path – An object path.

  • interface_name – A D-Bus interface name.

  • cancellable – A Cancellable or None.

Methods#

class DBusProxy
call(method_name: str, parameters: Variant | None, flags: DBusCallFlags, timeout_msec: int, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

Asynchronously invokes the method_name method on proxy.

If method_name contains any dots, then name is split into interface and method name parts. This allows using proxy for invoking methods on other interfaces.

If the DBusConnection associated with proxy is closed then the operation will fail with CLOSED. If cancellable is canceled, the operation will fail with CANCELLED. If parameters contains a value not compatible with the D-Bus protocol, the operation fails with INVALID_ARGUMENT.

If the parameters Variant is floating, it is consumed. This allows convenient ‘inline’ use of new(), e.g.:

g_dbus_proxy_call (proxy,
                   "TwoStrings",
                   g_variant_new ("(ss)",
                                  "Thing One",
                                  "Thing Two"),
                   G_DBUS_CALL_FLAGS_NONE,
                   -1,
                   NULL,
                   (GAsyncReadyCallback) two_strings_done,
                   &data);

If proxy has an expected interface (see DBusProxy:g-interface-info) and method_name is referenced by it, then the return value is checked against the return type.

This is an asynchronous method. When the operation is finished, callback will be invoked in the [thread-default main context][g-main-context-push-thread-default] of the thread you are calling this method from. You can then call call_finish() to get the result of the operation. See call_sync() for the synchronous version of this method.

If callback is None then the D-Bus method call message will be sent with the NO_REPLY_EXPECTED flag set.

Added in version 2.26.

Parameters:

  • method_name – Name of method to invoke.

  • parameters – A Variant tuple with parameters for the signal or None if not passing parameters.

  • flags – Flags from the DBusCallFlags enumeration.

  • timeout_msec – The timeout in milliseconds (with %G_MAXINT meaning “infinite”) or -1 to use the proxy default timeout.

  • cancellable – A Cancellable or None.

  • callback – A AsyncReadyCallback to call when the request is satisfied or None if you don’t care about the result of the method invocation.

  • user_data – The data to pass to callback.

call_finish(res: AsyncResult) → Variant#

Finishes an operation started with call().

Added in version 2.26.

Parameters:

res – A AsyncResult obtained from the AsyncReadyCallback passed to call().

call_sync(method_name: str, parameters: Variant | None, flags: DBusCallFlags, timeout_msec: int, cancellable: Cancellable | None = None) → Variant#

Synchronously invokes the method_name method on proxy.

If method_name contains any dots, then name is split into interface and method name parts. This allows using proxy for invoking methods on other interfaces.

If the DBusConnection associated with proxy is disconnected then the operation will fail with CLOSED. If cancellable is canceled, the operation will fail with CANCELLED. If parameters contains a value not compatible with the D-Bus protocol, the operation fails with INVALID_ARGUMENT.

If the parameters Variant is floating, it is consumed. This allows convenient ‘inline’ use of new(), e.g.:

g_dbus_proxy_call_sync (proxy,
                        "TwoStrings",
                        g_variant_new ("(ss)",
                                       "Thing One",
                                       "Thing Two"),
                        G_DBUS_CALL_FLAGS_NONE,
                        -1,
                        NULL,
                        &error);

The calling thread is blocked until a reply is received. See call() for the asynchronous version of this method.

If proxy has an expected interface (see DBusProxy:g-interface-info) and method_name is referenced by it, then the return value is checked against the return type.

Added in version 2.26.

Parameters:

  • method_name – Name of method to invoke.

  • parameters – A Variant tuple with parameters for the signal or None if not passing parameters.

  • flags – Flags from the DBusCallFlags enumeration.

  • timeout_msec – The timeout in milliseconds (with %G_MAXINT meaning “infinite”) or -1 to use the proxy default timeout.

  • cancellable – A Cancellable or None.

call_with_unix_fd_list(method_name: str, parameters: Variant | None, flags: DBusCallFlags, timeout_msec: int, fd_list: UnixFDList | None = None, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

Like call() but also takes a UnixFDList object.

This method is only available on UNIX.

Added in version 2.30.

Parameters:

  • method_name – Name of method to invoke.

  • parameters – A Variant tuple with parameters for the signal or None if not passing parameters.

  • flags – Flags from the DBusCallFlags enumeration.

  • timeout_msec – The timeout in milliseconds (with %G_MAXINT meaning “infinite”) or -1 to use the proxy default timeout.

  • fd_list – A UnixFDList or None.

  • cancellable – A Cancellable or None.

  • callback – A AsyncReadyCallback to call when the request is satisfied or None if you don’t care about the result of the method invocation.

  • user_data – The data to pass to callback.

call_with_unix_fd_list_finish(res: AsyncResult) → Tuple[Variant, UnixFDList]#

Finishes an operation started with call_with_unix_fd_list().

Added in version 2.30.

Parameters:

res – A AsyncResult obtained from the AsyncReadyCallback passed to call_with_unix_fd_list().

call_with_unix_fd_list_sync(method_name: str, parameters: Variant | None, flags: DBusCallFlags, timeout_msec: int, fd_list: UnixFDList | None = None, cancellable: Cancellable | None = None) → Tuple[Variant, UnixFDList]#

Like call_sync() but also takes and returns UnixFDList objects.

This method is only available on UNIX.

Added in version 2.30.

Parameters:

  • method_name – Name of method to invoke.

  • parameters – A Variant tuple with parameters for the signal or None if not passing parameters.

  • flags – Flags from the DBusCallFlags enumeration.

  • timeout_msec – The timeout in milliseconds (with %G_MAXINT meaning “infinite”) or -1 to use the proxy default timeout.

  • fd_list – A UnixFDList or None.

  • cancellable – A Cancellable or None.

do_g_properties_changed(self, changed_properties: Variant, invalidated_properties: str) → None#
Parameters:

  • changed_properties

  • invalidated_properties

do_g_signal(self, sender_name: str, signal_name: str, parameters: Variant) → None#
Parameters:

  • sender_name

  • signal_name

  • parameters

get_cached_property(property_name: str) → Variant | None#

Looks up the value for a property from the cache. This call does no blocking IO.

If proxy has an expected interface (see DBusProxy:g-interface-info) and property_name is referenced by it, then value is checked against the type of the property.

Added in version 2.26.

Parameters:

property_name – Property name.

get_cached_property_names() → list[str] | None#

Gets the names of all cached properties on proxy.

Added in version 2.26.

get_connection() → DBusConnection#

Gets the connection proxy is for.

Added in version 2.26.

get_default_timeout() → int#

Gets the timeout to use if -1 (specifying default timeout) is passed as timeout_msec in the call() and call_sync() functions.

See the DBusProxy:g-default-timeout property for more details.

Added in version 2.26.

get_flags() → DBusProxyFlags#

Gets the flags that proxy was constructed with.

Added in version 2.26.

get_interface_info() → DBusInterfaceInfo | None#

Returns the DBusInterfaceInfo, if any, specifying the interface that proxy conforms to. See the DBusProxy:g-interface-info property for more details.

Added in version 2.26.

get_interface_name() → str#

Gets the D-Bus interface name proxy is for.

Added in version 2.26.

get_name() → str | None#

Gets the name that proxy was constructed for.

When connected to a message bus, this will usually be non-None. However, it may be None for a proxy that communicates using a peer-to-peer pattern.

Added in version 2.26.

get_name_owner() → str | None#

The unique name that owns the name that proxy is for or None if no-one currently owns that name. You may connect to the Object::notify signal to track changes to the DBusProxy:g-name-owner property.

Added in version 2.26.

get_object_path() → str#

Gets the object path proxy is for.

Added in version 2.26.

classmethod new(flags: DBusProxyFlags, info: DBusInterfaceInfo | None, name: str | None, object_path: str, interface_name: str, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

Creates a proxy for accessing interface_name on the remote object at object_path owned by name at connection and asynchronously loads D-Bus properties unless the DO_NOT_LOAD_PROPERTIES flag is used. Connect to the DBusProxy::g-properties-changed signal to get notified about property changes.

If the DO_NOT_CONNECT_SIGNALS flag is not set, also sets up match rules for signals. Connect to the DBusProxy::g-signal signal to handle signals from the remote object.

If both DO_NOT_LOAD_PROPERTIES and DO_NOT_CONNECT_SIGNALS are set, this constructor is guaranteed to complete immediately without blocking.

If name is a well-known name and the DO_NOT_AUTO_START and DO_NOT_AUTO_START_AT_CONSTRUCTION flags aren’t set and no name owner currently exists, the message bus will be requested to launch a name owner for the name.

This is a failable asynchronous constructor - when the proxy is ready, callback will be invoked and you can use new_finish() to get the result.

See new_sync() and for a synchronous version of this constructor.

DBusProxy is used in this [example][gdbus-wellknown-proxy].

Added in version 2.26.

Parameters:

  • flags – Flags used when constructing the proxy.

  • info – A DBusInterfaceInfo specifying the minimal interface that proxy conforms to or None.

  • name – A bus name (well-known or unique) or None if connection is not a message bus connection.

  • object_path – An object path.

  • interface_name – A D-Bus interface name.

  • cancellable – A Cancellable or None.

  • callback – Callback function to invoke when the proxy is ready.

  • user_data – User data to pass to callback.

classmethod new_for_bus(flags: DBusProxyFlags, info: DBusInterfaceInfo | None, name: str, object_path: str, interface_name: str, cancellable: Cancellable | None = None, callback: Callable[[Object | None, AsyncResult, Any], None] | None = None, user_data: Any = None) → None#

Like new() but takes a BusType instead of a DBusConnection.

DBusProxy is used in this [example][gdbus-wellknown-proxy].

Added in version 2.26.

Parameters:

  • flags – Flags used when constructing the proxy.

  • info – A DBusInterfaceInfo specifying the minimal interface that proxy conforms to or None.

  • name – A bus name (well-known or unique).

  • object_path – An object path.

  • interface_name – A D-Bus interface name.

  • cancellable – A Cancellable or None.

  • callback – Callback function to invoke when the proxy is ready.

  • user_data – User data to pass to callback.

set_cached_property(property_name: str, value: Variant | None = None) → None#

If value is not None, sets the cached value for the property with name property_name to the value in value.

If value is None, then the cached value is removed from the property cache.

If proxy has an expected interface (see DBusProxy:g-interface-info) and property_name is referenced by it, then value is checked against the type of the property.

If the value Variant is floating, it is consumed. This allows convenient ‘inline’ use of new(), e.g.

g_dbus_proxy_set_cached_property (proxy,
                                  "SomeProperty",
                                  g_variant_new ("(si)",
                                                "A String",
                                                42));

Normally you will not need to use this method since proxy is tracking changes using the org.freedesktop.DBus.Properties.PropertiesChanged D-Bus signal. However, for performance reasons an object may decide to not use this signal for some properties and instead use a proprietary out-of-band mechanism to transmit changes.

As a concrete example, consider an object with a property ChatroomParticipants which is an array of strings. Instead of transmitting the same (long) array every time the property changes, it is more efficient to only transmit the delta using e.g. signals ChatroomParticipantJoined(String name) and ChatroomParticipantParted(String name).

Added in version 2.26.

Parameters:

  • property_name – Property name.

  • value – Value for the property or None to remove it from the cache.

set_default_timeout(timeout_msec: int) → None#

Sets the timeout to use if -1 (specifying default timeout) is passed as timeout_msec in the call() and call_sync() functions.

See the DBusProxy:g-default-timeout property for more details.

Added in version 2.26.

Parameters:

timeout_msec – Timeout in milliseconds.

set_interface_info(info: DBusInterfaceInfo | None = None) → None#

Ensure that interactions with proxy conform to the given interface. See the DBusProxy:g-interface-info property for more details.

Added in version 2.26.

Parameters:

info – Minimum interface this proxy conforms to or None to unset.

Properties#

class DBusProxy
props.g_bus_type: BusType#

The type of the None singleton.

Added in version 2.26.

props.g_connection: DBusConnection#

The type of the None singleton.

Added in version 2.26.

props.g_default_timeout: int#

The type of the None singleton.

Added in version 2.26.

props.g_flags: DBusProxyFlags#

The type of the None singleton.

Added in version 2.26.

props.g_interface_info: DBusInterfaceInfo#

The type of the None singleton.

Added in version 2.26.

props.g_interface_name: str#

The type of the None singleton.

Added in version 2.26.

props.g_name: str#

The type of the None singleton.

Added in version 2.26.

props.g_name_owner: str#

The type of the None singleton.

Added in version 2.26.

props.g_object_path: str#

The type of the None singleton.

Added in version 2.26.

Signals#

class DBusProxy.signals
g_properties_changed(changed_properties: Variant, invalidated_properties: list[str]) → None#

The type of the None singleton.

Added in version 2.26.

Parameters:

  • changed_properties – A Variant containing the properties that changed (type: a{sv})

  • invalidated_properties – A None terminated array of properties that was invalidated

g_signal(sender_name: str | None, signal_name: str, parameters: Variant) → None#

The type of the None singleton.

Added in version 2.26.

Parameters:

  • sender_name – The sender of the signal or None if the connection is not a bus connection.

  • signal_name – The name of the signal.

  • parameters – A Variant tuple with parameters for the signal.

Virtual Methods#

class DBusProxy
do_g_properties_changed(changed_properties: Variant, invalidated_properties: str) → None#

The type of the None singleton.

Parameters:

  • changed_properties

  • invalidated_properties

do_g_signal(sender_name: str, signal_name: str, parameters: Variant) → None#

The type of the None singleton.

Parameters:

  • sender_name

  • signal_name

  • parameters

Fields#

class DBusProxy
parent_instance#
priv#