Overview

RedditWarp is a Reddit API wrapper library written in Python, enabling the development of 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 RedditWarp’s tooling is primarily designed for developers and may not be as user-friendly for non-technical users.

Although this library may not be well-suited for beginner programmers, experienced programmers should find it familiar and easy to learn. It strives to be simple to understand and learn by having a consistent programming style whose design emphasizes consistency, cleanliness, and correctness over brevity. Additionally, access to well-designed low-level components enables advanced use-cases. This provides a more powerful and fine-grained tool for working with the Reddit API than ever before.

The library organizes all the possible API calls it supports on the client instance as sub-objects of client.p:

>>> import redditwarp.SYNC
>>> client = redditwarp.SYNC.Client()
>>> user = client.p.user.fetch_by_name('spez')
>>> user
<redditwarp.models.user_SYNC.User object at 0x1034e1000>
>>> user.id36
'1w72'
>>> user.name
'spez'
>>> str(user.created_at)
'2005-06-06 04:00:00+00:00'

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

Evidently, RedditWarp code features a functional programming design. The API calls are organised into a big catalog, and the majority of models objects are treated as read-only. In terms of your experience, this means that the objects you work with behave consistently, reducing the cognitive load of learning each of the different sections of the Reddit API.

Low-level API requests can be made like so:

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

The following code is an example of a very small and 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.

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

If you’re familiar with PRAW, take a look at this document that contains extra examples to help you get the hang of RedditWarp quicker.