Merge pull request #207 from praw-dev/type_mixins

Add missing typing annotations and improve docs
praw-dev · Nov 28, 2022 · 4b023ff · 4b023ff
2 parents fe92c63 + f2a2be0
commit 4b023ff
Show file tree

Hide file tree

Showing 4 changed files with 40 additions and 10 deletions.
diff --git a/asyncpraw/models/listing/mixins/redditor.py b/asyncpraw/models/listing/mixins/redditor.py
@@ -1,5 +1,5 @@
 """Provide the RedditorListingMixin class."""
-from typing import TYPE_CHECKING, Any, AsyncIterator, Dict, Union
+from typing import TYPE_CHECKING, AsyncIterator, Dict, Union
 from urllib.parse import urljoin
 
 from ....util.cache import cachedproperty
@@ -64,9 +64,14 @@ def submissions(self) -> SubListing:
 
     def downvoted(
         self, **generator_kwargs: Union[str, int, Dict[str, str]]
-    ) -> AsyncIterator[Any]:
+    ) -> AsyncIterator[
+        Union["asyncpraw.models.Comment", "asyncpraw.models.Submission"]
+    ]:
         """Return a :class:`.ListingGenerator` for items the user has downvoted.
 
+        :returns: A :class:`.ListingGenerator` object which yields :class:`.Comment` or
+            :class:`.Submission` objects the user has downvoted.
+
         :raises: ``asyncprawcore.Forbidden`` if the user is not authorized to access the
             list.
 
@@ -94,9 +99,14 @@ def downvoted(
 
     def gildings(
         self, **generator_kwargs: Union[str, int, Dict[str, str]]
-    ) -> AsyncIterator[Any]:
+    ) -> AsyncIterator[
+        Union["asyncpraw.models.Comment", "asyncpraw.models.Submission"]
+    ]:
         """Return a :class:`.ListingGenerator` for items the user has gilded.
 
+        :returns: A :class:`.ListingGenerator` object which yields :class:`.Comment` or
+            :class:`.Submission` objects the user has gilded.
+
         :raises: ``asyncprawcore.Forbidden`` if the user is not authorized to access the
             list.
 
@@ -124,9 +134,14 @@ def gildings(
 
     def hidden(
         self, **generator_kwargs: Union[str, int, Dict[str, str]]
-    ) -> AsyncIterator[Any]:
+    ) -> AsyncIterator[
+        Union["asyncpraw.models.Comment", "asyncpraw.models.Submission"]
+    ]:
         """Return a :class:`.ListingGenerator` for items the user has hidden.
 
+        :returns: A :class:`.ListingGenerator` object which yields :class:`.Comment` or
+            :class:`.Submission` objects the user has hid.
+
         :raises: ``asyncprawcore.Forbidden`` if the user is not authorized to access the
             list.
 
@@ -154,9 +169,14 @@ def hidden(
 
     def saved(
         self, **generator_kwargs: Union[str, int, Dict[str, str]]
-    ) -> AsyncIterator[Any]:
+    ) -> AsyncIterator[
+        Union["asyncpraw.models.Comment", "asyncpraw.models.Submission"]
+    ]:
         """Return a :class:`.ListingGenerator` for items the user has saved.
 
+        :returns: A :class:`.ListingGenerator` object which yields :class:`.Comment` or
+            :class:`.Submission` objects the user has saved.
+
         :raises: ``asyncprawcore.Forbidden`` if the user is not authorized to access the
             list.
 
@@ -184,9 +204,14 @@ def saved(
 
     def upvoted(
         self, **generator_kwargs: Union[str, int, Dict[str, str]]
-    ) -> AsyncIterator[Any]:
+    ) -> AsyncIterator[
+        Union["asyncpraw.models.Comment", "asyncpraw.models.Submission"]
+    ]:
         """Return a :class:`.ListingGenerator` for items the user has upvoted.
 
+        :returns: A :class:`.ListingGenerator` object which yields :class:`.Comment` or
+            :class:`.Submission` objects the user has upvoted.
+
         :raises: ``asyncprawcore.Forbidden`` if the user is not authorized to access the
             list.
 

diff --git a/asyncpraw/models/reddit/live.py b/asyncpraw/models/reddit/live.py
@@ -445,7 +445,7 @@ def discussions(
             constructor.
 
         :returns: A :class:`.ListingGenerator` object which yields :class:`.Submission`
-            object.
+            objects.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.
@@ -489,7 +489,7 @@ async def updates(
             constructor.
 
         :returns: A :class:`.ListingGenerator` object which yields :class:`.LiveUpdate`
-            object.
+            objects.
 
         Additional keyword arguments are passed in the initialization of
         :class:`.ListingGenerator`.

diff --git a/asyncpraw/models/reddit/mixins/gildable.py b/asyncpraw/models/reddit/mixins/gildable.py
@@ -107,7 +107,7 @@ async def award(
         }
         return await self._reddit.post(API_PATH["award_thing"], params=params)
 
-    async def gild(self):
+    async def gild(self) -> dict:
         """Alias for :meth:`.award` to maintain backwards compatibility."""
         warn(
             "`.gild` has been renamed to `.award`.",

diff --git a/asyncpraw/models/reddit/mixins/replyable.py b/asyncpraw/models/reddit/mixins/replyable.py
@@ -1,11 +1,16 @@
 """Provide the ReplyableMixin class."""
+from typing import TYPE_CHECKING, Optional
+
 from ....const import API_PATH
 
+if TYPE_CHECKING:  # pragma: no cover
+    import asyncpraw
+
 
 class ReplyableMixin:
     """Interface for :class:`.RedditBase` classes that can be replied to."""
 
-    async def reply(self, body: str):
+    async def reply(self, body: str) -> Optional["asyncpraw.models.Comment"]:
         """Reply to the object.
 
         :param body: The Markdown formatted content for a comment.