Unofficial Python API for Hacker News.
| Build Status | Test Coverage | 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 - comment'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 run 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!