dbus-fast 2.44.6__cp313-cp313-manylinux_2_36_x86_64.whl

dbus_fast/aio/proxy_object.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from typing import TYPE_CHECKING, Any
+
+from .. import introspection as intr
+from .._private.util import replace_fds_with_idx, replace_idx_with_fds
+from ..constants import ErrorType, MessageFlag
+from ..errors import DBusError
+from ..message import Message
+from ..message_bus import BaseMessageBus
+from ..proxy_object import BaseProxyInterface, BaseProxyObject
+from ..signature import Variant
+from ..unpack import unpack_variants as unpack
+
+if TYPE_CHECKING:
+    from .message_bus import MessageBus as AioMessageBus
+
+NO_REPLY_EXPECTED_VALUE = MessageFlag.NO_REPLY_EXPECTED.value
+
+
+class ProxyInterface(BaseProxyInterface):
+    """A class representing a proxy to an interface exported on the bus by
+    another client for the asyncio :class:`MessageBus
+    <dbus_fast.aio.MessageBus>` implementation.
+
+    This class is not meant to be constructed directly by the user. Use
+    :func:`ProxyObject.get_interface()
+    <dbus_fast.aio.ProxyObject.get_interface>` on a asyncio proxy object to get
+    a proxy interface.
+
+    This class exposes methods to call DBus methods, listen to signals, and get
+    and set properties on the interface that are created dynamically based on
+    the introspection data passed to the proxy object that made this proxy
+    interface.
+
+    A *method call* takes this form:
+
+    .. code-block:: python3
+
+        result = await interface.call_[METHOD](*args)
+
+    Where ``METHOD`` is the name of the method converted to snake case.
+
+    DBus methods are exposed as coroutines that take arguments that correpond
+    to the *in args* of the interface method definition and return a ``result``
+    that corresponds to the *out arg*. If the method has more than one out arg,
+    they are returned within a :class:`list`.
+
+    To *listen to a signal* use this form:
+
+    .. code-block:: python3
+
+        interface.on_[SIGNAL](callback)
+
+    To *stop listening to a signal* use this form:
+
+    .. code-block:: python3
+
+        interface.off_[SIGNAL](callback)
+
+    Where ``SIGNAL`` is the name of the signal converted to snake case.
+
+    DBus signals are exposed with an event-callback interface. The provided
+    ``callback`` will be called when the signal is emitted with arguments that
+    correspond to the *out args* of the interface signal definition.
+
+    To *get or set a property* use this form:
+
+    .. code-block:: python3
+
+        value = await interface.get_[PROPERTY]()
+        await interface.set_[PROPERTY](value)
+
+    Where ``PROPERTY`` is the name of the property converted to snake case.
+
+    DBus property getters and setters are exposed as coroutines. The ``value``
+    must correspond to the type of the property in the interface definition.
+
+    If the service returns an error for a DBus call, a :class:`DBusError
+    <dbus_fast.DBusError>` will be raised with information about the error.
+    """
+
+    bus: AioMessageBus
+
+    def _add_method(self, intr_method: intr.Method) -> None:
+        async def method_fn(
+            *args, flags=MessageFlag.NONE, unpack_variants: bool = False
+        ):
+            input_body, unix_fds = replace_fds_with_idx(
+                intr_method.in_signature, list(args)
+            )
+
+            msg = await self.bus.call(
+                Message(
+                    destination=self.bus_name,
+                    path=self.path,
+                    interface=self.introspection.name,
+                    member=intr_method.name,
+                    signature=intr_method.in_signature,
+                    body=input_body,
+                    flags=flags,
+                    unix_fds=unix_fds,
+                )
+            )
+
+            if flags is not None and flags.value & NO_REPLY_EXPECTED_VALUE:
+                return None
+
+            BaseProxyInterface._check_method_return(msg, intr_method.out_signature)
+
+            out_len = len(intr_method.out_args)
+
+            body = replace_idx_with_fds(msg.signature_tree, msg.body, msg.unix_fds)
+
+            if not out_len:
+                return None
+
+            if unpack_variants:
+                body = unpack(body)
+
+            if out_len == 1:
+                return body[0]
+            return body
+
+        method_name = f"call_{BaseProxyInterface._to_snake_case(intr_method.name)}"
+        setattr(self, method_name, method_fn)
+
+    def _add_property(
+        self,
+        intr_property: intr.Property,
+    ) -> None:
+        async def property_getter(
+            *, flags=MessageFlag.NONE, unpack_variants: bool = False
+        ):
+            msg = await self.bus.call(
+                Message(
+                    destination=self.bus_name,
+                    path=self.path,
+                    interface="org.freedesktop.DBus.Properties",
+                    member="Get",
+                    signature="ss",
+                    body=[self.introspection.name, intr_property.name],
+                )
+            )
+
+            BaseProxyInterface._check_method_return(msg, "v")
+            variant = msg.body[0]
+            if variant.signature != intr_property.signature:
+                raise DBusError(
+                    ErrorType.CLIENT_ERROR,
+                    f'property returned unexpected signature "{variant.signature}"',
+                    msg,
+                )
+
+            body = replace_idx_with_fds("v", msg.body, msg.unix_fds)[0].value
+
+            if unpack_variants:
+                return unpack(body)
+            return body
+
+        async def property_setter(val: Any) -> None:
+            variant = Variant(intr_property.signature, val)
+
+            body, unix_fds = replace_fds_with_idx(
+                "ssv", [self.introspection.name, intr_property.name, variant]
+            )
+
+            msg = await self.bus.call(
+                Message(
+                    destination=self.bus_name,
+                    path=self.path,
+                    interface="org.freedesktop.DBus.Properties",
+                    member="Set",
+                    signature="ssv",
+                    body=body,
+                    unix_fds=unix_fds,
+                )
+            )
+
+            BaseProxyInterface._check_method_return(msg)
+
+        snake_case = BaseProxyInterface._to_snake_case(intr_property.name)
+        setattr(self, f"get_{snake_case}", property_getter)
+        setattr(self, f"set_{snake_case}", property_setter)
+
+
+class ProxyObject(BaseProxyObject):
+    """The proxy object implementation for the GLib :class:`MessageBus <dbus_fast.glib.MessageBus>`.
+
+    For more information, see the :class:`BaseProxyObject <dbus_fast.proxy_object.BaseProxyObject>`.
+    """
+
+    def __init__(
+        self,
+        bus_name: str,
+        path: str,
+        introspection: intr.Node | str | ET.Element,
+        bus: BaseMessageBus,
+    ) -> None:
+        super().__init__(bus_name, path, introspection, bus, ProxyInterface)
+
+    def get_interface(self, name: str) -> ProxyInterface:
+        return super().get_interface(name)
+
+    def get_children(self) -> list[ProxyObject]:
+        return super().get_children()

dbus_fast/auth.py

@@ -0,0 +1,126 @@
+import enum
+import os
+from typing import Optional
+
+from .errors import AuthError
+
+UID_NOT_SPECIFIED = -1
+
+# The auth interface here is unstable. I would like to eventually open this up
+# for people to define their own custom authentication protocols, but I'm not
+# familiar with what's needed for that exactly. To work with any message bus
+# implementation would require abstracting out all the IO. Async operations
+# might be challenging because different IO backends have different ways of
+# doing that. I might just end up giving the raw socket and leaving it all up
+# to the user, but it would be nice to have a little guidance in the interface
+# since a lot of it is strongly specified. If you have a need for this, contact
+# the project maintainer to help stabilize this interface.
+
+
+class _AuthResponse(enum.Enum):
+    OK = "OK"
+    REJECTED = "REJECTED"
+    DATA = "DATA"
+    ERROR = "ERROR"
+    AGREE_UNIX_FD = "AGREE_UNIX_FD"
+
+    @classmethod
+    def parse(klass, line: str) -> tuple["_AuthResponse", list[str]]:
+        args = line.split(" ")
+        response = klass(args[0])
+        return response, args[1:]
+
+
+# UNSTABLE
+class Authenticator:
+    """The base class for authenticators for :class:`MessageBus <dbus_fast.message_bus.BaseMessageBus>` authentication.
+
+    In the future, the library may allow extending this class for custom authentication protocols.
+
+    :seealso: https://dbus.freedesktop.org/doc/dbus-specification.html#auth-protocol
+    """
+
+    def _authentication_start(self, negotiate_unix_fd: bool = False) -> str:
+        raise NotImplementedError(
+            "authentication_start() must be implemented in the inheriting class"
+        )
+
+    def _receive_line(self, line: str) -> str:
+        raise NotImplementedError(
+            "receive_line() must be implemented in the inheriting class"
+        )
+
+    @staticmethod
+    def _format_line(line: str) -> bytes:
+        return f"{line}\r\n".encode()
+
+
+class AuthExternal(Authenticator):
+    """An authenticator class for the external auth protocol for use with the
+    :class:`MessageBus <dbus_fast.message_bus.BaseMessageBus>`.
+
+    :param uid: The uid to use when connecting to the message bus. Use UID_NOT_SPECIFIED to use the uid known to the kernel.
+    :vartype uid: int
+
+    :sealso: https://dbus.freedesktop.org/doc/dbus-specification.html#auth-protocol
+    """
+
+    def __init__(self, uid: Optional[int] = None) -> None:
+        self.negotiate_unix_fd: bool = False
+        self.negotiating_fds: bool = False
+        self.uid: Optional[int] = uid
+
+    def _authentication_start(self, negotiate_unix_fd: bool = False) -> str:
+        self.negotiate_unix_fd = negotiate_unix_fd
+        uid = self.uid
+        if uid == UID_NOT_SPECIFIED:
+            return "AUTH EXTERNAL"
+        if uid is None:
+            uid = os.getuid()
+        hex_uid = str(uid).encode().hex()
+        return f"AUTH EXTERNAL {hex_uid}"
+
+    def _receive_line(self, line: str) -> str:
+        response, args = _AuthResponse.parse(line)
+
+        if response is _AuthResponse.OK:
+            if self.negotiate_unix_fd:
+                self.negotiating_fds = True
+                return "NEGOTIATE_UNIX_FD"
+            return "BEGIN"
+
+        if response is _AuthResponse.AGREE_UNIX_FD:
+            return "BEGIN"
+
+        if response is _AuthResponse.DATA and self.uid == UID_NOT_SPECIFIED:
+            return "DATA"
+
+        raise AuthError(f"authentication failed: {response.value}: {args}")
+
+
+class AuthAnonymous(Authenticator):
+    """An authenticator class for the anonymous auth protocol for use with the
+    :class:`MessageBus <dbus_fast.message_bus.BaseMessageBus>`.
+
+    :sealso: https://dbus.freedesktop.org/doc/dbus-specification.html#auth-protocol
+    """
+
+    def _authentication_start(self, negotiate_unix_fd: bool = False) -> str:
+        if negotiate_unix_fd:
+            raise AuthError(
+                "anonymous authentication does not support negotiating unix fds right now"
+            )
+
+        return "AUTH ANONYMOUS"
+
+    def _receive_line(self, line: str) -> str:
+        response, args = _AuthResponse.parse(line)
+
+        if response != _AuthResponse.OK:
+            raise AuthError(f"authentication failed: {response.value}: {args}")
+
+        return "BEGIN"
+
+
+# The following line provides backwards compatibility, remove at some point? --jrd
+AuthAnnonymous = AuthAnonymous

dbus_fast/constants.py

@@ -0,0 +1,152 @@
+from enum import Enum, IntFlag
+from functools import cached_property
+
+
+class BusType(Enum):
+    """An enum that indicates a type of bus. On most systems, there are
+    normally two different kinds of buses running.
+    """
+
+    SESSION = 1  #: A bus for the current graphical user session.
+    SYSTEM = 2  #: A persistent bus for the whole machine.
+
+
+class MessageType(Enum):
+    """An enum that indicates a type of message."""
+
+    METHOD_CALL = 1  #: An outgoing method call.
+    METHOD_RETURN = 2  #: A return to a previously sent method call
+    ERROR = 3  #: A return to a method call that has failed
+    SIGNAL = 4  #: A broadcast signal to subscribed connections
+
+    @cached_property
+    def value(self) -> int:
+        """Return the value."""
+        return self._value_
+
+
+MESSAGE_TYPE_MAP = {field.value: field for field in MessageType}
+
+
+class MessageFlag(IntFlag):
+    """Flags that affect the behavior of sent and received messages"""
+
+    NONE = 0
+    NO_REPLY_EXPECTED = 1  #: The method call does not expect a method return.
+    NO_AUTOSTART = 2
+    ALLOW_INTERACTIVE_AUTHORIZATION = 4
+
+    @cached_property
+    def value(self) -> int:
+        """Return the value."""
+        return self._value_
+
+
+# This is written out because of https://github.com/python/cpython/issues/98976
+MESSAGE_FLAG_MAP = {
+    0: MessageFlag.NONE,
+    1: MessageFlag.NO_REPLY_EXPECTED,
+    2: MessageFlag.NO_AUTOSTART,
+    4: MessageFlag.ALLOW_INTERACTIVE_AUTHORIZATION,
+}
+
+
+class NameFlag(IntFlag):
+    """A flag that affects the behavior of a name request."""
+
+    NONE = 0
+    ALLOW_REPLACEMENT = 1  #: If another client requests this name, let them have it.
+    REPLACE_EXISTING = 2  #: If another client owns this name, try to take it.
+    DO_NOT_QUEUE = 4  #: Name requests normally queue and wait for the owner to release the name. Do not enter this queue.
+
+
+class RequestNameReply(Enum):
+    """An enum that describes the result of a name request."""
+
+    PRIMARY_OWNER = 1  #: The bus owns the name.
+    IN_QUEUE = 2  #: The bus is in a queue and may receive the name after it is relased by the primary owner.
+    EXISTS = 3  #: The name has an owner and NameFlag.DO_NOT_QUEUE was given.
+    ALREADY_OWNER = 4  #: The bus already owns the name.
+
+
+class ReleaseNameReply(Enum):
+    """An enum that describes the result of a name release request"""
+
+    RELEASED = 1
+    NON_EXISTENT = 2
+    NOT_OWNER = 3
+
+
+class PropertyAccess(Enum):
+    """An enum that describes whether a DBus property can be gotten or set with
+    the ``org.freedesktop.DBus.Properties`` interface.
+    """
+
+    READ = "read"  #: The property is readonly.
+    WRITE = "write"  #: The property is writeonly.
+    READWRITE = "readwrite"  #: The property can be read or written to.
+
+    def readable(self) -> bool:
+        """Get whether the property can be read."""
+        return self == PropertyAccess.READ or self == PropertyAccess.READWRITE
+
+    def writable(self) -> bool:
+        """Get whether the property can be written to."""
+        return self == PropertyAccess.WRITE or self == PropertyAccess.READWRITE
+
+
+class ArgDirection(Enum):
+    """For an introspected argument, indicates whether it is an input parameter or a return value."""
+
+    IN = "in"
+    OUT = "out"
+
+
+class ErrorType(str, Enum):
+    """An enum for the type of an error for a message reply.
+
+    :seealso: http://man7.org/linux/man-pages/man3/sd-bus-errors.3.html
+    """
+
+    SERVICE_ERROR = "com.dubstepdish.dbus.next.ServiceError"  #: A custom error to indicate an exported service threw an exception.
+    INTERNAL_ERROR = "com.dubstepdish.dbus.next.InternalError"  #: A custom error to indicate something went wrong with the library.
+    CLIENT_ERROR = "com.dubstepdish.dbus.next.ClientError"  #: A custom error to indicate something went wrong with the client.
+
+    FAILED = "org.freedesktop.DBus.Error.Failed"
+    NO_MEMORY = "org.freedesktop.DBus.Error.NoMemory"
+    SERVICE_UNKNOWN = "org.freedesktop.DBus.Error.ServiceUnknown"
+    NAME_HAS_NO_OWNER = "org.freedesktop.DBus.Error.NameHasNoOwner"
+    NO_REPLY = "org.freedesktop.DBus.Error.NoReply"
+    IO_ERROR = "org.freedesktop.DBus.Error.IOError"
+    BAD_ADDRESS = "org.freedesktop.DBus.Error.BadAddress"
+    NOT_SUPPORTED = "org.freedesktop.DBus.Error.NotSupported"
+    LIMITS_EXCEEDED = "org.freedesktop.DBus.Error.LimitsExceeded"
+    ACCESS_DENIED = "org.freedesktop.DBus.Error.AccessDenied"
+    AUTH_FAILED = "org.freedesktop.DBus.Error.AuthFailed"
+    NO_SERVER = "org.freedesktop.DBus.Error.NoServer"
+    TIMEOUT = "org.freedesktop.DBus.Error.Timeout"
+    NO_NETWORK = "org.freedesktop.DBus.Error.NoNetwork"
+    ADDRESS_IN_USE = "org.freedesktop.DBus.Error.AddressInUse"
+    DISCONNECTED = "org.freedesktop.DBus.Error.Disconnected"
+    INVALID_ARGS = "org.freedesktop.DBus.Error.InvalidArgs"
+    FILE_NOT_FOUND = "org.freedesktop.DBus.Error.FileNotFound"
+    FILE_EXISTS = "org.freedesktop.DBus.Error.FileExists"
+    UNKNOWN_METHOD = "org.freedesktop.DBus.Error.UnknownMethod"
+    UNKNOWN_OBJECT = "org.freedesktop.DBus.Error.UnknownObject"
+    UNKNOWN_INTERFACE = "org.freedesktop.DBus.Error.UnknownInterface"
+    UNKNOWN_PROPERTY = "org.freedesktop.DBus.Error.UnknownProperty"
+    PROPERTY_READ_ONLY = "org.freedesktop.DBus.Error.PropertyReadOnly"
+    UNIX_PROCESS_ID_UNKNOWN = "org.freedesktop.DBus.Error.UnixProcessIdUnknown"
+    INVALID_SIGNATURE = "org.freedesktop.DBus.Error.InvalidSignature"
+    INCONSISTENT_MESSAGE = "org.freedesktop.DBus.Error.InconsistentMessage"
+    TIMED_OUT = "org.freedesktop.DBus.Error.TimedOut"
+    MATCH_RULE_NOT_FOUND = "org.freedesktop.DBus.Error.MatchRuleNotFound"
+    MATCH_RULE_INVALID = "org.freedesktop.DBus.Error.MatchRuleInvalid"
+    INTERACTIVE_AUTHORIZATION_REQUIRED = (
+        "org.freedesktop.DBus.Error.InteractiveAuthorizationRequired"
+    )
+    INVALID_FILE_CONTENT = "org.freedesktop.DBus.Error.InvalidFileContent"
+    SELINUX_SECURITY_CONTEXT_UNKNOWN = (
+        "org.freedesktop.DBus.Error.SELinuxSecurityContextUnknown"
+    )
+    OBJECT_PATH_IN_USE = "org.freedesktop.DBus.Error.ObjectPathInUse"

dbus_fast/errors.py

@@ -0,0 +1,84 @@
+from typing import Optional, Union
+
+
+class SignatureBodyMismatchError(ValueError):
+    pass
+
+
+class InvalidSignatureError(ValueError):
+    pass
+
+
+class InvalidAddressError(ValueError):
+    pass
+
+
+class AuthError(Exception):
+    pass
+
+
+class InvalidMessageError(ValueError):
+    pass
+
+
+class InvalidIntrospectionError(ValueError):
+    pass
+
+
+class InterfaceNotFoundError(Exception):
+    pass
+
+
+class SignalDisabledError(Exception):
+    pass
+
+
+class InvalidBusNameError(TypeError):
+    def __init__(self, name: str) -> None:
+        super().__init__(f"invalid bus name: {name}")
+
+
+class InvalidObjectPathError(TypeError):
+    def __init__(self, path: str) -> None:
+        super().__init__(f"invalid object path: {path}")
+
+
+class InvalidInterfaceNameError(TypeError):
+    def __init__(self, name: str) -> None:
+        super().__init__(f"invalid interface name: {name}")
+
+
+class InvalidMemberNameError(TypeError):
+    def __init__(self, member: str) -> None:
+        super().__init__(f"invalid member name: {member}")
+
+
+from .constants import ErrorType, MessageType  # noqa: E402
+from .message import Message  # noqa: E402
+from .validators import assert_interface_name_valid  # noqa: E402
+
+
+class DBusError(Exception):
+    def __init__(
+        self, type_: Union[ErrorType, str], text: str, reply: Optional[Message] = None
+    ) -> None:
+        super().__init__(text)
+
+        if type(type_) is ErrorType:
+            type_ = type_.value
+
+        assert_interface_name_valid(type_)  # type: ignore[arg-type]
+        if reply is not None and type(reply) is not Message:
+            raise TypeError("reply must be of type Message")
+
+        self.type = type_
+        self.text = text
+        self.reply = reply
+
+    @staticmethod
+    def _from_message(msg: Message) -> "DBusError":
+        assert msg.message_type == MessageType.ERROR
+        return DBusError(msg.error_name or "unknown", msg.body[0], reply=msg)
+
+    def _as_message(self, msg: Message) -> Message:
+        return Message.new_error(msg, self.type, self.text)

dbus_fast/glib/__init__.py

@@ -0,0 +1,3 @@
+from .message_bus import MessageBus as MessageBus
+from .proxy_object import ProxyInterface as ProxyInterface
+from .proxy_object import ProxyObject as ProxyObject