Add pydbus stubs

Author: Tatsh

stubs/pydbus/METADATA.toml

@@ -0,0 +1,3 @@
+version = "0.6.*"
+requires = ["pygobject-stubs"]
+upstream_repository = "https://github.com/LEW21/pydbus"

stubs/pydbus/pydbus/__init__.pyi

@@ -0,0 +1,5 @@
+from gi.repository.GLib import Variant
+
+from .bus import SessionBus, SystemBus, connect
+
+__all__ = ["SessionBus", "SystemBus", "Variant", "connect"]

stubs/pydbus/pydbus/auto_names.pyi

@@ -0,0 +1,2 @@
+def auto_bus_name(bus_name: str) -> str: ...
+def auto_object_path(bus_name: str, object_path: str | None = None) -> str: ...

stubs/pydbus/pydbus/bus.pyi

@@ -0,0 +1,190 @@
+import types
+from typing import Any, Literal, TypedDict, overload
+from typing_extensions import Self
+
+from gi.repository import Gio
+
+from .bus_names import OwnMixin, WatchMixin
+from .generic import bound_signal
+from .proxy import CompositeObject, ProxyMixin
+from .publication import PublicationMixin
+from .registration import RegistrationMixin
+from .request_name import RequestNameMixin
+from .subscription import SubscriptionMixin
+
+def bus_get(type: Gio.BusType) -> Bus: ...
+def connect(address: str) -> Bus: ...
+
+class DBusOrgFreedesktopDBus:
+    # Incomplete interface to org.freedesktop.DBus
+    Features: list[str]
+
+    def GetId(self) -> str: ...
+
+class DBusOrgFreedesktopPolicyKit1Authority:
+    # Incomplete interface to org.freedesktop.PolicyKit1.Authority
+    BackendFeatures: int  # flags
+    BackendName: str
+    BackendVersion: str
+
+class OrgBluezAdapter1Dict(TypedDict, total=False):
+    Address: str
+    AddressType: Literal["public", "random"]
+    Alias: str
+    Class: int
+    Connectable: bool
+    Discoverable: bool
+    DiscoverableTimeout: int
+    Discovering: bool
+    Manufacturer: int
+    Modalias: str
+    Name: str
+    Pairable: bool
+    PairableTimeout: int
+    Powered: bool
+    Roles: list[str]
+    UUIDs: list[str]
+    Version: int
+
+class OrgBluezDevice1Dict(TypedDict, total=False):
+    Adapter: str
+    Address: str
+    AddressType: Literal["public", "random"]
+    Alias: str
+    Appearance: int
+    Blocked: bool
+    Bonded: bool
+    Class: int
+    Connected: bool
+    Icon: str
+    LegacyPairing: bool
+    Modalias: str
+    Name: str
+    Paired: bool
+    ServicesResolved: bool
+    Trusted: bool
+    UUIDs: list[str]
+    WakeAllowed: bool
+
+class OrgBluezInput1Dict(TypedDict, total=False):
+    ReconnectMode: str
+
+class OrgBluezMedia1Dict(TypedDict, total=False):
+    SupportedUUIDs: list[str]
+
+class OrgBluezMediaControl1Dict(TypedDict, total=False):
+    Connected: bool
+
+class OrgBluezBattery1Dict(TypedDict, total=False):
+    Percentage: int
+    Source: str
+
+class OrgBluezGattService1Dict(TypedDict, total=False):
+    Device: str
+    Handle: int
+    Includes: list[str]
+    Primary: bool
+    UUID: str
+
+class OrgBluezGattCharacteristic1Dict(TypedDict, total=False):
+    Flags: list[str]
+    Handle: int
+    MTU: int
+    Service: str
+    UUID: str
+    Value: list[int]
+
+class OrgBluezGattDescriptor1Dict(TypedDict, total=False):
+    Characteristic: str
+    Handle: int
+    UUID: str
+    Value: list[int]
+
+class OrgBluezLEAdvertisingManager1Dict(TypedDict, total=False):
+    ActiveInstances: int
+    SupportedCapabilities: dict[str, int]  # e.g. MaxTxPower: 7
+    SupportedFeatures: list[str]
+    SupportedIncludes: list[str]
+    SupportedInstances: int
+    SupportedSecondaryChannels: list[str]
+
+# This is for keys under /org/bluez/hci0/*
+OrgBluezDict = TypedDict(
+    "OrgBluezDict",
+    {
+        "org.bluez.Adapter1": OrgBluezAdapter1Dict,
+        "org.bluez.Battery1": OrgBluezBattery1Dict,
+        "org.bluez.Device1": OrgBluezDevice1Dict,
+        "org.bluez.GattCharacteristic1": OrgBluezGattCharacteristic1Dict,
+        "org.bluez.GattDescriptor1": OrgBluezGattDescriptor1Dict,
+        "org.bluez.GattService1": OrgBluezGattService1Dict,
+        "org.bluez.Input1": OrgBluezInput1Dict,
+        "org.bluez.LEAdvertisingManager1": OrgBluezLEAdvertisingManager1Dict,
+        "org.bluez.Media1": OrgBluezMedia1Dict,
+        "org.bluez.MediaControl1": OrgBluezMediaControl1Dict,
+        # The following always appear as empty dictionaries on my system.
+        "org.bluez.AgentManager1": dict[str, Any],
+        "org.bluez.BatteryProviderManager1": dict[str, Any],
+        "org.bluez.NetworkServer1": dict[str, Any],
+        "org.bluez.ProfileManager1": dict[str, Any],
+        "org.freedesktop.DBus.Introspectable": dict[str, Any],
+        "org.freedesktop.DBus.Properties": dict[str, Any],
+    },
+    total=False,
+)
+
+class OrgFreedesktopDBusObjectManager:
+    @staticmethod
+    def GetManagedObjects() -> dict[str, OrgBluezDict]: ...
+
+class OrgBluez(CompositeObject):
+    def __getitem__(self, key: Literal["org.freedesktop.DBus.ObjectManager"]) -> OrgFreedesktopDBusObjectManager: ...  # type: ignore[override]
+
+class OrgFreedesktopNotifications(CompositeObject):
+    Inhibited: bool
+    ActivationToken: bound_signal
+    ActionInvoked: bound_signal
+    NotificationClosed: bound_signal
+
+    def CloseNotification(self, id: int) -> None: ...
+    def GetCapabilities(self) -> list[str]: ...  # We could use Literal[] here but KDE also returns its own not in the spec.
+    def GetServerInformation(self) -> tuple[str, str, str, str]: ...
+    def Inhibit(self, name: str, reason: str, hints: dict[str, bool | bytes | int | str]) -> int | None: ...
+    def Notify(
+        self,
+        app_name: str,
+        replaces_id: int,
+        app_icon: str,
+        summary: str,
+        body: str,
+        actions: list[str],
+        hints: dict[str, bool | bytes | int | str],  # See https://specifications.freedesktop.org/notification-spec/1.3/hints.html
+        expire_timeout: int,
+    ) -> int: ...
+    def UnInhibit(self, key: int) -> int | None: ...
+
+class Bus(ProxyMixin, RequestNameMixin, OwnMixin, WatchMixin, SubscriptionMixin, RegistrationMixin, PublicationMixin):
+    Type: type[Gio.BusType] = ...
+    autoclose: bool
+    con: Gio.DBusConnection
+
+    def __init__(self, gio_con: Gio.DBusConnection) -> None: ...
+    def __enter__(self) -> Self: ...
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: types.TracebackType | None
+    ) -> None: ...
+    @property
+    def dbus(self) -> DBusOrgFreedesktopDBus: ...
+    @property
+    def polkit_authority(self) -> DBusOrgFreedesktopPolicyKit1Authority: ...
+    @overload  # type: ignore[override]
+    def get(self, domain: Literal[".Notifications"]) -> OrgFreedesktopNotifications: ...
+    @overload  # type: ignore[override]
+    def get(self, domain: Literal["org.freedesktop.Notifications"]) -> OrgFreedesktopNotifications: ...
+    @overload
+    def get(self, domain: Literal["org.bluez"], path: Literal["/"]) -> OrgBluez: ...
+    @overload
+    def get(self, domain: str, path: str) -> Any: ...  # unpredictable return value.
+
+def SystemBus() -> Bus: ...
+def SessionBus() -> Bus: ...

stubs/pydbus/pydbus/bus_names.pyi

@@ -0,0 +1,53 @@
+from collections.abc import Callable
+
+from gi.repository import Gio
+
+from .exitable import Exitable
+
+class NameOwner(Exitable):
+    Flags: Gio.BusNameOwnerFlags
+
+    def __init__(
+        self,
+        con: Gio.DBusConnection,
+        name: str,
+        flags: Gio.BusNameOwnerFlags,
+        name_aquired_handler: Callable[[str], None],
+        name_lost_handler: Callable[[str], None],
+    ) -> None: ...
+    def unown(self) -> None: ...  # added by ExitableWithAliases('unown')
+
+class NameWatcher(Exitable):
+    Flags: Gio.BusNameWatcherFlags
+
+    def __init__(
+        self,
+        con: Gio.DBusConnection,
+        name: str,
+        flags: Gio.BusNameWatcherFlags,
+        name_appeared_handler: Callable[[str], None],
+        name_vanished_handler: Callable[[str], None],
+    ) -> None: ...
+    def unwatch(self) -> None: ...  # added by ExitableWithAliases('unwatch')
+
+class OwnMixin:
+    NameOwnerFlags: Gio.BusNameOwnerFlags
+
+    def own_name(
+        self,
+        name: str,
+        flags: Gio.BusNameOwnerFlags = ...,
+        name_aquired: Callable[[str], None] | None = ...,
+        name_lost: Callable[[str], None] | None = ...,
+    ) -> NameOwner: ...
+
+class WatchMixin:
+    NameWatcherFlags: Gio.BusNameWatcherFlags
+
+    def watch_name(
+        self,
+        name: str,
+        flags: Gio.BusNameWatcherFlags = ...,
+        name_appeared: Callable[[str], None] | None = ...,
+        name_vanished: Callable[[str], None] | None = ...,
+    ) -> NameWatcher: ...

stubs/pydbus/pydbus/exitable.pyi

@@ -0,0 +1,14 @@
+import types
+from collections.abc import Iterable
+from typing_extensions import Self
+
+class Exitable:
+    def __enter__(self) -> Self: ...
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None = None,
+        exc_value: BaseException | None = None,
+        traceback: types.TracebackType | None = None,
+    ) -> None: ...
+
+def ExitableWithAliases(*exit_methods: Iterable[str]) -> Exitable: ...

stubs/pydbus/pydbus/generic.pyi

@@ -0,0 +1,43 @@
+import types
+from _typeshed import Unused
+from collections.abc import Callable
+from typing import Generic, TypeVar, overload
+from typing_extensions import Self
+
+class subscription:
+    callback_list: list[Callable[..., object]]
+    callback: Callable[..., object]
+
+    def __init__(self, callback_list: list[Callable[..., object]], callback: Callable[..., object]) -> None: ...
+    def unsubscribe(self) -> None: ...
+    def disconnect(self) -> None: ...
+    def __enter__(self) -> Self: ...
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: types.TracebackType | None
+    ) -> None: ...
+
+_T = TypeVar("_T")
+
+class bound_signal(Generic[_T]):
+    __signal__: signal[_T]
+
+    def __init__(self, signal: signal[_T], instance: _T) -> None: ...
+    @property
+    def callbacks(self) -> list[Callable[..., object]]: ...
+    def connect(self, callback: Callable[..., object]) -> subscription: ...
+    def emit(self, *args: object) -> None: ...
+    def __call__(self, *args: object) -> None: ...
+
+class signal(Generic[_T]):
+    map: dict[object, Callable[..., object]]
+
+    def __init__(self) -> None: ...
+    def connect(self, object: str, callback: Callable[..., object]) -> subscription: ...
+    def emit(self, object: str, *args: object) -> None: ...
+    @overload
+    def __get__(self, instance: None, owner: Unused) -> Self: ...
+    @overload
+    def __get__(self, instance: _T, owner: Unused) -> bound_signal[_T]: ...
+    def __set__(self, instance: Unused, value: Unused) -> None: ...  # Always raises
+
+bound_method: Callable[..., None]  # type(signal().emit)

stubs/pydbus/pydbus/identifier.pyi

@@ -0,0 +1,2 @@
+def isident(s: str) -> bool: ...
+def filter_identifier(name: str) -> str: ...

stubs/pydbus/pydbus/method_call_context.pyi

@@ -0,0 +1,25 @@
+from typing import NamedTuple
+
+from gi.repository import Gio
+
+from .bus import Bus
+
+class AuthorizationResult(NamedTuple):
+    is_authorized: bool
+    is_challenge: bool
+    details: dict[str, str]
+
+class MethodCallContext:
+    def __init__(self, gdbus_method_invocation: Gio.DBusMethodInvocation) -> None: ...
+    @property
+    def bus(self) -> Bus: ...
+    @property
+    def sender(self) -> str: ...
+    @property
+    def object_path(self) -> str: ...
+    @property
+    def interface_name(self) -> str: ...
+    @property
+    def method_name(self) -> str: ...
+    def check_authorization(self, action_id: str, details: dict[str, str], interactive: bool = False) -> AuthorizationResult: ...
+    def is_authorized(self, action_id: str, details: dict[str, str], interactive: bool = False) -> bool: ...

stubs/pydbus/pydbus/proxy.pyi

@@ -0,0 +1,25 @@
+from typing import Generic, TypeVar
+from typing_extensions import Self
+from xml.etree.ElementTree import Element
+
+from .bus import Bus
+
+class ProxyMixin:
+    def get(self, bus_name: str, object_path: str | None = None, *, timeout: int | None = None) -> CompositeObject: ...
+
+_T = TypeVar("_T")
+
+class ProxyObject(Generic[_T]):
+    def __init__(self, bus: Bus, bus_name: str, path: str, object: Self | None = None) -> None: ...
+    def __getattr__(self, name: str) -> _T: ...
+    def __setattr__(self, name: str, value: _T) -> None: ...
+
+class CompositeObject(ProxyObject[_T]):  # Inside CompositeInterface
+    def __getitem__(self, iface: str) -> ProxyObject[_T]: ...
+
+class interface(ProxyObject[_T]):  # inside Interface
+    @staticmethod
+    def _Introspect() -> None: ...
+
+def Interface(iface: Element) -> interface[object]: ...
+def CompositeInterface(introspection: Element) -> CompositeObject[object]: ...

stubs/pydbus/pydbus/proxy_method.pyi

@@ -0,0 +1,19 @@
+from _typeshed import Unused
+from inspect import Signature
+from typing import Generic, TypeVar
+
+from .proxy import ProxyObject
+
+_CT = TypeVar("_CT")  # __call__ return type
+_GT = TypeVar("_GT")  # __get__ return type
+_PT = TypeVar("_PT")  # ProxyObject type
+put_signature_in_doc: bool = False
+
+class DBUSSignature(Signature): ...
+
+class ProxyMethod(Generic[_GT, _CT, _PT]):
+    __signature__: DBUSSignature
+
+    def __init__(self, iface_name: str, method: str) -> None: ...
+    def __call__(self, instance: ProxyObject[_PT], *args: object, timeout: int | None = None) -> _CT: ...
+    def __get__(self, instance: ProxyObject[_PT], owner: Unused) -> _GT: ...