You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
voussoir 83fc4ade2e
Update with link to
2 weeks ago
timesearch_modules Print 404 error separately from general stacktrace. 5 months ago
utilities main should return args.func(args) value. 1 year ago
.gitignore Delete all this templated junk out of gitignore. 1 year ago Update with link to 2 weeks ago Update license, contact, donate for many projects. 3 months ago
LICENSE.txt Update license, contact, donate for many projects. 3 months ago Add Mirrors header. 4 months ago
requirements.txt Initial migratory commit from voussoir/reddit. 3 years ago Add --help to "see details on each command". 6 months ago
timesearch_logo.svg Add timesearch_logo.svg. 1 year ago


NEWS (2018 04 09):

Reddit has removed the timestamp search feature which timesearch was built off of (original). Please message the admins by sending a PM to /r/ Let them know that this feature is important to you, and you would like them to restore it on the new search stack.

Thankfully, Jason Baumgartner aka /u/Stuck_in_the_Matrix, owner of, has made it easy to interact with his dataset. Timesearch now queries his API to get post data, and then uses reddit's /api/info to get up-to-date information about those posts (scores, edited text bodies, ...). While we're at it, this also gives us the ability to speed up get_comments. In addition, we can get all of a user's comments which was not possible through reddit alone.

NOTE: Because Pushshift is an independent dataset run by a regular person, it does not contain posts from private subreddits. Without the timestamp search parameter, scanning private subreddits is now impossible. I urge once again that you contact your senator the admins to have this feature restored.

I don't have a test suite. You're my test suite! Messages go to /u/GoldenSights.

Timesearch is a collection of utilities for archiving subreddits.

Make sure you have:

  • Installed Python. I use Python 3.7.
  • Installed PRAW >= 4, as well as the other modules in requirements.txt. Try pip install -r requirements.txt to get them all.
  • Created an OAuth app at Make it script type, and set the redirect URI to http://localhost:8080. The title and description can be anything you want, and the about URL is not required.
  • Used this PRAW script to generate a refresh token. Just save it as a .py file somewhere and run it through your terminal / command line. For simplicity's sake, I just choose all for the scopes.
  • Downloaded a copy of this file and saved it as Fill out the variables using your OAuth information, and read the instructions to see where to put it. The Useragent is a description of your API usage. Typically "/u/username's praw client" is sufficient.
  • Downloaded this project using the green "Clone or Download" button in the upper right.

This package consists of:

  • get_submissions: If you try to page through /new on a subreddit, you'll hit a limit at or before 1,000 posts. Timesearch uses the dataset to get information about very old posts, and then queries the reddit api to update their information. Previously, we used the timestamp cloudsearch query parameter on reddit's own API, but reddit has removed that feature and pushshift is now the only viable source for initial data.
    python get_submissions -r subredditname <flags>
    python get_submissions -u username <flags>

  • get_comments: Similar to get_submissions, this tool queries pushshift for comment data and updates it from reddit.
    python get_comments -r subredditname <flags>
    python get_comments -u username <flags>

  • livestream: get_submissions+get_comments is great for starting your database and getting the historical posts, but it's not the best for staying up-to-date. Instead, livestream monitors /new and /comments to continuously ingest data.
    python livestream -r subredditname <flags>
    python livestream -u username <flags>

  • get_styles: Downloads the stylesheet and CSS images.
    python get_styles -r subredditname

  • get_wiki: Downloads the wiki pages, sidebar, etc. from /wiki/pages.
    python get_wiki -r subredditname

  • offline_reading: Renders comment threads into HTML via markdown.
    Note: I'm currently using the markdown library from pypi, and it doesn't do reddit's custom markdown like /r/ or /u/, obviously. So far I don't think anybody really uses o_r so I haven't invested much time into improving it.
    python offline_reading -r subredditname <flags>
    python offline_reading -u username <flags>

  • index: Generates plaintext or HTML lists of submissions, sorted by a property of your choosing. You can order by date, author, flair, etc. With the --offline parameter, you can make all the links point to the files you generated with offline_reading.
    python index -r subredditname <flags>
    python index -u username <flags>

  • breakdown: Produces a JSON file indicating which users make the most posts in a subreddit, or which subreddits a user posts in.
    python breakdown -r subredditname
    python breakdown -u username

  • merge_db: Copy all new data from one timesearch database into another. Useful for syncing or merging two scans of the same subreddit.
    python merge_db --from filepath/database1.db --to filepath/database2.db

To use it

When you download this project, the main file that you will execute is here in the root directory. It will load the appropriate module to run your command from the modules folder.

You can view a summarized version of all the help text by running, and you can view a specific help text by running a command with no arguments, like livestream, etc.

I recommend sqlitebrowser if you want to inspect the database yourself.


  • 2020 01 27

    • When I first created Timesearch, it was simply a collection of all the random scripts I had written to archive various things. And they tended to have wacky names like commentaugment and redmash. Well, since the timesearch toolkit is meant to be a singular cohesive package now I decided to finally rename everything. I believe I have aliased everything properly so the old names still work for backwards compat, except for the fact the modules folder is now called timesearch_modules which may break your import statements if you ever imported that on your own.
  • 2018 04 09

    • Integrated with Pushshift to restore timesearch functionality, speed up commentaugment, and get user comments.
  • 2017 11 13

    • Gave timesearch its own Github repository so that (1) it will be easier for people to download it and (2) it has a cleaner, more independent URL. voussoir/timesearch
  • 2017 11 05

    • Added a try-except inside livestream helper to prevent generator from terminating.
  • 2017 11 04

    • For timesearch, I switched from using my custom cloudsearch iterator to the one that comes with PRAW4+.
  • 2017 10 12

    • Added the mergedb utility for combining databases.
  • 2017 06 02

    • You can use commentaugment -s abcdef to get a particular thread even if you haven't scraped anything else from that subreddit. Previously -s only worked if the database already existed and you specified it via -r. Now it is inferred from the submission itself.
  • 2017 04 28

    • Complete restructure into package, started using PRAW4.
  • 2016 08 10

    • Started merging redmash and wrote its argparser
  • 2016 07 03

    • Improved docstring clarity.
  • 2016 07 02

    • Added livestream argparse
  • 2016 06 07

    • Offline_reading has been merged with the main timesearch file
    • get_all_posts renamed to timesearch
    • Timesearch parameter usermode renamed to username; maxupper renamed to upper.
    • Everything now accessible via commandline arguments. Read the docstring at the top of the file.
  • 2016 06 05

    • NEW DATABASE SCHEME. Submissions and comments now live in different tables like they should have all along. Submission table has two new columns for a little bit of commentaugment metadata. This allows commentaugment to only scan threads that are new.
    • You can use the script to convert old databases into new ones.
  • 2015 11 11

    • created which converts a timesearch database into a comment tree that can be rendered into HTML
  • 2015 09 07

    • fixed bug which allowed livestream to crash because bot.refresh() was outside of the try-catch.
  • 2015 08 19

    • fixed bug in which updatescores stopped iterating early if you had more than 100 comments in a row in the db
    • commentaugment has been completely merged into the file. you can use commentaugment_prompt() to input the parameters, or use the commentaugment() function directly.

I want to live in a future where everyone uses UTC and agrees on daylight savings.