After importing narwal,
>>> import narwal
you’ll always be starting with Reddit, by invoking either:
>>> session = narwal.Reddit(user_agent='hellonarwal')
>>> session = narwal.Reddit('username', 'password', user_agent='nice2meetu')
or
>>> session = narwal.connect(user_agent='hellonarwal')
>>> session = narwal.connect('username', 'password', user_agent='nice2meetu')
But really, connect() is the same as instantiating Reddit. I just think connect() makes more sense intuitively.
narwal defaults to respecting reddit’s rules of making at most only 1 request every 2 seconds and always supplying a useful User-Agent. That’s why if you try this:
>>> session = narwal.connect()
a ValueError will be raised complaining that you need to supply a user_agent. You can make narwal be disrespectful by setting respect=False when instantiating a new session:
>>> session = narwal.connect(respect=False)
But c’mon – be respectful.
Upon receiving a response from GET (and some POST) requests, narwal attempts to “thingify” the response content. Thingifying is simply wrapping the useful data as a things.Thing subclass, as defined by reddit here. Thingifying works recursively through the object, such that some data in a Thing may be another Thing. For example:
>>> page1 = session.hot() # Listing
>>> link = page1[0] # Link
>>> comments = link.comments() # Listing
>>> comment = comments[0] # Comment
>>> replies = comment.replies # Listing
>>> replies[0] # Comment
You can access all of narwal’s implemented reddit API calls through narwal.Reddit methods, but, as you can see in the examples, many of them are accessible through things’ methods for convenience.
A Reddit session.
Parameters: |
|
---|
Property. True if logged in.
Sends a GET request to a reddit path determined by args. Basically .get('foo', 'bar', 'baz') will GET http://www.reddit.com/foo/bar/baz/.json. kwargs supplied will be passed to requests.get() after having user_agent and cookies injected. Injection only occurs if they don’t already exist.
Returns things.Blob object or a subclass of things.Blob, or raises exceptions.BadResponse if not a 200 Response.
Parameters: |
|
---|
Sends a POST request to a reddit path determined by args. Basically .post('foo', 'bar', 'baz') will POST http://www.reddit.com/foo/bar/baz/.json. kwargs supplied will be passed to requests.post after having modhash and cookies injected, and after having modhash injected into kwargs['data'] if logged in. Injection only occurs if they don’t already exist.
Returns received response JSON content as a dict.
Raises exceptions.BadResponse if not a 200 response or no JSON content received or raises exceptions.PostError if a reddit error was returned.
Parameters: |
|
---|
Logs into reddit with supplied credentials using SSL. Returns requests.Response object, or raises exceptions.LoginFail or exceptions.BadResponse if not a 200 response.
URL: https://ssl.reddit.com/api/login
Parameters: |
|
---|
GETs a link by ID. Returns things.Link object.
URL: http://www.reddit.com/by_id/<id_>
Parameters: | id_ – full name of link |
---|
GETs hot links. If sr is None, gets from main. Returns things.Listing object.
URL: http://www.reddit.com/[r/<sr>]/?limit=<limit>
Parameters: |
|
---|
GETs new links. If sr is None, gets from main. Returns things.Listing object.
URL: http://www.reddit.com/[r/<sr>/]new/?limit=<limit>
Parameters: |
|
---|
GETs top links. If sr is None, gets from main. Returns things.Listing object.
URL: http://www.reddit.com/[r/<sr>/]top/?limit=<limit>
Parameters: |
|
---|
GETs controversial links. If sr is None, gets from main. Returns things.Listing object.
URL: http://www.reddit.com/[r/<sr>/]controversial/?limit=<limit>
Parameters: |
|
---|
GETs newest comments. If sr is None, gets all. Returns things.Listing object.
URL: http://www.reddit.com/[r/<sr>/]comments/?limit=<limit>
Parameters: |
|
---|
GETs user info. Returns things.Account object.
URL: http://www.reddit.com/user/<username>/about/
Parameters: | username – username of user |
---|
GETs subreddit info. Returns things.Subreddit object.
URL: http://www.reddit.com/r/<sr>/about/
Parameters: | sr – subreddit name |
---|
GETs “info” about url. See https://github.com/reddit/reddit/wiki/API%3A-info.json.
URL: http://www.reddit.com/api/info/?url=<url>
Parameters: |
|
---|
Use reddit’s search function. Returns things.Listing object.
URL: http://www.reddit.com/search/?q=<query>&limit=<limit>
Parameters: |
|
---|
GETs links from domain_. Returns things.Listing object.
URL: http://www.reddit.com/domain/?domain=<domain_>&limit=<limit>
Parameters: |
|
---|
GETs a user’s posted comments. Returns things.Listing object.
Parameters: |
|
---|
GETs a user’s posted comments. Returns things.Listing object.
Parameters: |
|
---|
GETs a user’s submissions. Returns things.Listing object.
Parameters: |
|
---|
GETs moderators of subreddit sr. Returns things.ListBlob object.
NOTE: The things.Account objects in the returned ListBlob only have id and name set. This is because that’s all reddit returns. If you need full info on each moderator, you must individually GET them using user() or things.Account.about().
URL: http://www.reddit.com/r/<sr>/about/moderators/
Parameters: | sr – name of subreddit |
---|
Login required. GETs info about logged in user. Returns :class`things.Account` object.
See https://github.com/reddit/reddit/wiki/API%3A-mine.json.
URL: http://www.reddit.com/api/me/
Login required. GETs logged in user’s subreddits. Returns things.Listing object.
See https://github.com/reddit/reddit/wiki/API%3A-mine.json.
URL: http://www.reddit.com/reddits/mine[/(subscriber|contributor|moderator)]?limit=<limit>
Parameters: |
|
---|
Login required. GETs logged in user’s saved submissions. Returns things.Listing object.
URL: http://www.reddit.com/saved/
Parameters: | limit – max number of submissions to get |
---|
Login required. POSTs a vote. Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
See https://github.com/reddit/reddit/wiki/API%3A-vote.
URL: http://www.reddit.com/api/vote/
Parameters: |
|
---|
Login required. POSTs an upvote (1). Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
See https://github.com/reddit/reddit/wiki/API%3A-vote.
URL: http://www.reddit.com/api/vote/
Parameters: | id_ – full id of object voting on |
---|
Login required. POSTs a downvote (-1). Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
See https://github.com/reddit/reddit/wiki/API%3A-vote.
URL: http://www.reddit.com/api/vote/
Parameters: | id_ – full id of object voting on |
---|
Login required. POSTs a null vote (0). Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
See https://github.com/reddit/reddit/wiki/API%3A-vote.
URL: http://www.reddit.com/api/vote/
Parameters: | id_ – full id of object voting on |
---|
Login required. POSTs a comment in response to parent. Returns things.Comment object.
See https://github.com/reddit/reddit/wiki/API%3A-comment.
URL: http://www.reddit.com/api/comment/
Parameters: |
|
---|
Login required. Sends POST to change selftext or comment text to text. Returns things.Comment or things.Link object depending on what’s being edited. Raises UnexpectedResponse if neither is returned.
URL: http://www.reddit.com/api/editusertext/
Parameters: |
|
---|
Login required. POSTs a link submission. Returns things.Link object if follow=True (default), or the string permalink of the new submission otherwise.
Argument follow exists because reddit only returns the permalink after POSTing a submission. In order to get detailed info on the new submission, we need to make another request. If you don’t want to make that additional request, just set follow=False.
See https://github.com/reddit/reddit/wiki/API%3A-submit.
URL: http://www.reddit.com/api/submit/
Parameters: |
|
---|
Login required. POSTs a text submission. Returns things.Link object if follow=True (default), or the string permalink of the new submission otherwise.
Argument follow exists because reddit only returns the permalink after POSTing a submission. In order to get detailed info on the new submission, we need to make another request. If you don’t want to make that additional request, set follow=False.
See https://github.com/reddit/reddit/wiki/API%3A-submit.
URL: http://www.reddit.com/api/submit/
Parameters: |
|
---|
Login required. Send POST to delete an object. Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
URL: http://www.reddit.com/api/del/
Parameters: | id_ – full id of object to delete |
---|
Login required. Sends POST to save a link. Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
See https://github.com/reddit/reddit/wiki/API%3A-save.
URL: http://www.reddit.com/api/save/
Parameters: | id_ – full id of link to save |
---|
Login required. Sends POST to unsave a link. Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
See https://github.com/reddit/reddit/wiki/API%3A-unsave.
URL: http://www.reddit.com/api/unsave/
Parameters: | id_ – full id of link to unsave |
---|
Login required. Sends POST to hide a link. Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
See https://github.com/reddit/reddit/wiki/API%3A-hide.
URL: http://www.reddit.com/api/hide/
Parameters: | id_ – full id of link to hide |
---|
Login required. Sends POST to unhide a link. Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
See https://github.com/reddit/reddit/wiki/API%3A-unhide.
URL: http://www.reddit.com/api/unhide/
Parameters: | id_ – full id of link to unhide |
---|
Login required. Sends POST to mark link as NSFW. Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
URL: http://www.reddit.com/api/marknsfw/
Parameters: | id_ – full id of link to mark |
---|
Login required. Sends POST to unmark link as NSFW. Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
URL: http://www.reddit.com/api/unmarknsfw/
Parameters: | id_ – full id of link to unmark |
---|
Login required. Sends POST to report a link. Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
URL: http://www.reddit.com/api/report/
Parameters: | id_ – full id of link to report |
---|
Login required. Sends POST to send a message to a user. Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
URL: http://www.reddit.com/api/compose/
Parameters: |
|
---|
Login required. Send POST to mark a message as read. Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
URL: http://www.reddit.com/api/read_message/
Parameters: | id_ – full id of message to mark |
---|
Login required. Send POST to unmark a message as read. Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
URL: http://www.reddit.com/api/unread_message/
Parameters: | id_ – full id of message to unmark |
---|
Login required. Send POST to subscribe to a subreddit. If sr is the name of the subreddit, a GET request is sent to retrieve the full id of the subreddit, which is necessary for this API call. Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
URL: http://www.reddit.com/api/subscribe/
Parameters: | sr – full id of subreddit or name of subreddit (full id is preferred) |
---|
Login required. Send POST to unsubscribe to a subreddit. If sr is the name of the subreddit, a GET request is sent to retrieve the full id of the subreddit, which is necessary for this API call. Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
URL: http://www.reddit.com/api/unsubscribe/
Parameters: | sr – full id of subreddit or name of subreddit (full id is preferred) |
---|
Login required. GETs logged in user’s inbox. Returns things.Listing object.
URL: http://www.reddit.com/message/inbox/
Parameters: | limit – max number of objects to get |
---|
Login required. GETs logged in user’s unread. Returns things.Listing object.
URL: http://www.reddit.com/message/unread/
Parameters: | limit – max number of objects to get |
---|
Login required. GETs logged in user’s messages. Returns things.Listing object.
URL: http://www.reddit.com/message/messages/
Parameters: | limit – max number of messages to get |
---|
Login required. GETs logged in user’s comment replies. Returns things.Listing object.
URL: http://www.reddit.com/message/comments/
Parameters: | limit – max number of comment replies to get |
---|
Login required. GETs logged in user’s post replies. Returns things.Listing object.
URL: http://www.reddit.com/message/selfreply/
Parameters: | limit – max number of post replies to get |
---|
Login required. GETs logged in user’s sent messages. Returns things.Listing object.
URL: http://www.reddit.com/message/sent/
Parameters: | limit – max number of messages to get |
---|
Login required. GETs logged in user’s modmail. Returns things.Listing object.
URL: http://www.reddit.com/message/moderator/
Parameters: | limit – max number of messages to get |
---|
GETs logged-in user’s liked submissions. Returns things.Listing object.
Parameters: | limit – max number of submissions to get |
---|
GETs logged-in user’s disliked submissions. Returns things.Listing object.
Parameters: | limit – max number of submissions to get |
---|
GETs logged-in user’s hidden submissions. Returns things.Listing object.
Parameters: | limit – max number of submissions to get |
---|
Login required. Sends POST to approve a submission. Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
URL: http://www.reddit.com/api/approve/
Parameters: | id_ – full id of submission to approve |
---|
Login required. Sends POST to remove a submission or comment. Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
URL: http://www.reddit.com/api/remove/
Parameters: | id_ – full id of object to remove |
---|
Login required. Sends POST to distinguish a submission or comment. Returns things.Link or things.Comment, or raises exceptions.UnexpectedResponse otherwise.
URL: http://www.reddit.com/api/distinguish/
Parameters: |
|
---|
Login required. Gets flairlist for subreddit r. See https://github.com/reddit/reddit/wiki/API%3A-flairlist.
However, the wiki docs are wrong (as of 2012/5/4). Returns things.ListBlob of things.Blob objects, each object being a mapping with user, flair_css_class, and flair_text attributes.
URL: http://www.reddit.com/r/<r>/api/flairlist
Parameters: |
|
---|
Login required. Sets flair for a user. See https://github.com/reddit/reddit/wiki/API%3A-flair. Returns True or raises exceptions.UnexpectedResponse if non-“truthy” value in response.
URL: http://www.reddit.com/api/flair
Parameters: |
|
---|
Login required. Bulk sets flair for users. See https://github.com/reddit/reddit/wiki/API%3A-flaircsv/. Returns response JSON content as dict.
URL: http://www.reddit.com/api/flaircsv
Parameters: |
|
---|
Login required. GETs list of contributors to subreddit sr. Returns things.ListBlob object.
NOTE: The things.Account objects in the returned ListBlob only have id and name set. This is because that’s all reddit returns. If you need full info on each contributor, you must individually GET them using user() or things.Account.about().
URL: http://www.reddit.com/r/<sr>/about/contributors/
Parameters: | sr – name of subreddit |
---|
Bases: object
A dumb container because obj.x is cooler then obj['x'].
Parameters: | reddit (Reddit) – a reddit session |
---|
Bases: narwal.things.Blob
A Blob that almost looks and feels like a list, but isn’t.
Parameters: |
|
---|
Bases: narwal.things.Blob
A reddit Thing. See https://github.com/reddit/reddit/wiki/thing for more details. You will only be seeing instances of subclasses of this.
kind is omitted because it will be implied by Thing‘s subclasses. data is omitted because data will be stored as attributes.
Bases: narwal.things.Thing
An implementation. See https://github.com/reddit/reddit/wiki/thing for more details.
Bases: narwal.things.Thing
An implementation. See https://github.com/reddit/reddit/wiki/thing for more details.
POST a vote on the thing. Calls narwal.Reddit.vote().
Parameters: | dir_ – direction (up: 1, down: -1, no vote: 0) |
---|
Upvote the thing (POST). Calls Votable.vote().
Downvote the thing (POST). Calls Votable.vote().
Unvote the thing (POST). Calls Votable.vote().
Bases: narwal.things.Thing
Base class for Thing objects that are commentable (i.e. Link and Comment).
POST a comment to this thing. Calls narwal.Reddit.comment().
Parameters: | text – comment’s body text |
---|
Edits this thing (POST). Calls narwal.Reddit.edit().
Parameters: | text – new text |
---|
GETs comments to this thing.
Parameters: | limit – max number of comments to return |
---|
Distinguishes this thing (POST). Calls narwal.Reddit.distinguish().
Parameters: | how – either True, False, or ‘admin’ |
---|
Deletes this thing (POST). Calls narwal.Reddit.delete().
Removes this thing (POST). Calls narwal.Reddit.remove().
Bases: narwal.things.Thing
Base class for Thing objects that are hideable (i.e. Link and Message).
Hides this thing (POST). Calls narwal.Reddit.hide().
Hides this thing (POST). Calls narwal.Reddit.unhide().
Bases: narwal.things.Thing
Base class for Thing objects that are reportable (i.e. Link, Comment, and Message).
Reports this thing (POST). Calls narwal.Reddit.report().
Bases: narwal.things.ListBlob
A reddit Listing. See https://github.com/reddit/reddit/wiki/thing for more details.
data is omitted because data will be stored as attributes.
Property that aliases self.children to self._items. This is done so that ListBlob special methods work automagically.
Returns True if there are more things that can be retrieved.
A convenience function. Calls self.next_listing.
Bases: narwal.things.Votable, narwal.things.Created, narwal.things.Commentable, narwal.things.Reportable
A reddit Comment. See https://github.com/reddit/reddit/wiki/thing for more details.
Property. Returns permalink as relative path.
POSTs a comment in reply to this one. Calls Commentable.comment().
Parameters: | text – comment body text |
---|
Bases: narwal.things.Votable, narwal.things.Created, narwal.things.Commentable, narwal.things.Hideable, narwal.things.Reportable
A reddit Link. See https://github.com/reddit/reddit/wiki/thing for more details.
Saves this link (POST). Calls narwal.Reddit.save().
Unsaves this link (POST). Calls narwal.Reddit.unsave().
Marks link as nsfw (POST). Calls narwal.Reddit.marknsfw().
Marks link as nsfw (POST). Calls narwal.Reddit.unmarknsfw().
Approves this link (POST). Calls narwal.Reddit.approve().
Bases: narwal.things.Thing
A reddit Submission. See https://github.com/reddit/reddit/wiki/thing for more details.
GETs hot links from this subreddit. Calls narwal.Reddit.hot().
Parameters: | limit – max number of links to return |
---|
GETs new links from this subreddit. Calls narwal.Reddit.new().
Parameters: | limit – max number of links to return |
---|
GETs top links from this subreddit. Calls narwal.Reddit.top().
Parameters: | limit – max number of links to return |
---|
GETs controversial links from this subreddit. Calls narwal.Reddit.controversial().
Parameters: | limit – max number of links to return |
---|
GETs newest comments from this subreddit. Calls narwal.Reddit.comments().
Parameters: | limit – max number of links to return |
---|
Subscribe to this subreddit (POST). Calls narwal.Reddit.subscribe().
Unsubscribe to this subreddit (POST). Calls narwal.Reddit.unsubscribe().
Submit link to this subreddit (POST). Calls narwal.Reddit.submit_link().
Parameters: |
|
---|
Submit self text submission to this subreddit (POST). Calls narwal.Reddit.submit_text().
Parameters: |
|
---|
GETs moderators for this subreddit. Calls narwal.Reddit.moderators().
Parameters: | limit – max number of items to return |
---|
Sets flair for user in this subreddit (POST). Calls narwal.Reddit.flairlist().
Parameters: |
|
---|
GETs flairlist for this subreddit. Calls narwal.Reddit.flairlist().
Parameters: |
|
---|
Bulk sets flair for users in this subreddit (POST). Calls narwal.Reddit.flaircsv().
Parameters: | flair_csv – CSV string |
---|
GETs contributors for this subreddit. Calls narwal.Reddit.contributors().
Parameters: | limit – max number of items to return |
---|
Bases: narwal.things.Created, narwal.things.Hideable, narwal.things.Reportable
A reddit Message. See https://github.com/reddit/reddit/wiki/thing for more details.
Marks message as read (POST). Calls narwal.Reddit.read_message().
Marks message as unread (POST). Calls narwal.Reddit.unread_message().
POSTs reply to message with own message. Returns posted message.
URL: http://www.reddit.com/api/comment/
Parameters: | text – body text of message |
---|
Bases: narwal.things.Thing
A reddit Account. See https://github.com/reddit/reddit/wiki/thing for more details.
GETs overview of user’s activities. Calls narwal.Reddit.user_overview().
Parameters: | limit – max number of items to get |
---|
GETs user’s comments. Calls narwal.Reddit.user_comments().
Parameters: | limit – max number of comments to get |
---|
GETs user’s submissions. Calls narwal.Reddit.user_submitted().
Parameters: | limit – max number of submissions to get |
---|
GETs this user (again). Calls narwal.Reddit.user().
Compose a message to this user. Calls narwal.Reddit.compose().
Parameters: |
|
---|
Bases: narwal.things.Thing
A reddit More. See https://github.com/reddit/reddit/wiki/thing for more details.
Bases: exceptions.Exception
Generic exception
Bases: narwal.exceptions.AlienException
Unable to login for whatever reason (bad user/password combo, no response, etc.)
Bases: narwal.exceptions.AlienException
Need to be logged in to call
Bases: narwal.exceptions.AlienException
Can’t get next/prev items of a Listing
Bases: narwal.exceptions.AlienException
Currently unsupported API feature
Bases: narwal.exceptions.AlienException
Response containing reddit errors in response.
list of string reddit errors received in response
Bases: narwal.exceptions.AlienException
A non-200 response.
the requests.Response object returned
Bases: narwal.exceptions.AlienException
A 200 response with unexpected content.
the json dict returned