Skip to content
Back to top
View this page

# The Reddit Instance

class praw.Reddit(site_name: str | None = None, *, config_interpolation: str | None = None, requestor_class: Type[Requestor] | None = None, requestor_kwargs: Dict[str, Any] | None = None, token_manager: BaseTokenManager | None = None, **config_settings: str | bool | int | None)

  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: str | None = None, *, config_interpolation: str | None = None, requestor_class: Type[Requestor] | None = None, requestor_kwargs: Dict[str, Any] | None = None, token_manager: BaseTokenManager | None = None, **config_settings: str | bool | int | None)

    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: str | None = None, *, url: str | None = 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: Dict[str, str | Any] | bytes | IO | str | None = None, json: Dict[Any, Any] | None = None, params: str | Dict[str, str] | None = 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: str | Dict[str, str | int] | None = 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: Iterable[str] | None = None, subreddits: Iterable[praw.models.Subreddit | str] | None = None, url: str | None = None) → Generator[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 `ModNote`s 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: Dict[str, str | Any] | bytes | IO | str | None = None, json: Dict[Any, Any] | None = 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: Dict[str, str | Any] | bytes | IO | str | None = None, files: Dict[str, IO] | None = None, json: Dict[Any, Any] | None = None, params: str | Dict[str, str] | None = 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: Dict[str, str | Any] | bytes | IO | str | None = None, json: Dict[Any, Any] | None = 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: str | None = None, *, fullname: str | None = 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: Dict[str, str | Any] | bytes | IO | str | None = None, files: Dict[str, IO] | None = None, json: Dict[Any, Any] | None = None, method: str, params: str | Dict[str, str | int] | None = 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: str | None = None, *, url: str | None = None) → praw.models.Submission

    Return a lazy instance of `Submission`.

    Parameters:

      - id – A Reddit base36 submission ID, e.g., `"2gmzqe"`.

      - url – A URL supported by `Submission.id_from_url()`.

    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

- reddit.live
  - `DraftHelper`
- reddit.front
  - `Front`
- reddit.inbox
  - `Inbox`
- reddit.live
  - `LiveHelper`
- reddit.multireddit
  - `MultiredditHelper`
- reddit.redditors
  - `Redditors`
- reddit.subreddit
  - `SubredditHelper`
- reddit.subreddits
  - `Subreddits`
- reddit.user
  - `User`