Overview

RedditWarp is a Reddit API wrapper library written in Python that can help you develop robust statically-typed Reddit bots and programs.

The library can be used to create advanced automations for subreddit moderation in ways that go beyond the capabilities of AutoModerator. However, it’s worth noting that this tooling is primarily designed for developers and comparatively may not be as user-friendly for non-technical users.

While this library may not be tailored for beginners, experienced programmers will likely find it familiar and straightforward. Its consistent programming style prioritizes cleanliness and correctness over brevity. Moreover, the inclusion of well-designed low-level components allows for advanced use-cases, making it a powerful, fine-grained tool for working with the Reddit API.

RedditWarp code features a functional programming design. The API calls are organized into a comprehensive catalog, and most model objects are treated as read-only. From a user’s perspective, this consistency simplifies working with different sections of the Reddit API, reducing the cognitive load.

All the possible API calls the library supports are neatly categorized into sub-objects on the client instance:

>>> import redditwarp.SYNC
>>> client = redditwarp.SYNC.Client()
>>> user = client.p.user.fetch_by_name('Pyprohly')
>>> user.id36
'4x25quk'
>>> user.name
'Pyprohly'
>>> str(user.created_at)
'2017-06-23 15:25:50+00:00'

The high-level procedure calls return objects called ‘models’. Models represent an API resource at a particular point in time. These objects are never mutated after they are created.

Low-level API requests can also be made:

>>> d = client.request('GET', '/user/Pyprohly/about')['data']
>>> print(d.keys() == user.d.keys())
True

The following code is an example of a basic bot script that monitors r/test for comments and direct messages the user u/test about any comments containing the string “Hello World”.

#!/usr/bin/env python
from __future__ import annotations
from typing import TYPE_CHECKING
if TYPE_CHECKING:
    from redditwarp.models.comment_ASYNC import Comment

import asyncio

import redditwarp.ASYNC
from redditwarp.streaming.makers.subreddit_ASYNC import create_comment_stream
from redditwarp.streaming.ASYNC import flow

sr = 'test'
user = 'test'
needle = 'Hello World'

async def main() -> None:
    client = redditwarp.ASYNC.Client.from_praw_config('SuvaBot')
    async with client:
        comment_stream = create_comment_stream(client, sr)

        @comment_stream.output.attach
        async def _(comm: Comment) -> None:
            if needle in comm.body:
                subject = f"World greeted by u/{comm.author_display_name}"
                body = comm.permalink
                await client.p.message.send(user, subject, body)

        await flow(comment_stream)

asyncio.run(main())

Before using this library to access the Reddit API, please see the Reddit Data API Wiki for rules, terms, and conditions.

If you intend to use this library to create a Reddit bot, please read the bottiquette before wreaking havoc all over the internet.

Doing data science? Know that the amount of historical data that can be obtained from the Reddit API is limited. For data science or academic research purposes that requires large volumes of data, using the Pushshift service to bulk download historical archives may be a more suitable option. Visit r/pushshift to learn more.

Coming from PRAW? Take a look at this document which contains code examples to help you quickly get up to speed with RedditWarp.