PRAW

PRAW (Python Reddit API Wrapper) is the de facto standard library for talking to Reddit from Python. It wraps the full breadth of Reddit’s REST API — subreddits, submissions, comments, redditors, moderation actions, modmail, live threads, and more — behind a small set of intuitive, chainable objects built around a single praw.Reddit client instance.

The library is built on top of prawcore for OAuth session and rate-limit handling, so requests automatically back off and retry according to Reddit’s API rules without any manual sleep() calls. Models are lazily fetched: calling reddit.submission(url=...) returns instantly, and the network request only fires the first time you touch an attribute that wasn’t already loaded.

PRAW has been maintained continuously since 2012 (as a rename of the earlier reddit package dating to 2010), carries a 100%-enforced test coverage requirement backed by VCR-cassette integration tests, and ships full type hints (py.typed) checked with pyright. For asyncio-based bots, the maintainers also publish Async PRAW as a parallel async-native implementation.

What You Get

• A single Reddit client object that manages OAuth (script, web, or read-only flows) and automatically respects Reddit’s rate limits without manual sleep() calls
• Lazy-loaded model objects (Submission, Comment, Redditor, Subreddit, etc.) that only hit the network the first time an unfetched attribute is accessed
• Generator-based listings for hot/new/top/rising/controversial feeds and comment forests that auto-paginate across result pages
• Full moderation API coverage — removing content, managing modmail conversations, mod notes, mod queue actions, and subreddit settings
• Streaming helpers for polling new submissions/comments in near-real-time without hand-rolling a polling loop
• Complete type hints (py.typed) checked with pyright, plus extensive Sphinx documentation with tutorials and a full API reference

Common Use Cases

• Building moderation bots that auto-remove rule-breaking posts or comments and notify mods via modmail
• Building reply/utility bots that watch a subreddit’s new-submissions stream and respond automatically
• Scraping and archiving subreddit content or comment trees for research or datasets
• Automating repetitive moderator tasks — flair management, scheduled posts, wiki-page updates
• Building read-only analytics tools that track subreddit activity, karma trends, or post performance

Under The Hood

Architecture The Reddit class in praw/reddit.py (973 lines) is the central client: it configures a prawcore Authorizer/Requestor for OAuth, resolves API paths from praw/endpoints.py, and hands every JSON response to Objector (praw/objector.py) for polymorphic deserialization into the right model class. The model layer under praw/models/reddit/ builds on RedditBase (praw/models/reddit/base.py), which implements a lazy-object pattern: __getattr__ triggers _fetch() on first access to an attribute that wasn’t already populated, so constructing reddit.submission(id) never makes a network call by itself. Listings and comment trees live under praw/models/listing/ as pagination generators layered on top of the base model objects. Because nearly every model’s __eq__, __hash__, __repr__, and attribute access all route through RedditBase, it functions as the single load-bearing abstraction the rest of the library depends on.

Tech Stack Built with a hatchling build backend (pyproject.toml) and requires Python 3.10+. Runtime dependencies are deliberately minimal: prawcore (OAuth session and rate-limit handling), defusedxml (safe XML parsing for legacy endpoints), update_checker, and websocket-client for streaming features, plus typing-extensions on older Pythons. Tooling is uv-centric: tox-uv with uv-venv-lock-runner drives environments across Python 3.10 through 3.14, ruff (full ALL ruleset, narrowly relaxed per-file) handles lint/format, pyright in standard mode handles type-checking, and sphinx + furo build the documentation site. No web framework is involved — this is a pure API client library.

Code Quality The test suite is split into tests/unit/ (isolated logic) and tests/integration/ (VCR-cassette-backed HTTP replay via vcrpy), run under pytest with coverage and a hard fail_under = 100 gate enforced in the tox test environment — genuinely comprehensive coverage, not just present. praw/py.typed marks the package as fully typed, checked with pyright, and every module uses from __future__ import annotations consistently. Errors are modeled explicitly through a dedicated praw/exceptions.py hierarchy (RedditAPIException, ClientException, etc.) rather than being swallowed. Pre-commit hooks and CI enforce the ruff/pyright/test gates on every change.

API Design The headline design choice is transparent laziness: objects returned by methods like reddit.submission() or reddit.redditor() are cheap to construct and only issue a request the first time you read an attribute that wasn’t supplied up front, which keeps common call chains (reddit.subreddit("test").hot(limit=10)) both fast and intuitive. Rate-limit handling is fully internal — PRAW’s own pitch is that you never need sleep() calls in your bot code, unlike raw requests usage against Reddit’s API. The library also cleanly separates its sync implementation from Async PRAW, a parallel maintained package with an (almost) identical API for asyncio-based bots, so developers pick sync or async without relearning the interface.