Add stub files for PRAW

.gitignore

@@ -16,3 +16,4 @@
 _build/
 build/
 dist/
+venv/

.travis.yml

@@ -8,7 +8,7 @@ jobs:
     - install: pip install black flake8 pydocstyle sphinx sphinx_rtd_theme .
       python: 3.8
       script:
-        - black --check --verbose *.py docs praw tests
+        - black --check --verbose docs praw tests stubs ./pre_push.py setup.py
         - flake8 --exclude=.eggs,build,docs
         - pydocstyle praw
         - sphinx-build -W docs/ /tmp/foo

pre_push.py

@@ -37,7 +37,9 @@ def run_static():
     Otherwise, it will return statuscode 1
     """
     success = True
-    success &= do_process(["black *.py docs praw tests"], shell=True)
+    success &= do_process(
+        ["black docs praw tests stubs ./pre_push.py setup.py"], shell=True
+    )
     success &= do_process(["flake8", "--exclude=.eggs,build,dist,docs,.tox"])
     success &= do_process(["pydocstyle", "praw"])
     # success &= do_process(["pylint", "--rcfile=.pylintrc", "praw"])

pyproject.toml

@@ -1,3 +1,3 @@
 [tool.black]
-exclude = '/(\.eggs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|_build|buck-out|build|dist)/'
+exclude = '/(\.eggs|\.git|\.hg|\.mypy_cache|\.nox|\.tox|\.venv|_build|buck-out|build|dist|__pycache__)/'
 line-length = 79

setup.py

@@ -1,10 +1,10 @@
 """praw setup.py"""
-
+import pathlib
 import re
 from codecs import open
-from os import path
-from setuptools import find_packages, setup
+from os import fspath, path
 
+from setuptools import find_packages, setup
 
 PACKAGE_NAME = "praw"
 HERE = path.abspath(path.dirname(__file__))
@@ -13,7 +13,6 @@
 with open(path.join(HERE, PACKAGE_NAME, "const.py"), encoding="utf-8") as fp:
     VERSION = re.search('__version__ = "([^"]+)"', fp.read()).group(1)
 
-
 setup(
     name=PACKAGE_NAME,
     author="Bryce Boe",
@@ -49,7 +48,9 @@
     keywords="reddit api wrapper",
     license="Simplified BSD License",
     long_description=README,
-    package_data={"": ["LICENSE.txt"], PACKAGE_NAME: ["*.ini"]},
+    package_data={"": ["LICENSE.txt"],
+                  PACKAGE_NAME: ["*.ini"] + [fspath(file) for file in pathlib.Path(
+        path.abspath(path.join(__file__, "..", "stubs"))).glob('**/*.pyi')]},
     packages=find_packages(exclude=["tests", "tests.*"]),
     setup_requires=["pytest-runner >=2.1"],
     tests_require=[

stubs/README.rst

@@ -0,0 +1,8 @@
+Stub files
+==========
+
+These stub files show the types associated with the functions and methods of PRAW.
+They need to be loaded with a type checker, which is included in most Python IDEs directly or as a plugin.
+
+The stub files are in the same path structure as praw itself,
+with one stub corresponding to one module.

stubs/__init__.pyi

@@ -0,0 +1 @@
+"""Holds PRAW stubs"""

stubs/praw/__init__.pyi

@@ -0,0 +1 @@
+

stubs/praw/config.pyi

@@ -0,0 +1,29 @@
+from configparser import RawConfigParser
+from threading import Lock
+
+from typing import Any, ClassVar, Dict, Optional, Union, TypeVar
+
+_T = TypeVar("_T")
+
+class Config:
+    CONFIG: ClassVar[Optional[RawConfigParser]] = ...
+    CONFIG_NOT_SET: ClassVar[_T] = ...
+    LOCK: ClassVar[Lock] = ...
+
+    @property
+    def short_url(self) -> Union[str, _T]: ...
+
+    custom: Dict[Union[str, Any], Union[str, Any]] = ...
+    client_id: ClassVar[Optional[str]] = ...
+    client_secret: ClassVar[Optional[str]] = ...
+    oauth_url: ClassVar[Optional[str]] = ...
+    reddit_url: ClassVar[Optional[str]] = ...
+    refresh_token: ClassVar[Optional[str]] = ...
+    redirect_uri: ClassVar[Optional[str]] = ...
+    password: ClassVar[Optional[str]] = ...
+    user_agent: ClassVar[Optional[str]] = ...
+    username: ClassVar[Optional[str]] = ...
+
+    def __init__(self, site_name: str, **settings: Union[str, Any]) -> Config: ...
+    check_for_updates: ClassVar[bool] = ...
+    kinds: ClassVar[Dict[str, Any]] = ...

stubs/praw/const.pyi

@@ -0,0 +1,7 @@
+__version__: str
+USER_AGENT_FORMAT: str
+MAX_IMAGE_SIZE: int
+MIN_JPEG_SIZE: int
+MIN_PNG_SIZE: int
+JPEG_HEADER: bytes
+PNG_HEADER: bytes

stubs/praw/endpoints.pyi

@@ -0,0 +1,3 @@
+from typing import Dict
+
+API_PATH: Dict[str, str]

stubs/praw/exceptions.pyi

@@ -0,0 +1,12 @@
+from typing import ClassVar
+
+
+class PRAWException(Exception): ...
+
+class APIException(PRAWException):
+    error_type: ClassVar[str] = ...
+    message: ClassVar[str] = ...
+    field: ClassVar[str] = ...
+    def __init__(self, error_type: str, message: str, field: str) -> APIException: ...
+
+class ClientException(PRAWException): ...

stubs/praw/models/__init__.pyi

@@ -0,0 +1,30 @@
+from .auth import Auth as Auth
+from .front import Front as Front
+from .helpers import LiveHelper as LiveHelper, MultiredditHelper as MultiredditHelper, SubredditHelper as SubredditHelper
+from .inbox import Inbox as Inbox
+from .list.redditor import RedditorList as RedditorList
+from .list.trophy import TrophyList as TrophyList
+from .listing.domain import DomainListing as DomainListing
+from .listing.generator import ListingGenerator as ListingGenerator
+from .listing.listing import Listing as Listing
+from .modaction import ModAction as ModAction
+from .preferences import Preferences as Preferences
+from .reddit.collections import Collection as Collection
+from .reddit.comment import Comment as Comment
+from .reddit.emoji import Emoji as Emoji
+from .reddit.live import LiveThread as LiveThread, LiveUpdate as LiveUpdate
+from .reddit.message import Message as Message, SubredditMessage as SubredditMessage
+from .reddit.modmail import ModmailAction as ModmailAction, ModmailConversation as ModmailConversation, ModmailMessage as ModmailMessage
+from .reddit.more import MoreComments as MoreComments
+from .reddit.multi import Multireddit as Multireddit
+from .reddit.redditor import Redditor as Redditor
+from .reddit.removal_reasons import RemovalReason as RemovalReason
+from .reddit.submission import Submission as Submission
+from .reddit.subreddit import Subreddit as Subreddit
+from .reddit.widgets import Button as Button, ButtonWidget as ButtonWidget, Calendar as Calendar, CommunityList as CommunityList, CustomWidget as CustomWidget, IDCard as IDCard, Image as Image, ImageData as ImageData, ImageWidget as ImageWidget, Menu as Menu, MenuLink as MenuLink, ModeratorsWidget as ModeratorsWidget, PostFlairWidget as PostFlairWidget, RulesWidget as RulesWidget, Submenu as Submenu, SubredditWidgets as SubredditWidgets, SubredditWidgetsModeration as SubredditWidgetsModeration, TextArea as TextArea, Widget as Widget, WidgetModeration as WidgetModeration
+from .reddit.wikipage import WikiPage as WikiPage
+from .redditors import Redditors as Redditors
+from .stylesheet import Stylesheet as Stylesheet
+from .subreddits import Subreddits as Subreddits
+from .trophy import Trophy as Trophy
+from .user import User as User

stubs/praw/models/auth.pyi

@@ -0,0 +1,12 @@
+from typing import Optional, Union, Dict, Sequence, NoReturn, Set
+
+from .base import PRAWBase as PRAWBase
+
+
+class Auth(PRAWBase):
+    @property
+    def limits(self) -> Dict[str, Optional[Union[str, int]]]: ...
+    def authorize(self, code: str) -> Optional[str]: ...
+    def implicit(self, access_token: str, expires_in: int, scope: str) -> NoReturn: ...
+    def scopes(self) -> Set[str]: ...
+    def url(self, scopes: Sequence[str], state: str, duration: str = ..., implicit: bool = ...) -> str: ...

stubs/praw/models/base.pyi

@@ -0,0 +1,9 @@
+from typing import Any, Dict
+
+from ..reddit import Reddit
+
+
+class PRAWBase:
+    @classmethod
+    def parse(cls, data: Dict[Any, Any], reddit: Reddit): ...
+    def __init__(self, reddit: Reddit, _data: Dict[Any, Any]) -> PRAWBase: ...

stubs/praw/models/comment_forest.pyi

@@ -0,0 +1,13 @@
+from typing import Optional, List, Union
+
+from .reddit.comment import Comment
+from .reddit.more import MoreComments
+from .reddit.submission import Submission
+
+
+class CommentForest(List[Union[Comment, MoreComments]]):
+    def __getitem__(self, index: int): ...
+    def __init__(self, submission: Submission, comments: Optional[List[Comment]] = ...) -> CommentForest: ...
+    def __len__(self) -> int: ...
+    def list(self) -> List[Comment]: ...
+    def replace_more(self, limit: int = ..., threshold: int = ...) -> List[MoreComments]: ...

stubs/praw/models/front.pyi

@@ -0,0 +1,9 @@
+from . import ListingGenerator
+from .listing.mixins import SubredditListingMixin as SubredditListingMixin
+from .reddit.submission import Submission
+from ..reddit import Reddit
+
+
+class Front(SubredditListingMixin):
+    def __init__(self, reddit: Reddit) -> None: ...
+    def best(self, **generator_kwargs: str) -> ListingGenerator[Submission]: ...

stubs/praw/models/helpers.pyi

@@ -0,0 +1,22 @@
+from typing import Any, Optional, List, Sequence, Literal
+
+from . import ListingGenerator
+from .base import PRAWBase as PRAWBase
+from .reddit.live import LiveThread as LiveThread
+from .reddit.multi import Multireddit as Multireddit
+from .reddit.subreddit import Subreddit
+
+
+class LiveHelper(PRAWBase):
+    def __call__(self, id: str) -> LiveThread: ...
+    def info(self, ids: List[str]) -> ListingGenerator[LiveThread]: ...
+    def create(self, title: str, description: Optional[str] = ..., nsfw: bool = ..., resources: Optional[str] = ...) -> LiveThread: ...
+    def now(self) -> Optional[LiveThread]: ...
+
+class MultiredditHelper(PRAWBase):
+    def __call__(self, redditor: str, name: str) -> Multireddit: ...
+    def create(self, display_name: str, subreddits: Sequence[Subreddit], description_md: Optional[str] = ..., icon_name: Literal["art and design", "ask", "books", "business", "cars", "comics", "cute animals", "diy", "entertainment", "food and drink", "funny", "games", "grooming", "health", "life advice", "military", "models pinup", "music", "news", "philosophy", "pictures and gifs", "science", "shopping", "sports", "style", "tech", "travel", "unusual stories", "video"] = ..., key_color: Optional[str] = ..., visibility: Literal["hidden", "private", "public"] = ..., weighting_scheme: Literal["classic", "fresh"] = ...) -> Multireddit: ...
+
+class SubredditHelper(PRAWBase):
+    def __call__(self, display_name: str) -> Subreddit: ...
+    def create(self, name: str, title: Optional[str] = ..., link_type: Literal["any", "link", "self"] = ..., subreddit_type: Literal["archived", "employees_only", "gold_only", "gold_restricted", "private", "public", "restricted"] = ..., wikimode: Literal["anyone", "disabled", "modonly"] = ..., **other_settings: Any) -> Subreddit: ...

stubs/praw/models/inbox.pyi

@@ -0,0 +1,21 @@
+from typing import List, Generator, NoReturn, Union
+
+from . import Message, ListingGenerator
+from .base import PRAWBase as PRAWBase
+from .reddit.comment import Comment
+
+
+class Inbox(PRAWBase):
+    def all(self, **generator_kwargs: str) -> Generator[Union[Comment, Message]]: ...
+    def collapse(self, items: List[Message]) -> NoReturn: ...
+    def comment_replies(self, **generator_kwargs: str) -> ListingGenerator[Comment]: ...
+    def mark_read(self, items: List[Message]) -> NoReturn: ...
+    def mark_unread(self, items: List[Message]) -> NoReturn: ...
+    def mentions(self, **generator_kwargs: str) -> ListingGenerator[Comment]: ...
+    def message(self, message_id: str) -> Message: ...
+    def messages(self, **generator_kwargs: str) -> ListingGenerator[Message]: ...
+    def sent(self, **generator_kwargs: str) -> ListingGenerator[Message]: ...
+    def stream(self, **stream_options: str) -> ListingGenerator[Message]: ...
+    def submission_replies(self, **generator_kwargs: str) -> ListingGenerator[Comment]: ...
+    def uncollapse(self, items: List[Message]) -> NoReturn: ...
+    def unread(self, mark_read: bool = ..., **generator_kwargs: str) -> Generator[Union[Comment, Message]]: ...

stubs/praw/models/list/base.pyi

@@ -0,0 +1,13 @@
+from typing import Any, Dict, Optional, List, Iterator, Union
+
+from ..base import PRAWBase as PRAWBase
+from ...reddit import Reddit
+
+
+class BaseList(PRAWBase):
+    CHILD_ATTRIBUTE: Optional[Union[List[Any], str]] = ...
+    def __init__(self, reddit: Reddit, _data: Dict[str, Any]) -> BaseList: ...
+    def __contains__(self, item: Any) -> bool: ...
+    def __getitem__(self, index: int) -> Any: ...
+    def __iter__(self) -> Iterator[Any]: ...
+    def __len__(self) -> int: ...

stubs/praw/models/list/redditor.pyi

@@ -0,0 +1,8 @@
+from typing import List
+
+from .base import BaseList as BaseList
+from ..reddit.redditor import Redditor
+
+
+class RedditorList(BaseList, List[Redditor]):
+    CHILD_ATTRIBUTE: str = ...

stubs/praw/models/list/trophy.pyi

@@ -0,0 +1,4 @@
+from .base import BaseList as BaseList
+
+class TrophyList(BaseList):
+    CHILD_ATTRIBUTE: str = ...

stubs/praw/models/listing/domain.pyi

@@ -0,0 +1,7 @@
+from .mixins import BaseListingMixin as BaseListingMixin, \
+    RisingListingMixin as RisingListingMixin
+from ...reddit import Reddit
+
+
+class DomainListing(BaseListingMixin, RisingListingMixin):
+    def __init__(self, reddit: Reddit, domain: str) -> None: ...

stubs/praw/models/listing/generator.pyi

@@ -0,0 +1,17 @@
+from typing import Any, Optional, Dict
+from typing import Generator, TypeVar
+
+from ..base import PRAWBase as PRAWBase
+from ...reddit import Reddit
+
+T = TypeVar("T")
+
+
+class ListingGenerator(PRAWBase, Generator[T, None, None]):
+    limit: int = ...
+    params: Dict[str, str] = ...
+    url: str = ...
+    yielded: int = ...
+    def __init__(self, reddit: Reddit, url: str, limit: int = ..., params: Optional[Dict[str, str]] = ...) -> ListingGenerator: ...
+    def __iter__(self) -> ListingGenerator: ...
+    def __next__(self) -> Any: ...

stubs/praw/models/listing/listing.pyi

@@ -0,0 +1,16 @@
+from typing import Any, NoReturn, Optional, TypeVar, Collection
+
+from ..base import PRAWBase as PRAWBase
+
+T = TypeVar("T")
+
+class Listing(PRAWBase, Collection[T]):
+    CHILD_ATTRIBUTE: str = ...
+    def __len__(self) -> int: ...
+    def __getitem__(self, index: int) -> Any: ...
+    def __setattr__(self, attribute: str, value: Any) -> NoReturn: ...
+
+class FlairListing(Listing):
+    CHILD_ATTRIBUTE: str = ...
+    @property
+    def after(self) -> Optional[Any]: ...

stubs/praw/models/listing/mixins/__init__.pyi

@@ -0,0 +1,5 @@
+from .base import BaseListingMixin as BaseListingMixin
+from .redditor import RedditorListingMixin as RedditorListingMixin
+from .rising import RisingListingMixin as RisingListingMixin
+from .submission import SubmissionListingMixin as SubmissionListingMixin
+from .subreddit import SubredditListingMixin as SubredditListingMixin

stubs/praw/models/listing/mixins/base.pyi

@@ -0,0 +1,12 @@
+from typing import Any, Set, Literal
+
+from ... import ListingGenerator
+from ...base import PRAWBase as PRAWBase
+
+
+class BaseListingMixin(PRAWBase):
+    VALID_TIME_FILTERS: Set[str] = ...
+    def controversial(self, time_filter: Literal["all", "day", "hour", "month", "week", "year"] = ..., **generator_kwargs: str) -> ListingGenerator[Any]: ...
+    def hot(self, **generator_kwargs: str) -> ListingGenerator[Any]: ...
+    def new(self, **generator_kwargs: str) -> ListingGenerator[Any]: ...
+    def top(self, time_filter: Literal["all", "day", "hour", "month", "week", "year"] = ..., **generator_kwargs: str) -> ListingGenerator[Any]: ...

stubs/praw/models/listing/mixins/gilded.pyi

@@ -0,0 +1,8 @@
+from typing import Any
+
+from ... import ListingGenerator
+from ...base import PRAWBase as PRAWBase
+
+
+class GildedListingMixin(PRAWBase):
+    def gilded(self, **generator_kwargs: str) -> ListingGenerator[Any]: ...

stubs/praw/models/listing/mixins/redditor.pyi

@@ -0,0 +1,26 @@
+from typing import TypeVar, Collection
+from typing import Union
+
+from .base import BaseListingMixin as BaseListingMixin
+from .gilded import GildedListingMixin as GildedListingMixin
+from ...reddit.comment import Comment
+from ...reddit.submission import Submission
+from ....reddit import Reddit
+from ....util.cache import cachedproperty
+
+T = TypeVar("T")
+
+
+class RedditorListingMixin(BaseListingMixin, GildedListingMixin):
+    @cachedproperty
+    def comments(self) -> SubListing[Comment]: ...
+    @cachedproperty
+    def submissions(self) -> SubListing[Submission]: ...
+    def downvoted(self, **generator_kwargs: str) -> Union[Comment, Submission]: ...
+    def gildings(self, **generator_kwargs: str) -> Union[Comment, Submission]: ...
+    def hidden(self, **generator_kwargs: str) -> Union[Comment, Submission]: ...
+    def saved(self, **generator_kwargs: str) -> Union[Comment, Submission]: ...
+    def upvoted(self, **generator_kwargs: str) -> Union[Comment, Submission]: ...
+
+class SubListing(BaseListingMixin, Collection[T]):
+    def __init__(self, reddit: Reddit, base_path: str, subpath: str) -> SubListing: ...

stubs/praw/models/listing/mixins/rising.pyi

@@ -0,0 +1,8 @@
+from ... import ListingGenerator
+from ...base import PRAWBase as PRAWBase
+from ...reddit.submission import Submission
+
+
+class RisingListingMixin(PRAWBase):
+    def random_rising(self, **generator_kwargs: str) -> ListingGenerator[Submission]: ...
+    def rising(self, **generator_kwargs: str) -> ListingGenerator[Submission]: ...