Merge remote-tracking branch 'praw-dev/master' into Moderation-Streams

praw/models/auth.py

@@ -1,4 +1,6 @@
 """Provide the Auth class."""
+from typing import Dict, List, NoReturn, Optional, Set, Union
+
 from prawcore import (
     Authorizer,
     ImplicitAuthorizer,
@@ -14,7 +16,7 @@ class Auth(PRAWBase):
     """Auth provides an interface to Reddit's authorization."""
 
     @property
-    def limits(self):
+    def limits(self) -> Dict[str, Optional[Union[str, int]]]:
         """Return a dictionary containing the rate limit info.
 
         The keys are:
@@ -42,7 +44,7 @@ def limits(self):
             "used": data.used,
         }
 
-    def authorize(self, code):
+    def authorize(self, code: str) -> Optional[str]:
         """Complete the web authorization flow and return the refresh token.
 
         :param code: The code obtained through the request to the redirect uri.
@@ -58,7 +60,9 @@ def authorize(self, code):
         self._reddit._core = self._reddit._authorized_core = authorized_session
         return authorizer.refresh_token
 
-    def implicit(self, access_token, expires_in, scope):
+    def implicit(
+        self, access_token: str, expires_in: int, scope: str
+    ) -> NoReturn:
         """Set the active authorization to be an implicit authorization.
 
         :param access_token: The access_token obtained from Reddit's callback.
@@ -84,7 +88,7 @@ def implicit(self, access_token, expires_in, scope):
         )
         self._reddit._core = self._reddit._authorized_core = implicit_session
 
-    def scopes(self):
+    def scopes(self) -> Set[str]:
         """Return a set of scopes included in the current authorization.
 
         For read-only authorizations this should return ``{'*'}``.
@@ -95,7 +99,13 @@ def scopes(self):
             authorizer.refresh()
         return authorizer.scopes
 
-    def url(self, scopes, state, duration="permanent", implicit=False):
+    def url(
+        self,
+        scopes: List[str],
+        state: str,
+        duration: str = "permanent",
+        implicit: bool = False,
+    ) -> str:
         """Return the URL used out-of-band to grant access to your application.
 
         :param scopes: A list of OAuth scopes to request authorization for.

praw/models/base.py

@@ -1,5 +1,8 @@
 """Provide the PRAWBase superclass."""
 from copy import deepcopy
+from typing import Any, Dict, TypeVar
+
+Reddit = TypeVar("Reddit")
 
 
 class PRAWBase:
@@ -20,7 +23,7 @@ def _safely_add_arguments(argument_dict, key, **new_arguments):
         argument_dict[key] = value
 
     @classmethod
-    def parse(cls, data, reddit):
+    def parse(cls, data: Dict[str, Any], reddit: Reddit) -> Any:
         """Return an instance of ``cls`` from ``data``.
 
         :param data: The structured data.
@@ -29,7 +32,7 @@ def parse(cls, data, reddit):
         """
         return cls(reddit, _data=data)
 
-    def __init__(self, reddit, _data):
+    def __init__(self, reddit: Reddit, _data: Dict[str, Any]):
         """Initialize a PRAWModel instance.
 
         :param reddit: An instance of :class:`.Reddit`.

praw/models/comment_forest.py

@@ -1,8 +1,12 @@
 """Provide CommentForest for Submission comments."""
 from heapq import heappop, heappush
+from typing import List, Optional, TypeVar, Union
 
 from .reddit.more import MoreComments
 
+Comment = TypeVar("Comment")
+Submission = TypeVar("Submission")
+
 
 class CommentForest:
     """A forest of comments starts with multiple top-level comments.
@@ -29,7 +33,7 @@ def _gather_more_comments(tree, parent_tree=None):
                     queue.append((comment, item))
         return more_comments
 
-    def __getitem__(self, index):
+    def __getitem__(self, index: int):
         """Return the comment at position ``index`` in the list.
 
         This method is to be used like an array access, such as:
@@ -49,7 +53,9 @@ def __getitem__(self, index):
         """
         return self._comments[index]
 
-    def __init__(self, submission, comments=None):
+    def __init__(
+        self, submission: Submission, comments: Optional[List[Comment]] = None
+    ):
         """Initialize a CommentForest instance.
 
         :param submission: An instance of :class:`~.Subreddit` that is the
@@ -61,7 +67,7 @@ def __init__(self, submission, comments=None):
         self._comments = comments
         self._submission = submission
 
-    def __len__(self):
+    def __len__(self) -> int:
         """Return the number of top-level comments in the forest."""
         return len(self._comments)
 
@@ -80,7 +86,7 @@ def _update(self, comments):
         for comment in comments:
             comment.submission = self._submission
 
-    def list(self):
+    def list(self) -> Union[Comment, MoreComments]:
         """Return a flattened list of all Comments.
 
         This list may contain :class:`.MoreComments` instances if
@@ -96,7 +102,9 @@ def list(self):
                 queue.extend(comment.replies)
         return comments
 
-    def replace_more(self, limit=32, threshold=0):
+    def replace_more(
+        self, limit: int = 32, threshold: int = 0
+    ) -> List[MoreComments]:
         """Update the comment forest by resolving instances of MoreComments.
 
         :param limit: The maximum number of :class:`.MoreComments` instances to

praw/models/front.py

@@ -1,19 +1,25 @@
 """Provide the Front class."""
+from typing import Generator, TypeVar, Union
 from urllib.parse import urljoin
 
 from .listing.generator import ListingGenerator
 from .listing.mixins import SubredditListingMixin
+from .reddit.submission import Submission
+
+Reddit = TypeVar("Reddit")
 
 
 class Front(SubredditListingMixin):
     """Front is a Listing class that represents the front page."""
 
-    def __init__(self, reddit):
+    def __init__(self, reddit: Reddit):
         """Initialize a Front instance."""
         super().__init__(reddit, _data=None)
         self._path = "/"
 
-    def best(self, **generator_kwargs):
+    def best(
+        self, **generator_kwargs: Union[str, int]
+    ) -> Generator[Submission, None, None]:
         """Return a :class:`.ListingGenerator` for best items.
 
         Additional keyword arguments are passed in the initialization of

praw/models/helpers.py

@@ -1,16 +1,20 @@
 """Provide the helper classes."""
 from json import dumps
+from typing import Generator, List, Optional, Union
 
 from ..const import API_PATH
 from .base import PRAWBase
 from .reddit.live import LiveThread
 from .reddit.multi import Multireddit, Subreddit
+from .reddit.redditor import Redditor
 
 
 class LiveHelper(PRAWBase):
     """Provide a set of functions to interact with LiveThreads."""
 
-    def __call__(self, id):  # pylint: disable=invalid-name,redefined-builtin
+    def __call__(
+        self, id: str
+    ) -> LiveThread:  # pylint: disable=invalid-name,redefined-builtin
         """Return a new lazy instance of :class:`~.LiveThread`.
 
         This method is intended to be used as:
@@ -23,7 +27,7 @@ def __call__(self, id):  # pylint: disable=invalid-name,redefined-builtin
         """
         return LiveThread(self._reddit, id=id)
 
-    def info(self, ids):
+    def info(self, ids: List[str]) -> Generator[LiveThread, None, None]:
         """Fetch information about each live thread in ``ids``.
 
         :param ids: A list of IDs for a live thread.
@@ -63,7 +67,13 @@ def generator():
 
         return generator()
 
-    def create(self, title, description=None, nsfw=False, resources=None):
+    def create(
+        self,
+        title: str,
+        description: Optional[str] = None,
+        nsfw: bool = False,
+        resources: str = None,
+    ) -> LiveThread:
         """Create a new LiveThread.
 
         :param title: The title of the new LiveThread.
@@ -85,7 +95,7 @@ def create(self, title, description=None, nsfw=False, resources=None):
             },
         )
 
-    def now(self):
+    def now(self) -> Optional[LiveThread]:
         """Get the currently featured live thread.
 
         :returns: The :class:`.LiveThread` object, or ``None`` if there is
@@ -104,7 +114,9 @@ def now(self):
 class MultiredditHelper(PRAWBase):
     """Provide a set of functions to interact with Multireddits."""
 
-    def __call__(self, redditor, name):
+    def __call__(
+        self, redditor: Union[str, Redditor], name: str
+    ) -> Multireddit:
         """Return a lazy instance of :class:`~.Multireddit`.
 
         :param redditor: A redditor name (e.g., ``'spez'``) or
@@ -117,14 +129,14 @@ def __call__(self, redditor, name):
 
     def create(
         self,
-        display_name,
-        subreddits,
-        description_md=None,
-        icon_name=None,
-        key_color=None,
-        visibility="private",
-        weighting_scheme="classic",
-    ):
+        display_name: str,
+        subreddits: Union[str, Subreddit],
+        description_md: Optional[str] = None,
+        icon_name: Optional[str] = None,
+        key_color: Optional[str] = None,
+        visibility: str = "private",
+        weighting_scheme: str = "classic",
+    ) -> Multireddit:
         """Create a new multireddit.
 
         :param display_name: The display name for the new multireddit.
@@ -165,7 +177,7 @@ def create(
 class SubredditHelper(PRAWBase):
     """Provide a set of functions to interact with Subreddits."""
 
-    def __call__(self, display_name):
+    def __call__(self, display_name: str) -> Subreddit:
         """Return a lazy instance of :class:`~.Subreddit`.
 
         :param display_name: The name of the subreddit.
@@ -181,13 +193,13 @@ def __call__(self, display_name):
 
     def create(
         self,
-        name,
-        title=None,
-        link_type="any",
-        subreddit_type="public",
-        wikimode="disabled",
-        **other_settings
-    ):
+        name: str,
+        title: Optional[str] = None,
+        link_type: str = "any",
+        subreddit_type: str = "public",
+        wikimode: str = "disabled",
+        **other_settings: Optional[str]
+    ) -> Subreddit:
         """Create a new subreddit.
 
         :param name: The name for the new subreddit.