The Reddit Instance

class praw.Reddit(site_name: Optional[str] = None, *, config_interpolation: Optional[str] = None, requestor_class: Optional[Type[prawcore.requestor.Requestor]] = None, requestor_kwargs: Optional[Dict[str, Any]] = None, token_manager: Optional[praw.util.token_manager.BaseTokenManager] = None, **config_settings: Optional[Union[str, bool]])

The Reddit class provides convenient access to Reddit’s API.

Instances of this class are the gateway to interacting with Reddit’s API through PRAW. The canonical way to obtain an instance of this class is via:

import praw

reddit = praw.Reddit(
    client_id="CLIENT_ID",
    client_secret="CLIENT_SECRET",
    password="PASSWORD",
    user_agent="USERAGENT",
    username="USERNAME",
)
__init__(site_name: Optional[str] = None, *, config_interpolation: Optional[str] = None, requestor_class: Optional[Type[prawcore.requestor.Requestor]] = None, requestor_kwargs: Optional[Dict[str, Any]] = None, token_manager: Optional[praw.util.token_manager.BaseTokenManager] = None, **config_settings: Optional[Union[str, bool]])

Initialize a Reddit instance.

Parameters

  • site_name – The name of a section in your praw.ini file from which to load settings from. This parameter, in tandem with an appropriately configured praw.ini, file is useful if you wish to easily save credentials for different applications, or communicate with other servers running Reddit. If site_name is None, then the site name will be looked for in the environment variable praw_site. If it is not found there, the DEFAULT site will be used (default: None).

  • config_interpolation – Config parser interpolation type that will be passed to Config (default: None).

  • requestor_class – A class that will be used to create a requestor. If not set, use prawcore.Requestor (default: None).

  • requestor_kwargs – Dictionary with additional keyword arguments used to initialize the requestor (default: None).

  • token_manager – When provided, the passed instance, a subclass of BaseTokenManager, will manage tokens via two callback functions. This parameter must be provided in order to work with refresh tokens (default: None).

Additional keyword arguments will be used to initialize the Config object. This can be used to specify configuration settings during instantiation of the Reddit instance. For more details, please see Configuring PRAW.

Required settings are:

  • client_id

  • client_secret (for installed applications set this value to None)

  • user_agent

The requestor_class and requestor_kwargs allow for customization of the requestor Reddit will use. This allows, e.g., easily adding behavior to the requestor or wrapping its Session in a caching layer. Example usage:

import json

import betamax
import requests
from prawcore import Requestor

from praw import Reddit


class JSONDebugRequestor(Requestor):
    def request(self, *args, **kwargs):
        response = super().request(*args, **kwargs)
        print(json.dumps(response.json(), indent=4))
        return response


my_session = betamax.Betamax(requests.Session())
reddit = Reddit(
    ..., requestor_class=JSONDebugRequestor, requestor_kwargs={"session": my_session}
)
auth

An instance of Auth.

Provides the interface for interacting with installed and web applications.

See also

Obtain the Authorization URL

comment(id: Optional[str] = None, *, url: Optional[str] = None)

Return a lazy instance of Comment.

Parameters

  • id – The ID of the comment.

  • url – A permalink pointing to the comment.

Note

If you want to obtain the comment’s replies, you will need to call refresh() on the returned Comment.

delete(path: str, *, data: Optional[Union[Dict[str, Union[str, Any]], bytes, IO, str]] = None, json: Optional[Dict[Any, Any]] = None, params: Optional[Union[str, Dict[str, str]]] = None) → Any

Return parsed objects returned from a DELETE request to path.

Parameters

  • path – The path to fetch.

  • data – Dictionary, bytes, or file-like object to send in the body of the request (default: None).

  • json – JSON-serializable object to send in the body of the request with a Content-Type header of application/json (default: None). If json is provided, data should not be.

  • params – The query parameters to add to the request (default: None).

domain(domain: str)

Return an instance of DomainListing.

Parameters

domain – The domain to obtain submission listings for.

drafts

An instance of DraftHelper.

Provides the interface for working with Draft instances.

For example, to list the currently authenticated user’s drafts:

drafts = reddit.drafts()

To create a draft on r/test run:

reddit.drafts.create(title="title", selftext="selftext", subreddit="test")
front

An instance of Front.

Provides the interface for interacting with front page listings. For example:

for submission in reddit.front.hot():
    print(submission)
get(path: str, *, params: Optional[Union[str, Dict[str, Union[str, int]]]] = None)

Return parsed objects returned from a GET request to path.

Parameters

  • path – The path to fetch.

  • params – The query parameters to add to the request (default: None).

inbox

An instance of Inbox.

Provides the interface to a user’s inbox which produces Message, Comment, and Submission instances. For example, to iterate through comments which mention the authorized user run:

for comment in reddit.inbox.mentions():
    print(comment)
info(*, fullnames: Optional[Iterable[str]] = None, subreddits: Optional[Iterable[Union[praw.models.Subreddit, str]]] = None, url: Optional[str] = None) → Generator[Union[praw.models.Subreddit, praw.models.Comment, praw.models.Submission], None, None]

Fetch information about each item in fullnames, url, or subreddits.

Parameters

  • fullnames – A list of fullnames for comments, submissions, and/or subreddits.

  • subreddits – A list of subreddit names or Subreddit objects to retrieve subreddits from.

  • url – A url (as a string) to retrieve lists of link submissions from.

Returns

A generator that yields found items in their relative order.

Items that cannot be matched will not be generated. Requests will be issued in batches for each 100 fullnames.

Note

For comments that are retrieved via this method, if you want to obtain its replies, you will need to call refresh() on the yielded Comment.

Note

When using the URL option, it is important to be aware that URLs are treated literally by Reddit’s API. As such, the URLs "youtube.com" and "https://www.youtube.com" will provide a different set of submissions.

live

An instance of LiveHelper.

Provides the interface for working with LiveThread instances. At present only new live threads can be created.

reddit.live.create(title="title", description="description")
multireddit

An instance of MultiredditHelper.

Provides the interface to working with Multireddit instances. For example, you can obtain a Multireddit instance via:

reddit.multireddit(redditor="samuraisam", name="programming")
notes

An instance of RedditModNotes.

Provides the interface for working with ModNotes for multiple redditors across multiple subreddits.

Note

The authenticated user must be a moderator of the provided subreddit(s).

For example, the latest note for u/spez in r/redditdev and r/test, and for u/bboe in r/redditdev can be iterated through like so:

redditor = reddit.redditor("bboe")
subreddit = reddit.subreddit("redditdev")

pairs = [(subreddit, "spez"), ("test", "spez"), (subreddit, redditor)]

for note in reddit.notes(pairs=pairs):
    print(f"{note.label}: {note.note}")
patch(path: str, *, data: Optional[Union[Dict[str, Union[str, Any]], bytes, IO, str]] = None, json: Optional[Dict[Any, Any]] = None) → Any

Return parsed objects returned from a PATCH request to path.

Parameters

  • path – The path to fetch.

  • data – Dictionary, bytes, or file-like object to send in the body of the request (default: None).

  • json – JSON-serializable object to send in the body of the request with a Content-Type header of application/json (default: None). If json is provided, data should not be.

post(path: str, *, data: Optional[Union[Dict[str, Union[str, Any]], bytes, IO, str]] = None, files: Optional[Dict[str, IO]] = None, json: Optional[Dict[Any, Any]] = None, params: Optional[Union[str, Dict[str, str]]] = None) → Any

Return parsed objects returned from a POST request to path.

Parameters

  • path – The path to fetch.

  • data – Dictionary, bytes, or file-like object to send in the body of the request (default: None).

  • files – Dictionary, filename to file (like) object mapping (default: None).

  • json – JSON-serializable object to send in the body of the request with a Content-Type header of application/json (default: None). If json is provided, data should not be.

  • params – The query parameters to add to the request (default: None).

put(path: str, *, data: Optional[Union[Dict[str, Union[str, Any]], bytes, IO, str]] = None, json: Optional[Dict[Any, Any]] = None)

Return parsed objects returned from a PUT request to path.

Parameters

  • path – The path to fetch.

  • data – Dictionary, bytes, or file-like object to send in the body of the request (default: None).

  • json – JSON-serializable object to send in the body of the request with a Content-Type header of application/json (default: None). If json is provided, data should not be.

random_subreddit(*, nsfw: bool = False) → praw.models.Subreddit

Return a random lazy instance of Subreddit.

Parameters

nsfw – Return a random NSFW (not safe for work) subreddit (default: False).

property read_only: bool

Return True when using the ReadOnlyAuthorizer.

redditor(name: Optional[str] = None, *, fullname: Optional[str] = None) → praw.models.Redditor

Return a lazy instance of Redditor.

Parameters

  • name – The name of the redditor.

  • fullname – The fullname of the redditor, starting with t2_.

Either name or fullname can be provided, but not both.

redditors

An instance of Redditors.

Provides the interface for Redditor discovery. For example, to iterate over the newest Redditors, run:

for redditor in reddit.redditors.new(limit=None):
    print(redditor)
request(*, data: Optional[Union[Dict[str, Union[str, Any]], bytes, IO, str]] = None, files: Optional[Dict[str, IO]] = None, json: Optional[Dict[Any, Any]] = None, method: str, params: Optional[Union[str, Dict[str, Union[str, int]]]] = None, path: str) → Any

Return the parsed JSON data returned from a request to URL.

Parameters

  • data – Dictionary, bytes, or file-like object to send in the body of the request (default: None).

  • files – Dictionary, filename to file (like) object mapping (default: None).

  • json – JSON-serializable object to send in the body of the request with a Content-Type header of application/json (default: None). If json is provided, data should not be.

  • method – The HTTP method (e.g., "GET", "POST", "PUT", "DELETE").

  • params – The query parameters to add to the request (default: None).

  • path – The path to fetch.

submission(id: Optional[str] = None, *, url: Optional[str] = None) → praw.models.Submission

Return a lazy instance of Submission.

Parameters

Either id or url can be provided, but not both.

subreddit

An instance of SubredditHelper.

Provides the interface to working with Subreddit instances. For example to create a Subreddit run:

reddit.subreddit.create(name="coolnewsubname")

To obtain a lazy Subreddit instance run:

reddit.subreddit("test")

Multiple subreddits can be combined and filtered views of r/all can also be used just like a subreddit:

reddit.subreddit("redditdev+learnpython+botwatch")
reddit.subreddit("all-redditdev-learnpython")
subreddits

An instance of Subreddits.

Provides the interface for Subreddit discovery. For example, to iterate over the set of default subreddits run:

for subreddit in reddit.subreddits.default(limit=None):
    print(subreddit)
user

An instance of User.

Provides the interface to the currently authorized Redditor. For example to get the name of the current user run:

print(reddit.user.me())
username_available(name: str) → bool

Check to see if the username is available.

For example, to check if the username bboe is available, try:

reddit.username_available("bboe")
property validate_on_submit: bool

Get validate_on_submit.

Deprecated since version 7.0: If property validate_on_submit is set to False, the behavior is deprecated by Reddit. This attribute will be removed around May-June 2020.

Helper Classes