Improve new APIs (#582)

Co-authored-by: always-on-duty[bot] <120557446+always-on-duty[bot]@users.noreply.github.com>

CHANGELOG.md

@@ -5,6 +5,19 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
+### Added
+- [BaseContext.alluka][yuyo.interactions.BaseContext.alluka] property for getting the
+  context's alluka client.
+
+### Changed
+- [pagination.ResponseKwargs][yuyo.pagination.ResponseKwargs] is now publicly exported to
+  allow 3rd party implementations of
+  [AbstractPage.ctx_to_kwargs][yuyo.pagination.AbstractPage.ctx_to_kwargs]
+  and [AbstractPage.to_kwargs][yuyo.pagination.AbstractPage.to_kwargs] to have properly
+  typed return types.
+- [pagination.ResponseKwargs][yuyo.pagination.ResponseKwargs]'s fields are now all marked
+  as not required.
+
 ## [1.22.0] - 2024-07-11
 ### Added
 - Support for component pagination based on global ("static") bot data.

yuyo/components.py

@@ -162,6 +162,11 @@ def __init__(
         self._client = client
         self._response_future = response_future
 
+    @property
+    def alluka(self) -> alluka_.abc.Client:
+        """The Alluka client being used for callback dependency injection."""
+        return self._client.alluka
+
     @property
     def selected_channels(self) -> collections.Mapping[hikari.Snowflake, hikari.InteractionChannel]:
         """Sequence of the users passed for a channel select menu."""

yuyo/interactions.py

@@ -47,6 +47,7 @@
 from . import _internal
 
 if typing.TYPE_CHECKING:
+    import alluka as alluka_
     from typing_extensions import Self
 
 
@@ -110,6 +111,12 @@ def __init__(
         self._response_future = response_future
         self._response_lock = asyncio.Lock()
 
+    @property
+    @abc.abstractmethod
+    def alluka(self) -> alluka_.abc.Client:
+        """The Alluka client being used for callback dependency injection."""
+        raise NotImplementedError
+
     @property
     def author(self) -> hikari.User:
         """Author of this interaction."""

yuyo/modals.py

@@ -129,6 +129,11 @@ def __init__(
         self._component_ids = component_ids
         self._response_future = response_future
 
+    @property
+    def alluka(self) -> alluka_.abc.Client:
+        """The Alluka client being used for callback dependency injection."""
+        return self._client.alluka
+
     @property
     def client(self) -> Client:
         """The modal this context is bound to."""

yuyo/pagination.py

@@ -36,6 +36,7 @@
     "LocalisedPage",
     "LocalizedPage",
     "Page",
+    "ResponseKwargs",
     "aenumerate",
     "async_paginate_string",
     "paginate_string",
@@ -48,6 +49,7 @@
 from collections import abc as collections
 
 import hikari
+import typing_extensions
 
 from . import _internal
 from ._internal import localise
@@ -57,10 +59,23 @@
 
     _T = typing.TypeVar("_T")
 
-    class _ResponseKwargs(typing.TypedDict):
-        content: hikari.UndefinedOr[str]
-        attachments: hikari.UndefinedOr[collections.Sequence[hikari.Resourceish]]
-        embeds: hikari.UndefinedOr[collections.Sequence[hikari.Embed]]
+
+class ResponseKwargs(typing_extensions.TypedDict, total=False):
+    """Typed dict of a message response's basic kwargs.
+
+    This is returned by
+    [AbstractPage.to_kwargs][yuyo.pagination.AbstractPage.to_kwargs] and
+    [AbstractPage.ctx_to_kwargs][yuyo.pagination.AbstractPage.ctx_to_kwargs].
+    """
+
+    content: hikari.UndefinedOr[str]
+    """String message content to send."""
+
+    attachments: hikari.UndefinedOr[collections.Sequence[hikari.Resourceish]]
+    """A sequence of attachments to send."""
+
+    embeds: hikari.UndefinedOr[collections.Sequence[hikari.Embed]]
+    """A sequence of embeds to send."""
 
 
 EntryT = typing.Union[tuple[hikari.UndefinedOr[str], hikari.UndefinedOr[hikari.Embed]], "AbstractPage"]
@@ -328,12 +343,12 @@ class AbstractPage(abc.ABC):
     __slots__ = ()
 
     @abc.abstractmethod
-    def to_kwargs(self) -> _ResponseKwargs:
+    def to_kwargs(self) -> ResponseKwargs:
         """Form create message `**kwargs` for this page.
 
         Returns
         -------
-        dict[str, Any]
+        ResponseKwargs
             The create message kwargs for this page.
         """
 
@@ -344,12 +359,12 @@ def ctx_to_kwargs(
             interactions.BaseContext[hikari.ComponentInteraction], interactions.BaseContext[hikari.ModalInteraction]
         ],
         /,
-    ) -> _ResponseKwargs:
+    ) -> ResponseKwargs:
         """Form create message `**kwargs` for this page based on a component or modal context.
 
         Returns
         -------
-        dict[str, Any]
+        ResponseKwargs
             The create message kwargs for this page.
         """
 
@@ -477,12 +492,12 @@ def from_entry(cls, entry: EntryT, /) -> AbstractPage:
 
         return entry
 
-    def to_kwargs(self) -> _ResponseKwargs:
+    def to_kwargs(self) -> ResponseKwargs:
         """Form create message `**kwargs` for this page.
 
         Returns
         -------
-        dict[str, Any]
+        ResponseKwargs
             The create message kwargs for this page.
         """
         return {"attachments": self._attachments, "content": self._content, "embeds": self._embeds}
@@ -493,12 +508,12 @@ def ctx_to_kwargs(
             interactions.BaseContext[hikari.ComponentInteraction], interactions.BaseContext[hikari.ModalInteraction]
         ],
         /,
-    ) -> _ResponseKwargs:
+    ) -> ResponseKwargs:
         """Form create message `**kwargs` for this page based on a component or modal context.
 
         Returns
         -------
-        dict[str, Any]
+        ResponseKwargs
             The create message kwargs for this page.
         """
         return self.to_kwargs()
@@ -512,7 +527,7 @@ class LocalisedPage(AbstractPage):
     def __init__(self, pages: collections.Mapping[typing.Union[str, hikari.Locale], AbstractPage], /) -> None:
         self._pages = localise.MaybeLocalised[AbstractPage].parse("page", pages)
 
-    def to_kwargs(self) -> _ResponseKwargs:
+    def to_kwargs(self) -> ResponseKwargs:
         return self._pages.value.to_kwargs()
 
     def ctx_to_kwargs(
@@ -521,7 +536,7 @@ def ctx_to_kwargs(
             interactions.BaseContext[hikari.ComponentInteraction], interactions.BaseContext[hikari.ModalInteraction]
         ],
         /,
-    ) -> _ResponseKwargs:
+    ) -> ResponseKwargs:
         return self._pages.localise(ctx).to_kwargs()