The Reddit Instance¶

class praw.Reddit(site_name=None, *, config_interpolation=None, requestor_class=None, requestor_kwargs=None, **config_settings)¶

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",
)

Parameters:

site_name (str | None)
config_interpolation (str | None)
requestor_class (type[prawcore.requestor.Requestor] | None)
requestor_kwargs (dict[str, Any] | None)
config_settings (str | bool | int | None)

__init__(site_name=None, *, config_interpolation=None, requestor_class=None, requestor_kwargs=None, **config_settings)¶

Initialize a Reddit instance.

Parameters:

site_name (str | None) – 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 (str | None) – Config parser interpolation type that will be passed to Config (default: None).
requestor_class (type[Requestor] | None) – A class that will be used to create a requestor. If not set, use prawcore.Requestor (default: None).
requestor_kwargs (dict[str, Any] | None) – Dictionary with additional keyword arguments used to initialize the requestor (default: None).
config_settings (str | bool | int | None)

Return type:

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=None, *, url=None)¶

Return a lazy instance of Comment.

Parameters:

id (str | None) – The ID of the comment.
url (str | None) – A permalink pointing to the comment.

Return type:

Comment

Note

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

delete(path, *, data=None, json=None, params=None)¶

Return parsed objects returned from a DELETE request to path.

Parameters:

path (str) – The path to fetch.
data (dict[str, str | Any] | bytes | IO | str | None) – Dictionary, bytes, or file-like object to send in the body of the request (default: None).
json (dict[Any, Any] | list[Any] | None) – 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 (str | dict[str, str] | None) – The query parameters to add to the request (default: None).

Return type:

Any

domain(domain)¶

Return an instance of DomainListing.

Parameters:: domain (str) – The domain to obtain submission listings for.
Return type:: DomainListing

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, *, params=None)¶

Return parsed objects returned from a GET request to path.

Parameters:

path (str) – The path to fetch.
params (str | dict[str, str | int] | None) – The query parameters to add to the request (default: None).

Return type:

Any

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=None, subreddits=None, url=None)¶

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

Parameters:

fullnames (Iterable[str] | None) – A list of fullnames for comments, submissions, and/or subreddits.
subreddits (Iterable[Subreddit | str] | None) – A list of subreddit names or Subreddit objects to retrieve subreddits from.
url (str | None) – A url (as a string) to retrieve lists of link submissions from.

Return type:

Generator[Subreddit | Comment | Submission, None, None]

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, *, data=None, json=None, params=None)¶

Return parsed objects returned from a PATCH request to path.

Parameters:

path (str) – The path to fetch.
data (dict[str, str | Any] | bytes | IO | str | None) – Dictionary, bytes, or file-like object to send in the body of the request (default: None).
json (dict[Any, Any] | list[Any] | None) – 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 (str | dict[str, str] | None) – The query parameters to add to the request (default: None).

Return type:

Any

post(path, *, data=None, files=None, json=None, params=None)¶

Return parsed objects returned from a POST request to path.

Parameters:

path (str) – The path to fetch.
data (dict[str, str | Any] | bytes | IO | str | None) – Dictionary, bytes, or file-like object to send in the body of the request (default: None).
files (dict[str, IO] | None) – Dictionary, filename to file (like) object mapping (default: None).
json (dict[Any, Any] | list[Any] | None) – 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 (str | dict[str, str] | None) – The query parameters to add to the request (default: None).

Return type:

Any

put(path, *, data=None, json=None)¶

Return parsed objects returned from a PUT request to path.

Parameters:

path (str) – The path to fetch.
data (dict[str, str | Any] | bytes | IO | str | None) – Dictionary, bytes, or file-like object to send in the body of the request (default: None).
json (dict[Any, Any] | list[Any] | None) – 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.

Return type:

Any

property read_only: bool¶: Return True when using the ReadOnlyAuthorizer.

redditor(name=None, *, fullname=None)¶

Return a lazy instance of Redditor.

Parameters:

name (str | None) – The name of the redditor.
fullname (str | None) – The fullname of the redditor, starting with t2_.

Return type:

Redditor

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=None, files=None, json=None, method, params=None, path)¶

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

Parameters:

data (dict[str, str | Any] | bytes | IO | str | None) – Dictionary, bytes, or file-like object to send in the body of the request (default: None).
files (dict[str, IO] | None) – Dictionary, filename to file (like) object mapping (default: None).
json (dict[Any, Any] | list[Any] | None) – 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 (str) – The HTTP method (e.g., "GET", "POST", "PUT", "DELETE").
params (str | dict[str, str | int] | None) – The query parameters to add to the request (default: None).
path (str) – The path to fetch.

Return type:

Any

submission(id=None, *, url=None)¶

Return a lazy instance of Submission.

Parameters:

id (str | None) – A Reddit base36 submission ID, e.g., "2gmzqe".
url (str | None) – A URL supported by Submission.id_from_url().

Return type:

Submission

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)¶

Check to see if the username is available.

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

reddit.username_available("bboe")

Return type:: bool
Parameters:: name (str)

Helper Classes