/HackerNewsAPI

Unofficial Python API for Hacker News. RESTful API at https://github.com/karan/HNify

Primary LanguagePythonMIT LicenseMIT

Hacker News API

Unofficial Python API for Hacker News.

Build Status Test Coverage Version Downloads
Build Status Coverage Status Latest Version Downloads

Features

  • Compatible with Python 2 (2.7+).
  • Supports 'top', 'news2','newest' and 'best' posts
  • Retrieve comments from posts (flat list for now) (story.get_comments())
  • Pagination support for comments
  • Handles external posts, self posts and job posts
  • Get post details for any post (Story.fromid(7024626))

Installation

$ pip install HackerNews

Usage

NOTE: Do not make a lot of requests in a short period of time. HN has it's own throttling system.

from hn import HN

hn = HN()

# print the first 2 pages of newest stories
for story in hn.get_stories(story_type='newest', limit=60):
    print(story.rank, story.title)

API Reference

Class: HN

Get stories from Hacker News

get_stories

Parameters:

Name Type Required Description Default
story_type string No Returns the stories from this page. One of (empty string), news2, newest, best (empty string) (top)
limit integer No Number of stories required from the given page. Cannot be more than 30. 30

Example:

from hn import HN
hn = HN()
hn.get_stories(story_type='newest', limit=10)

get_leaders

Parameters:

Name Type Required Description Default
limit integer No Number of top leaders to return 10

Example:

from hn import HN
hn = HN()

# get top 20 users of HN
hn.get_leaders(limit=20)

Class: Story

Each Story has the following properties

  • rank - the rank of story on the page (keep pagination in mind)
  • story_id - the story's id
  • title - the title of the story
  • is_self - true for self/job stories
  • link - the url it points to ('' for self posts)
  • domain - the domain of the link ('' for self posts)
  • points - the points/karma on the story
  • submitter - the user who submitted the story ('' for job posts)
  • submitter_profile - the above user's profile link (can be '')
  • published_time - the published time
  • num_comments - the number of comments a story has
  • comments_link - the link to the comments page

Make an object from the ID of a story

fromid

Parameters:

Name Type Required Description Default
item_id integer Yes Initializes an instance of Story for given item_id. Must be a valid story id.

Example:

from hn import Story
story = Story.fromid(6374031)
print story.title

Get a list of Comment's for this story

get_comments

Parameters:

Name Type Required Description Default

Example:

from hn import Story
story = Story.fromid(6374031)
comments = story.get_comments()

Class: Comment

Each Comment has the following properties

  • comment_id - the comment's item id
  • level - commen's nesting level
  • user - user's name who submitted the post
  • time_ago - time when it was submitted
  • body - text representation of comment (unformatted)
  • body_html - html of comment, may not be valid

Class: User

Each User has the following properties

  • username - user's profile name
  • date_created - when the profile was created
  • karma - user's e-points
  • avg - user's average karma per day

Examples

See my_test_bot.py

Tests

To run the tests locally just do:

$ chmod 777 runtests.sh
$ ./runtests.sh

To run individual tests,

$ python -m unittest tests.<module name>

The tests are ran on a local test server with predownloaded original responses.

Donations

If HackerNewsAPI has helped you in any way, and you'd like to help the developer, please consider donating.

- BTC: 19dLDL4ax7xRmMiGDAbkizh6WA6Yei2zP5

- Flattr: https://flattr.com/profile/thekarangoel

Contribute

If you want to add any new features, or improve existing ones, feel free to send a pull request!