
PRAW: The Python Reddit Api Wrapper
***********************************

PRAW, an acronym for "Python Reddit API Wrapper", is a python package
that allows for simple access to reddit's API. PRAW aims to be as easy
to use as possible and is designed to follow all of reddit's API
rules. You have to give a useragent that follows the rules, everything
else is handled by PRAW so you needn't worry about violating them.

Here's a quick peek, getting the first 5 submissions from the 'hot'
section of the 'opensource' subreddit:

   >>> import praw
   >>> r = praw.Reddit(user_agent='my_cool_application')
   >>> submissions = r.get_subreddit('opensource').get_hot(limit=5)
   >>> [str(x) for x in submissions]

This will display something similar to the following:

   ['10 :: Gun.io Debuts Group Funding for Open Source Projects\n Gun.io',
    '24 :: Support the Free Software Foundation',
    '67 :: The 10 Most Important Open Source Projects of 2011',
    '85 :: Plan 9 - A distributed OS with a unified communicatioprotocol  I/O...',
     '2 :: Open-source webOS is dead on arrival ']


Content Pages
=============

* Getting Started

* Writing a reddit Bot

* Comment Parsing

* PRAW and OAuth

* Lazy Objects

* Concurrent PRAW Instances

* Contributor Guidelines

* The Configuration Files

* Frequently Asked Questions

* Changelog

* Code Overview

* Useful Apps/Scripts

* Exceptions


References And Other Relevant Pages
===================================

* PRAW's Source Code

* reddit's Source Code

* reddit's API Wiki Page

* reddit's API Documentation

* reddit Markdown Primer

* reddit.com's FAQ

* reddit.com's Status Twitterbot. Tweets when reddit goes up or down

* r/changelog. Significant changes to reddit's codebase will be
  announced here in non-developer speak

* r/redditdev. Ask questions about reddit's codebase, PRAW and other
  API clients here


Installation
============

PRAW is supported on python 2.7, 3.3, 3.4 and 3.5. The recommended way
to install is via pip

   $ pip install praw

If you want to run the development version of PRAW try:

   $ pip install --upgrade https://github.com/praw-dev/praw/archive/master.zip

If you don't have "pip" installed, then the Hitchhiker's Guide to
Python has a section for setting it up on Windows, Mac and Linux.
There is also a Stack overflow question on installing pip on Windows
that might prove helpful.

Alternatively you can do it via easy_install

   $ easy_install praw


Support
=======

The official place to ask questions about PRAW, reddit and other API
wrappers is r/redditdev. If the question is more about Python and less
about PRAW, such as "what are generators", then you're likely to get
more, faster and more in-depth answers in r/learnpython.

If you've uncovered a bug or have a feature request, then make an
issue on our project page at github.

Please note that this project is released with a Contributor Code of
Conduct. By participating in this project you agree to abide by its
terms.


License
=======

All of the code contained here is licensed by the GNU GPLv3.


A Few Short Examples
====================

Note: These example are intended to be completed in order. While you
are free to skip down to what you want to accomplish, please check the
previous examples for any "NameErrors" you might encounter.

1. Import the package

   >>> import praw

2. Create the Reddit object (requires a user-agent):

   >>> r = praw.Reddit(user_agent='Test Script by /u/bboe')

3. Logging in:

   >>> r.login('username', 'password')

4. Send a message (requires login):

   >>> r.send_message('user', 'Subject Line', 'You are awesome!')

5. Mark all unread messages as read (requires login):

   >>> for msg in r.get_unread(limit=None):
   ...     msg.mark_as_read()

6. Get the top submissions for /r/python:

   >>> submissions = r.get_subreddit('python').get_top(limit=10)

7. Get comments from a given submission:

   >>> submission = next(submissions)
   >>> submission.comments

8. Comment on a submission (requires login):

   >>> submission.add_comment('text')

9. Reply to a comment (requires login):

   >>> comment = submission.comments[0]
   >>> comment.reply('test')

10. Voting (requires login):

    >>> # item can be a comment or submission
    >>> item.upvote()
    >>> item.downvote()
    >>> item.clear_vote()

11. Deleting (requires login):

    >>> # item can be a comment or submission
    >>> item.delete()

12. Saving a submission (requires login):

    >>> submission.save()
    >>> submission.unsave()

13. Create a SELF submission (requires login):

    >>> r.submit('reddit_api_test', 'submission title', text='body')

14. Create a URL submission (requires login):

    >>> r.submit('reddit_api_test', 'Google!', url='http://google.com')

15. Get user karma:

    >>> user = r.get_redditor('ketralnis')
    >>> user.link_karma
    >>> user.comment_karma

16. Get saved links (requires login):

    >>> r.user.get_saved()

17. Get content newer than a comment or submission's id:

    >>> r.get_subreddit('python').get_top(limit=None,
                                          place_holder=submission.id)

18. (Un)subscribe to a subreddit (requires login):

    >>> r.get_subreddit('python').subscribe()
    >>> r.get_subreddit('python').unsubscribe()

19. (Un)friend a user:

    >>> r.get_redditor('ketralnis').friend()
    >>> r.get_redditor('ketralnis').unfriend()

20. Create a subreddit:

    >>> r.create_subreddit(short_title='MyIncredibleSubreddit',
    ...                        full_title='my Incredibly Cool Subreddit',
    ...                        description='It is incredible!')

21. Get flair mappings for a particular subreddit (requires mod
    privileges):

    >>> item = next(r.get_subreddit('python').get_flair_list())
    >>> item['user']
    >>> item['flair_text']
    >>> item['flair_css_class']

22. Set / update user flair (requires mod privileges):

    >>> r.get_subreddit('python').set_flair('user', 'text flair', 'css-class')

23. Clear user flair (requires mod privileges):

    >>> r.get_subreddit('python').set_flair('user')

24. Bulk set user flair (requires mod privileges):

    >>> flair_mapping = [{'user':'user', 'flair_text':'dev'},
    ...                  {'user':'pyapitestuser3', 'flair_css_class':'css2'},
    ...                  {'user':'pyapitestuser2', 'flair_text':'AWESOME',
    ...                  'flair_css_class':'css'}]
    >>> r.get_subreddit('python').set_flair_csv(flair_mapping)

25. Add flair templates (requires mod privileges):

    >>> r.get_subreddit('python').add_flair_template(text='editable',
    ...                                              css_class='foo',
    ...                                              text_editable=True)

26. Clear flair templates (requires mod privileges):

    >>> r.get_subreddit('python').clear_flair_templates()


Useful Scripts
**************

AutoModerator by Deimos
   A bot for automating straightforward reddit moderation tasks and
   improving upon the existing spam-filter.

ClockStalker
   Examines a redditor's posting history and creates a comment with a
   nice activity overview. ClockStalker uses an older version of PRAW,
   the "reddit", module. It should, but may not, work with the latest
   version of PRAW.

DailyProgBot
   A simple challenge-queue submission bot for r/DailyProgrammer.
   Users submit challenges through a Google Documents form, then the
   bot crawls said form, posting the appropriate challenge on the
   appropriate day of the week.
