Merge pull request #1194 from PokestarFan/add-types-subreddits

(#1164) Add types to subreddits.py

praw/models/subreddits.py

@@ -1,4 +1,6 @@
 """Provide the Subreddits class."""
+from typing import Dict, Generator, List, Optional, Union
+
 from . import Subreddit
 from .base import PRAWBase
 from .listing.generator import ListingGenerator
@@ -13,7 +15,9 @@ class Subreddits(PRAWBase):
     def _to_list(subreddit_list):
         return ",".join([str(x) for x in subreddit_list])
 
-    def default(self, **generator_kwargs):
+    def default(
+        self, **generator_kwargs: Union[str, int, Dict[str, str]]
+    ) -> Generator[Subreddit, None, None]:
         """Return a :class:`.ListingGenerator` for default subreddits.
 
         Additional keyword arguments are passed in the initialization of
@@ -23,7 +27,9 @@ def default(self, **generator_kwargs):
             self._reddit, API_PATH["subreddits_default"], **generator_kwargs
         )
 
-    def gold(self, **generator_kwargs):
+    def gold(
+        self, **generator_kwargs: Union[str, int, Dict[str, str]]
+    ) -> Generator[Subreddit, None, None]:
         """Return a :class:`.ListingGenerator` for gold subreddits.
 
         Additional keyword arguments are passed in the initialization of
@@ -33,7 +39,9 @@ def gold(self, **generator_kwargs):
             self._reddit, API_PATH["subreddits_gold"], **generator_kwargs
         )
 
-    def new(self, **generator_kwargs):
+    def new(
+        self, **generator_kwargs: Union[str, int, Dict[str, str]]
+    ) -> Generator[Subreddit, None, None]:
         """Return a :class:`.ListingGenerator` for new subreddits.
 
         Additional keyword arguments are passed in the initialization of
@@ -43,7 +51,9 @@ def new(self, **generator_kwargs):
             self._reddit, API_PATH["subreddits_new"], **generator_kwargs
         )
 
-    def popular(self, **generator_kwargs):
+    def popular(
+        self, **generator_kwargs: Union[str, int, Dict[str, str]]
+    ) -> Generator[Subreddit, None, None]:
         """Return a :class:`.ListingGenerator` for popular subreddits.
 
         Additional keyword arguments are passed in the initialization of
@@ -53,7 +63,11 @@ def popular(self, **generator_kwargs):
             self._reddit, API_PATH["subreddits_popular"], **generator_kwargs
         )
 
-    def recommended(self, subreddits, omit_subreddits=None):
+    def recommended(
+        self,
+        subreddits: List[Union[str, Subreddit]],
+        omit_subreddits: Optional[List[Union[str, Subreddit]]] = None,
+    ) -> List[Subreddit]:
         """Return subreddits recommended for the given list of subreddits.
 
         :param subreddits: A list of Subreddit instances and/or subreddit
@@ -79,7 +93,9 @@ def recommended(self, subreddits, omit_subreddits=None):
             for sub in self._reddit.get(url, params=params)
         ]
 
-    def search(self, query, **generator_kwargs):
+    def search(
+        self, query: str, **generator_kwargs: Union[str, int, Dict[str, str]]
+    ) -> Generator[Subreddit, None, None]:
         """Return a :class:`.ListingGenerator` of subreddits matching ``query``.
 
         Subreddits are searched by both their title and description. To search
@@ -95,7 +111,9 @@ def search(self, query, **generator_kwargs):
             self._reddit, API_PATH["subreddits_search"], **generator_kwargs
         )
 
-    def search_by_name(self, query, include_nsfw=True, exact=False):
+    def search_by_name(
+        self, query: str, include_nsfw: bool = True, exact: bool = False
+    ) -> List[Subreddit]:
         """Return list of Subreddits whose names begin with ``query``.
 
         :param query: Search for subreddits beginning with this string.
@@ -113,7 +131,7 @@ def search_by_name(self, query, include_nsfw=True, exact=False):
         )
         return [self._reddit.subreddit(x) for x in result["names"]]
 
-    def search_by_topic(self, query):
+    def search_by_topic(self, query: str) -> List[Subreddit]:
         """Return list of Subreddits whose topics match ``query``.
 
         :param query: Search for subreddits relevant to the search topic.
@@ -126,7 +144,9 @@ def search_by_topic(self, query):
             self._reddit.subreddit(x["name"]) for x in result if x.get("name")
         ]
 
-    def stream(self, **stream_options):
+    def stream(
+        self, **stream_options: Union[str, int, Dict[str, str]]
+    ) -> Generator[Subreddit, None, None]:
         """Yield new subreddits as they are created.
 
         Subreddits are yielded oldest first. Up to 100 historical subreddits