Add missing typing annotations and improve docs

praw-dev · May 21, 2022 · 3d9e414 · 3d9e414
1 parent 809d878
commit 3d9e414
Show file tree

Hide file tree

Showing 4 changed files with 29 additions and 9 deletions.
diff --git a/praw/models/listing/mixins/redditor.py b/praw/models/listing/mixins/redditor.py
@@ -62,9 +62,12 @@ def submissions(self) -> SubListing:
 
     def downvoted(
         self, **generator_kwargs: Union[str, int, Dict[str, str]]
-    ) -> Iterator[Any]:
+    ) -> Iterator[Union["praw.models.Comment", "praw.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: ``prawcore.Forbidden`` if the user is not authorized to access the
             list.
 
@@ -91,9 +94,12 @@ def downvoted(
 
     def gildings(
         self, **generator_kwargs: Union[str, int, Dict[str, str]]
-    ) -> Iterator[Any]:
+    ) -> Iterator[Union["praw.models.Comment", "praw.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: ``prawcore.Forbidden`` if the user is not authorized to access the
             list.
 
@@ -120,9 +126,12 @@ def gildings(
 
     def hidden(
         self, **generator_kwargs: Union[str, int, Dict[str, str]]
-    ) -> Iterator[Any]:
+    ) -> Iterator[Union["praw.models.Comment", "praw.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: ``prawcore.Forbidden`` if the user is not authorized to access the
             list.
 
@@ -149,9 +158,12 @@ def hidden(
 
     def saved(
         self, **generator_kwargs: Union[str, int, Dict[str, str]]
-    ) -> Iterator[Any]:
+    ) -> Iterator[Union["praw.models.Comment", "praw.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: ``prawcore.Forbidden`` if the user is not authorized to access the
             list.
 
@@ -178,9 +190,12 @@ def saved(
 
     def upvoted(
         self, **generator_kwargs: Union[str, int, Dict[str, str]]
-    ) -> Iterator[Any]:
+    ) -> Iterator[Union["praw.models.Comment", "praw.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: ``prawcore.Forbidden`` if the user is not authorized to access the
             list.
 

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

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