Kombu typing improvements (#207)

I've been working with Kombu directly in the last weeks, and tried to improve the type stubs along the way.

Overall I think the result is decent.

The workflow was basically just to run stubgen/stubtest to get first to some basic stubs, then mypy/basedpyright/ruff/tests to catch issues, everything semi-automated with AI, then some manual review. I've added the external deps which means the type checkers can actually resolve base classes and give useful feedback on overrides.

This is mainly here for some feedback. Personally I would go with this approach and just aim for full type stubs coverage, and then work out the kinks. But I can also see that this is not ideal.

Author: oliverhaas

.gitignore

@@ -3,3 +3,5 @@ dist
 .idea
 node_modules
 .python-version
+__pycache__
+*.pyc

amqp-stubs/__init__.pyi

@@ -1,3 +1,155 @@
-from amqp.exceptions import ConnectionError
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any
 
-__all__ = ["ConnectionError"]
+from amqp.basic_message import Message as Message
+from amqp.channel import Channel as Channel
+from amqp.connection import Connection as Connection
+from amqp.exceptions import (
+    AccessRefused as AccessRefused,
+)
+from amqp.exceptions import (
+    AMQPError as AMQPError,
+)
+from amqp.exceptions import (
+    AMQPNotImplementedError as AMQPNotImplementedError,
+)
+from amqp.exceptions import (
+    ChannelError as ChannelError,
+)
+from amqp.exceptions import (
+    ChannelNotOpen as ChannelNotOpen,
+)
+from amqp.exceptions import (
+    ConnectionError as ConnectionError,
+)
+from amqp.exceptions import (
+    ConnectionForced as ConnectionForced,
+)
+from amqp.exceptions import (
+    ConsumerCancelled as ConsumerCancelled,
+)
+from amqp.exceptions import (
+    ContentTooLarge as ContentTooLarge,
+)
+from amqp.exceptions import (
+    FrameError as FrameError,
+)
+from amqp.exceptions import (
+    FrameSyntaxError as FrameSyntaxError,
+)
+from amqp.exceptions import (
+    InternalError as InternalError,
+)
+from amqp.exceptions import (
+    InvalidCommand as InvalidCommand,
+)
+from amqp.exceptions import (
+    InvalidPath as InvalidPath,
+)
+from amqp.exceptions import (
+    IrrecoverableChannelError as IrrecoverableChannelError,
+)
+from amqp.exceptions import (
+    IrrecoverableConnectionError as IrrecoverableConnectionError,
+)
+from amqp.exceptions import (
+    NoConsumers as NoConsumers,
+)
+from amqp.exceptions import (
+    NotAllowed as NotAllowed,
+)
+from amqp.exceptions import (
+    NotFound as NotFound,
+)
+from amqp.exceptions import (
+    PreconditionFailed as PreconditionFailed,
+)
+from amqp.exceptions import (
+    RecoverableChannelError as RecoverableChannelError,
+)
+from amqp.exceptions import (
+    RecoverableConnectionError as RecoverableConnectionError,
+)
+from amqp.exceptions import (
+    ResourceError as ResourceError,
+)
+from amqp.exceptions import (
+    ResourceLocked as ResourceLocked,
+)
+from amqp.exceptions import (
+    UnexpectedFrame as UnexpectedFrame,
+)
+from amqp.exceptions import (
+    error_for_code as error_for_code,
+)
+
+__all__ = (
+    "AMQPError",
+    "AMQPNotImplementedError",
+    "AccessRefused",
+    "Channel",
+    "ChannelError",
+    "ChannelNotOpen",
+    "Connection",
+    "ConnectionError",
+    "ConnectionForced",
+    "ConsumerCancelled",
+    "ContentTooLarge",
+    "FrameError",
+    "FrameSyntaxError",
+    "InternalError",
+    "InvalidCommand",
+    "InvalidPath",
+    "IrrecoverableChannelError",
+    "IrrecoverableConnectionError",
+    "Message",
+    "NoConsumers",
+    "NotAllowed",
+    "NotFound",
+    "PreconditionFailed",
+    "RecoverableChannelError",
+    "RecoverableConnectionError",
+    "ResourceError",
+    "ResourceLocked",
+    "UnexpectedFrame",
+    "error_for_code",
+    "promise",
+)
+
+class promise:
+    fun: Callable[..., Any] | None
+    args: Sequence[Any]
+    kwargs: Mapping[str, Any]
+    on_error: Callable[..., Any] | None
+    cancelled: bool
+    failed: bool
+    ready: bool
+    reason: BaseException | None
+    weak: bool
+    ignore_result: bool
+    value: Any
+
+    def __init__(
+        self,
+        fun: Callable[..., Any] | None = ...,
+        args: Sequence[Any] | None = ...,
+        kwargs: Mapping[str, Any] | None = ...,
+        callback: Callable[..., Any] | None = ...,
+        on_error: Callable[..., Any] | None = ...,
+        weak: bool = ...,
+        ignore_result: bool = ...,
+    ) -> None: ...
+    def __call__(self, *args: Any, **kwargs: Any) -> Any: ...
+    def then(
+        self, callback: Callable[..., Any], on_error: Callable[..., Any] | None = ...
+    ) -> promise: ...
+    def throw(
+        self,
+        exc: BaseException | None = ...,
+        tb: Any | None = ...,
+        propagate: bool = ...,
+    ) -> None: ...
+    def throw1(self, exc: BaseException | None = ...) -> None: ...
+    def cancel(self) -> None: ...
+    @property
+    def listeners(self) -> list[promise]: ...

amqp-stubs/abstract_channel.pyi

@@ -0,0 +1,49 @@
+from collections.abc import Callable
+from logging import Logger
+from typing import Any
+
+from amqp.exceptions import AMQPNotImplementedError as AMQPNotImplementedError
+from amqp.exceptions import RecoverableConnectionError as RecoverableConnectionError
+from typing_extensions import Self
+from vine import promise
+
+__all__ = ("AbstractChannel",)
+
+AMQP_LOGGER: Logger
+IGNORED_METHOD_DURING_CHANNEL_CLOSE: str
+
+class AbstractChannel:
+    auto_decode: bool
+    channel_id: int | None
+    connection: Any
+    is_closing: bool
+    method_queue: list[Any]
+
+    def __init__(self, connection: Any, channel_id: int | None) -> None: ...
+    def __enter__(self) -> Self: ...
+    def __exit__(self, *args: object) -> None: ...
+    def close(self) -> None: ...
+    def dispatch_method(
+        self, method_sig: tuple[int, int], payload: bytes, content: Any
+    ) -> None: ...
+    def send_method(
+        self,
+        sig: tuple[int, int],
+        format: str | None = ...,
+        args: tuple[Any, ...] | None = ...,
+        content: Any | None = ...,
+        wait: Any | None = ...,
+        callback: Callable[..., Any] | None = ...,
+        returns_tuple: bool = ...,
+    ) -> Any: ...
+    def wait(
+        self,
+        method: Any,
+        callback: Callable[..., Any] | None = ...,
+        timeout: float | None = ...,
+        returns_tuple: bool = ...,
+    ) -> Any: ...
+
+def dumps(format: str, values: tuple[Any, ...]) -> bytes: ...
+def loads(format: str, buf: bytes, offset: int) -> tuple[Any, ...]: ...
+def ensure_promise(p: promise | Callable[..., Any] | None) -> promise: ...

amqp-stubs/basic_message.pyi

@@ -0,0 +1,44 @@
+from typing import Any
+
+__all__ = ("Message",)
+
+class Message:
+    CLASS_ID: int
+    PROPERTIES: list[tuple[str, str]]
+
+    body: bytes | str
+    body_size: int
+    body_received: int
+    channel: Any
+    delivery_info: dict[str, Any]
+    properties: dict[str, Any]
+    ready: bool
+    frame_method: tuple[int, int] | None
+    frame_args: bytes | None
+
+    content_type: str | None
+    content_encoding: str | None
+    application_headers: dict[str, Any] | None
+    delivery_mode: int | None
+    priority: int | None
+    correlation_id: str | None
+    reply_to: str | None
+    expiration: str | None
+    message_id: str | None
+    timestamp: int | None
+    type: str | None
+    user_id: str | None
+    app_id: str | None
+    cluster_id: str | None
+
+    def __init__(
+        self,
+        body: bytes | str = ...,
+        children: Any | None = ...,
+        channel: Any | None = ...,
+        **properties: Any,
+    ) -> None: ...
+    @property
+    def headers(self) -> dict[str, Any] | None: ...
+    @property
+    def delivery_tag(self) -> int | None: ...