Reddit::Client - A Perl wrapper for the Reddit API.
Up-to-date, nicely-formatted documentation can be found at http://redditclient.readthedocs.io. What follows is probably not incorrect, but is almost definitely not complete or current.
use Reddit::Client; my $client_id = "DFhtrhBgfhhRTd"; my $secret = "KrDNsbeffdbILOdgbgSvSBsbfFs"; my $username = "reddit_username"; my $password = "reddit_password"; # Create a Reddit::Client object and authorize in one step my $reddit = new Reddit::Client( user_agent => 'MyScriptName 1.0 by /u/myusername', client_id => $client_id, secret => $secret, username => $username, password => $password, ); # Or create object then authorize. # Useful if you need to switch between accounts, for example if you were to check the inboxes of several accounts. my $reddit = Reddit::Client->new( user_agent => 'MyApp/1.0 by /u/myusername', ); $reddit->get_token( client_id => $client_id, secret => $secret, username => $username, password => $password, ); # Check your inbox my $me = $reddit->me(); print "You've got mail!" if $me->{has_mail}; # Submit a link $reddit->submit_link( subreddit => 'test', title => 'Perl is still alive!', url => 'http://www.perl.org' ); # Submit a text post $reddit->submit_text( subreddit => 'test', title => 'my test', text => 'a test' ); # Get posts from a subreddit or multi my $posts = $reddit->fetch_links(subreddit=>'test', limit=>5); foreach my $post (@$posts) { print $post->{title} . "\n"; if (!$post->{is_self}) { # Is it a self post or a link? print $post->{url}; } else { print $post->{selftext}; } } # Get comments from a subreddit or multi my $cmts = $reddit->get_subreddit_comments('test'); foreach my $cmt (@$cmts) { print "$cmt->{author} says: $cmt->{body}\n"; }
Reddit::Client provides methods and object wrappers for objects exposed . This module handles HTTP communication, oauth session management, and communication with Reddit's external API. For more information about the Reddit API, see https://github.com/reddit/reddit/wiki/API.
Beginning August 3rd, 2015, the Reddit API requires Oauth authentication. This amounts to two extra arguments at the beginning of your script; in exchange you you twice as many requests per minute as before (60 vs 30) and some added convenience on the back end.
To get Oauth keys, visit your apps page: https://www.reddit.com/prefs/apps. Choose a "script" type app. None of the other fields are needed for a script type app; you can put in 127.0.0.1 for the URLs or whatever you like.
127.0.0.1
Every account that uses this script must have permission to use it. So for example if you were to check the inboxes of your various accounts, each one would need permission. To add accounts click "add developer" on the right, after you've created the app.
DEFAULT_LIMIT => 25 VIEW_HOT => '' VIEW_NEW => 'new' VIEW_CONTROVERSIAL => 'controversial' VIEW_TOP => 'top' VIEW_RISING => 'rising' VIEW_DEFAULT => VIEW_HOT VOTE_UP => 1 VOTE_DOWN => -1 VOTE_NONE => 0 SUBMIT_LINK => 'link' SUBMIT_SELF => 'self' SUBMIT_MESSAGE => 'message' MESSAGES_INBOX => 'inbox' MESSAGES_UNREAD => 'unread' MESSAGES_SENT => 'sent' MESSAGES_MESSAGES => 'messages' MESSAGES_COMMENTREPLIES => 'comments' MESSAGES_POSTREPLIES => 'selfreply' MESSAGES_MENTIONS => 'mentions' SUBREDDITS_HOME => '' SUBREDDITS_MINE => 'subscriber' SUBREDDITS_POPULAR => 'popular' SUBREDDITS_NEW => 'new' SUBREDDITS_CONTRIB => 'contributor' SUBREDDITS_MOD => 'moderator' USER_OVERVIEW => 'overview' USER_COMMENTS => 'comments' USER_SUBMITTED => 'submitted' USER_GILDED => 'gilded' USER_UPVOTED => 'upvoted' USER_DOWNVOTED => 'downvoted' USER_HIDDEN => 'hidden' USER_SAVED => 'saved'
These are the methods of the Reddit::Client class.
Two notes about methods that return lists of things:
1. All methods that return lists of things return them as a Perl list-- that is, a reference to an anonymous array. In practice this means that you get at the values with @$array instead of @array.
@$array
@array
2. All methods that return lists of things accept three optional parameters: limit, before, and after. You may recognize them from your address bar when viewing pages after the front page. limit defaults to 25 with a maximum of 100. (If limit is present but false, this is interpreted as "no limit" and the maximum is returned.) before and after limit results to those posted before before and after after.
comment ( $fullname, $text )
Make a comment under $fullname, which must be either a post or a comment. Return the fullname of the new comment.
This function is an alias for submit_comment, and is equivalent to
submit_comment
submit_comment ( parent_id => $fullname, text => $text )
create_multi ( name => $multi_name, [ description => $description, ] [ visibility => $visibility, ] [ subreddits => [ subreddits ], ] [ icon_name => $icon_name, ] [ key_color => $hex_code, ] [ weighting_scheme => $weighting_scheme, ] )
Create a multireddit. The only required argument is the name. A multi can also be created with edit_multi, the only difference being that create_multi will fail with a HTTP 409 error if a multi with that name already exists.
edit_multi
create_multi
Returns a hash of information about the newly created multireddit.
name The name of the multireddit. Maximum 50 characters. Only letters, numbers and underscores are allowed. Required.
description Description of the multi. This can contain markdown.
visibility One of 'private', 'public', or 'hidden'. Default 'private'.
subreddits or subs: An array reference.
The remaining arguments don't currently do anything. It seems like at least some of them are intended for future mobile updates.
icon_name If provided, must be one of the following values: 'art and design', 'ask', 'books', 'business', 'cars', 'comics', 'cute animals', 'diy', 'entertainment', 'food and drink', 'funny', 'games', 'grooming', 'health', 'life advice', 'military', 'models pinup', 'music', 'news', 'philosophy', 'pictures and gifs', 'science', 'shopping', 'sports', 'style', 'tech', 'travel', 'unusual stories', 'video', '', 'None'.
weighting_scheme If provided, must be either 'classic' or 'fresh'.
key_color A 6-character hex code. Defaults to CEE3F8.
delete ( $fullname )
Delete a post or comment.
delete_multi ( $multireddit_name )
Delete a multireddit.
Edit a multireddit. Will create a new multireddit if one with that name doesn't exist. The arguments are identical to create_multi.
edit_wiki ( subreddit => $subreddit, page => $page, content => $content, [ previous => $previous_version_number,] [ reason => $edit_reason, ] )
page is the page being edited.
content is the new page content. Can be empty but must be defined. Maximum 524,288 characters.
reason is the edit reason. Max 256 characters, will be truncated if longer. Optional.
previous is the ID of the intended previous version of the page; if provided, that is the version the page will be rolled back to in a rollback. However, there's no way to find out what this should be from the Reddit website, or currently from Reddit::Client either. Use it only if you know what you're doing. Optional.
find_subreddits ( q => $query, [ sort => 'relevance' ,] [ limit => DEFAULT_LIMIT ,] [ before => undef ,] [ after => undef ,] )
Returns a list of Subreddit objects matching the search string $query. Optionally sort them by sort, which can be "relevance" or "activity".
get_comment ( $fullname )
Returns a Comment object for $fullname.
get_flair_options( subreddit => $subreddit, post_id => $post_id_or_fullname, username => $username )
Get the flair options for either the post or the user provided.
Returns a hash containing two keys:
1. choices is an array of hash references containing the flair options. Most important is flair_template_id, which is used to set the flair of a post or user with set_post_flair or set_user_flair. flair_text contains the text of the flair.
set_post_flair
set_user_flair
2. current is a hash of the post or user's existing flair.
get_inbox ( [ view => MESSAGES_INBOX ,] [ limit => DEFAULT_LIMIT ,] [ before => undef ,] [ after => undef ,] )
Returns a list of Message objects, where view is one of the MESSAGE constants. All arguments are optional. If all are omitted your default inbox will be returned-- what you would see if you went to reddit.com and clicked the mailbox icon.
Checking your inbox via the API doesn't mark it as read. To do that you'll need to call mark_inbox_read: http://redditclient.readthedocs.org/en/latest/main-methods/#mark_inbox_read
mark_inbox_read
get_link ( $fullname )
Returns a Link object for $fullname.
get_links ( [ subreddit => undef ,] [ view => VIEW_DEFAULT ,] [ limit => DEFAULT_LIMIT ,] [ before => undef ,] [ after => undef ,] )
Returns a list of Link objects. All arguments are optional.
subreddit can be a subreddit or multi (ex: "pics+science"). If omitted, results from the user's front page will be returned-- i.e. what you would see if you visited reddit.com as that user.
view is a feed type constant-- i.e. VIEW_HOT, VIEW_NEW, etc.
fetch_links is an alias for get_links.
get_multi ( name => $multi_name, [ user => $username, ] [ expand => 0, ] )
Get a hash of information about a multireddit. $username defaults to your username.
If expand is true, returns more detailed information about the subreddits in the multi. This can be quite a bit of information, comparable to the amount of information contained in a Subreddit object, however it's not exactly the same, and if you try to create a Subreddit object out of it you'll fail.
get_permalink ( $comment_id, $post_id )
Returns a permalink for $comment_id. If you already have a Comment object, use its get_permalink function instead, ala $comment-get_permalink()>.
$comment-
This version causes an extra request because it has to ask Reddit for the parent post's URL first, while a Comment object already has that information. It's provided for backwards compatibility, and for the rare case when you may have a comment's ID but not a comment object (perhaps you have a list of IDs stored in a database). It may be deprecated in the future.
$comment_id and $post_id can be either fullnames or short IDs.
get_subreddit_comments ( [ subreddit => '' ,] [ view => VIEW_DEFAULT ,] [ limit => DEFAULT_LIMIT ,] [ before => undef ,] [ after => undef ,] )
Returns a list of Comment objects from a subreddit or multi.
All arguments are optional. If subreddit is omitted the account's "front page" subreddits are returned (i.e. what you see when you visit reddit.com and are logged in).
get_token ( client_id => $client_id, secret => $secret, username => $username, password => $password )
Get an Oauth token from Reddit. This is analogous to the old login function, and can be considered identical, with the exception that, if your script runs continuously for more than an hour, a new token will be obtained hourly.
get_user ( [ user => $username ,] [ view => USER_OVERVIEW ,] [ limit => DEFAULT_LIMIT ,][ before => undef ,] [ after => undef ,] )
Get information about a user, where view is one of the USER constants: overview, comments, submitted, gilded, upvoted, downvoted, hidden, or saved. Defaults to overview, which shows the user's most recent comments and posts.
Note that if you try to get the upvoted, downvoted, hidden, or saved activity for a user other than yourself, Reddit will return a 403 error, so be sure to wrap requests in a try/catch (http://redditclient.readthedocs.org/en/latest/examples/#catch-exceptions) if there's any chance that might happen. (Of course, all requests should be wrapped in a try/catch anyway, the internet being an unpredictable place.)
The result can be a list of Links, Comments, or a mix of both, depending on what view you requested. You can determine which is which by looking at the type property, which is "t1" for comments and "t3" for posts.
has_token()
Return true if a valid Oauth token exists.
hide ( $fullname )
Hide a post.
info ( $fullname )
Returns a hash of information about $fullname. $fullname can be any of the 8 types of thing.
list_subreddits ( [ view => SUBREDDITS_HOME ,] [ limit => DEFAULT_LIMIT ,] [ before => undef ,] [ after => undef ,] )
Returns a list of subreddits, where view is one of the SUBREDDIT constants.
An alias function is provided for each view type, which is the same as calling list_subreddits with the view already provided:
list_subreddits
contrib_subreddits ( [ limit = DEFAULT_LIMIT ,] [ before => undef ,] [ after => undef ,] )>
contrib_subreddits ( [ limit =
home_subreddits ( [ limit = DEFAULT_LIMIT ,] [ before => undef ,] [ after => undef ,] )>
home_subreddits ( [ limit =
mod_subreddits ( [ limit = DEFAULT_LIMIT ,] [ before => undef ,] [ after => undef ,] )>
mod_subreddits ( [ limit =
my_subreddits ( [ limit = DEFAULT_LIMIT ,] [ before => undef ,] [ after => undef ,] )>
my_subreddits ( [ limit =
new_subreddits ( [ limit = DEFAULT_LIMIT ,] [ before => undef ,] [ after => undef ,] )>
new_subreddits ( [ limit =
popular_subreddits ( [ limit = DEFAULT_LIMIT ,] [ before => undef ,] [ after => undef ,] )>
popular_subreddits ( [ limit =
mark_inbox_read()
Mark everything in your inbox as read. May take some time to complete.
me()
Return an Account object that contains information about the logged in account. Aside from static account information it contains the has_mail property, which will be true if there is anything in your inbox.
new ( user_agent => $user_agent, [ client_id => $client_id, secret => $secret, username => $username, password => $password ] )
Instantiate a Reddit::Client object. Optionally get an Oauth token (analogous to logging in) at the same time. If any of the four optional arguments are used, all are required.
$user_agent is always required, and should be something descriptive that uniquely identifies your app. The API Rules (https://github.com/reddit/reddit/wiki/API#rules) say it should be "something unique and descriptive, including the target platform, a unique application identifier, a version string, and your username as contact information".
It also includes this warning: "**NEVER lie about your user-agent.** This includes spoofing popular browsers and spoofing other bots. We will ban liars with extreme prejudice."
save ( $fullname )
Save a post or comment.
send_message ( to => $username, subject => $subject, text => $message )
Send a private message to $username. $subject is limited to 100 characters.
set_post_flair ( subreddit => $subreddit, post_id => $post_id_or_fullname, flair_template_id => $flair_id )
Set the flair on a post. The 'flair_template_id' is acquired via get_flair_options.
set_user_flair ( subreddit => $subreddit, username => $username, flair_template_id => $flair_id )
Set the flair for a user. The 'flair_template_id' is acquired via get_flair_options.
submit_comment ( parent_id => $fullname, text => $text)
Submit a comment under $fullname, which must be a post or comment. Returns fullname of the new comment.
submit_link ( subreddit => $subreddit, title => $title, url => $url, [ inbox_replies => 1, [repost => 0] )
Submit a link. Returns the fullname of the new post. If inbox_replies is defined and is false, disable inbox replies for that post. If repost is true, the link is allowed to be a repost. (Otherwise, if it is a repost, the request will fail with the error "That link has already been submitted".)
submit_text ( subreddit => $subreddit, title => $title, text => $text, [ inbox_replies => 1 ] )
Submit a text post. Returns the fullname of the new post. If inbox_replies is defined and is false, disable inbox replies for that post.
unhide ( $fullname )
Unhide a post.
unsave ( $fullname )
Unsave a post or comment.
version()
Return the Reddit::Client version.
vote ( $fullname, $direction )
Vote on a post or comment. Direction must be 1, 0, or -1 (0 to clear votes).
mailto:earthtone.rc@gmail.com
BSD license
To install Reddit::Client, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Reddit::Client
CPAN shell
perl -MCPAN -e shell install Reddit::Client
For more information on module installation, please visit the detailed CPAN module installation guide.