haxor

Unofficial Python wrapper for official Hacker News API.

Installation

pip install haxor

Usage

Import and initialization:

from hackernews import HackerNews
hn = HackerNews()

Items

Stories, comments, jobs, Ask HNs and even polls are just items with unique item id.

To query item information by id:

item = hn.get_item(8863)
# >>> item.title
# 'My YC app: Dropbox - Throw away your USB drive'
# >>> item.item_type
# 'story'
# >>> item.kids
# [ 8952, 9224, 8917, ...]

Since most results are returned as integer IDs (like item.kids above), these results require further iteration. Instead of doing this yourself, use the expand flag to get object-oriented, detailed item info by id:

item = hn.get_item(8863, expand=True)
# >>> item.kids
# [<hackernews.Item: 9224 - None>, <hackernews.Item: 8952 - None>, ...]
# >>> item.by
# <hackernews.User: dhouston>

To query a list of Item IDs:

items = hn.get_items_by_ids([8863, 37236, 2345])
# >>> items
# [<hackernews.Item: 8863 - My YC app: Dropbox - Throw away your USB drive>, <hackernews.Item:
# 37236 - None>, <hackernews.Item: 2345 - The Best Buy Scam.>]

Use the item_type filter to specifically select 'story', 'comment', 'job', or 'poll' items:

items = hn.get_items_by_ids([8863, 37236, 2345], item_type='story')
# >>> items
# [<hackernews.Item: 8863 - My YC app: Dropbox - Throw away your USB drive>, <hackernews.Item: # 2345 - The Best Buy Scam.>]

Stories

The HN API allows for real-time querying for New, Top, Best, Ask HN, Show HN, and Jobs stories.

As an example, to get Item objects of current top stories:

top_stories = hn.top_stories()
# >>> top_stories
# [<hackernews.Item: 16924667 - Ethereum Sharding FAQ>, ...]

Useful Item Queries

To get current largest Item id (most recent story, comment, job, or poll):

max_item = hn.get_max_item()
# >>> max_item
# 16925673

Once again, use the expand flag to get an object-oriented, detailed Item representation:

max_item = hn.get_max_item(expand=True)
# >>> max_item
# <hackernews.Item: 16925673 - None>

To get the x most recent Items:

last_ten = hn.get_last(10)
# >>> last_ten
# [<hackernews.Item: 16925688 - Show HN: Eventbot – Group calendar for Slack teams>, ...]

Users

HN users are also queryable.

To query users by user_id (i.e. username on Hacker News):

user = hn.get_user('pg')
# >>> user.user_id
# 'pg'
# >>> user.karma
# 155040

Use the expand flag to get an object-oriented, detailed Item representation for User attributes:

user = hn.get_user('dhouston', expand=True)
# >>> user.stories
# [<hackernews.Item: 1481914 - Dropbox is hiring a Web Engineer>, ...]
# >>> user.comments
# [<hackernews.Item: 16660140 - None>, <hackernews.Item: 15692914 - None>, ...]
# >>> user.jobs
# [<hackernews.Item: 3955262 - Dropbox seeking iOS and Android engineers>, ...]

To query a list of users:

users = hn.get_users_by_ids(['pg','dhouston'])
# >>> users
# [<hackernews.User: pg>, <hackernews.User: dhouston>]

Examples

Get top 10 stories:

hn.top_stories(limit=10)

# [<hackernews.Item: 16924667 - Ethereum Sharding FAQ>, <hackernews.Item: 16925499 - PipelineDB # v0.9.9 – One More Release Until PipelineDB Is a PostgreSQL Extension>, ...]

Find all the 'jobs' post from Top Stories:

stories = hn.top_stories()
for story in stories:
    if story.item_type == 'job':
        print(story)

# <hackernews.Item: 16925047 - Taplytics (YC W14) is solving hard engineering problems in
# Toronto and hiring>
# ...
# ...

Find Python jobs from monthly who is hiring thread:

# Who is hiring - April 2018
# https://news.ycombinator.com/item?id=16735011

who_is_hiring = hn.get_item(16735011, expand=True)

for comment in who_is_hiring.kids:
    if 'python' in comment.text.lower():
        print(comment)

# <hackernews.Item: 16735358 - None>
# <hackernews.Item: 16737152 - None>
# ...
# ...

API Reference

Class: HackerNews

Parameters:

| Name | Type | Required | Description | Default | ---------- | ------ | --------- | ------------------------------------- | -------- | version | string | No | specifies Hacker News API version | v0

get_item

Description: Returns Item object

Parameters:

| Name | Type | Required | Description | Default | ---------- | --------- | -------- | ----------------------------------- | ------- | item_id | string/int| Yes | unique item id of Hacker News story, comment etc | None | expand | bool | No | flag to indicate whether to transform all IDs into objects | False

get_items_by_ids

Description: Returns list of Item objects

Parameters:

| Name | Type | Required | Description | Default | ---------- | --------- | -------- | ----------------------------------- | ------- | item_ids | list of string/int | Yes | unique item ids of Hacker News stories, comments etc | None | item_type | string | No | item type to filter results with | None

get_user

Description: Returns User object

Parameters:

| Name | Type | Required | Description | Default | ------------ | -------- | ---------- | ------------------------------- | --------- | user_id | string | Yes | unique user id of a Hacker News user | None | expand | bool | No | flag to indicate whether to transform all IDs into objects | False

get_users_by_ids

Description: Returns list of User objects

Parameters:

| Name | Type | Required | Description | Default | ------------ | -------- | ---------- | ------------------------------- | --------- | user_ids | list of string/int | Yes | unique user ids of Hacker News users | None

top_stories

Description: Returns list of Item objects of current top stories

Parameters:

| Name | Type | Required | Description | Default | --------- | ----- | --------- | ------------------------------------- | -------- | raw | bool | No | indicate whether to represent all objects in raw json | False | limit | int | No | specifies the number of stories to be returned | None

new_stories

Description: Returns list of Item objects of current new stories

Parameters:

| Name | Type | Required | Description | Default | --------- | ----- | --------- | ------------------------------------- | -------- | raw | bool | No | indicate whether to represent all objects in raw json | False | limit | int | No | specifies the number of stories to be returned | None

ask_stories

Description: Returns list of Item objects of latest Ask HN stories

Parameters:

| Name | Type | Required | Description | Default | --------- | ----- | --------- | ------------------------------------- | -------- | raw | bool | No | indicate whether to represent all objects in raw json | False | limit | int | No | specifies the number of stories to be returned | None

show_stories

Description: Returns list of Item objects of latest Show HN stories

Parameters:

| Name | Type | Required | Description | Default | --------- | ----- | --------- | ------------------------------------- | -------- | raw | bool | No | indicate whether to represent all objects in raw json | False | limit | int | No | specifies the number of stories to be returned | None

job_stories

Description: Returns list of Item objects of latest Job stories

Parameters:

| Name | Type | Required | Description | Default | --------- | ----- | --------- | ------------------------------------- | -------- | raw | bool | No | indicate whether to represent all objects in raw json | False | limit | int | No | specifies the number of stories to be returned | None

updates

Description: Returns list of Item and User objects that have been changed/updated recently.

Parameters: N/A

get_max_item

Description: Returns current largest item id or current largest Item object

Parameters:

| Name | Type | Required | Description | Default | ------------ | -------- | ---------- | ------------------------------- | --------- | expand | bool | No | flag to indicate whether to transform ID into object | False

get_all

Description: Returns all Item objects from HN

Parameters: N/A

get_last

Description: Returns list of num most recent Item objects

Parameters:

| Name | Type | Required | Description | Default | ------------ | -------- | ---------- | ------------------------------- | --------- | num | int | No | numbr of most recent records to pull from HN | 10

Class: Item

From [Official HackerNews Item](https://github.com/Ha