Unofficial Python wrapper for official Hacker News API
Unofficial Python wrapper for official Hacker News API.
pip install haxor
from hackernews import HackerNews hn = HackerNews()
Stories, comments, jobs, Ask HNs and even polls are just items with unique item id.
To query item information by id: ```python item = hn.get_item(8863)
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: ```python item = hn.get_item(8863, expand=True) # >>> item.kids # [, , ...] # >>> item.by #
To query a list of Item IDs: ```python items = hn.getitemsby_ids([8863, 37236, 2345])
Use the `item_type` filter to specifically select 'story', 'comment', 'job', or 'poll' items: ```python items = hn.get_items_by_ids([8863, 37236, 2345], item_type='story') # >>> items # [, ]
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: ```python topstories = hn.topstories()
#### Useful Item QueriesTo get current largest Item id (most recent story, comment, job, or poll):
```python max_item = hn.get_max_item()
>>> max_item
16925673
Once again, use the
expandflag to get an object-oriented, detailed Item representation: ```python maxitem = hn.getmax_item(expand=True)
To get the x most recent Items: ```python last_ten = hn.get_last(10) # >>> last_ten # [, ...]
HN users are also queryable.
To query users by userid (i.e. username on Hacker News): ```python user = hn.getuser('pg')
Use the `expand` flag to get an object-oriented, detailed Item representation for User attributes: ```python user = hn.get_user('dhouston', expand=True) # >>> user.stories # [, ...] # >>> user.comments # [, , ...] # >>> user.jobs # [, ...]
To query a list of users: ```python users = hn.getusersby_ids(['pg','dhouston'])
Examples ========Get top 10 stories:
```python hn.top_stories(limit=10)
[<hackernews.item: ethereum sharding faq>, <hackernews.item: pipelinedb v0.9.9 one more release until is a postgresql extension>, ...]
</hackernews.item:></hackernews.item:>
Find all the 'jobs' post from Top Stories: ```python stories = hn.topstories() for story in stories: if story.itemtype == 'job': print(story)
Find Python jobs from monthly who is hiring thread: ```python # Who is hiring - April 2018 # https://news.ycombinator.com/item?id=16735011who_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: none>
<hackernews.item: none>
...
...
</hackernews.item:></hackernews.item:>
HackerNews
Parameters:
| Name | Type | Required | Description | Default | ---------- | ------ | --------- | ------------------------------------- | -------- |
version| string | No | specifies Hacker News API version |
v0
get_item
Description: Returns
Itemobject
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
Itemobjects
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
Userobject
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
Userobjects
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
Itemobjects 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
Itemobjects 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
Itemobjects 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
Itemobjects 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
Itemobjects 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
Itemand
Userobjects that have been changed/updated recently.
Parameters: N/A
get_max_item
Description: Returns current largest item id or current largest
Itemobject
Parameters:
| Name | Type | Required | Description | Default | ------------ | -------- | ---------- | ------------------------------- | --------- |
expand| bool | No | flag to indicate whether to transform ID into object | False
get_all
Description: Returns all
Itemobjects from HN
Parameters: N/A
get_last
Description: Returns list of
nummost recent
Itemobjects
Parameters:
| Name | Type | Required | Description | Default | ------------ | -------- | ---------- | ------------------------------- | --------- |
num| int | No | numbr of most recent records to pull from HN | 10
Item
From Official HackerNews Item:
| Property | Description | ----------- | ------------------------------------------------------------ | itemid | The item’s unique id. | deleted |
trueif the item is deleted. | itemtype | The type of item. One of “job”, “story”, “comment”, “poll”, or “pollopt”. | by | The username of the item’s author. | submission_time | Creation date of the item, in Python
datetime. | text | The comment, Ask HN, or poll text. HTML. | dead |
trueif the item is dead. | parent | The item’s parent. For comments, either another comment or the relevant story. For pollopts, the relevant poll. | poll | The ids of poll's. | kids | The ids of the item’s comments, in ranked display order. | url | The URL of the story. | score | The story’s score, or the votes for a pollopt. | title | The title of the story or poll. | parts | A list of related pollopts, in display order. | descendants | In the case of stories or polls, the total comment count. | raw | original JSON response.
User
From Official HackerNews User:
| Property | Description | --------- | ------------------------------------------------------------- | user_id | The user’s unique username. Case-sensitive. | delay | Delay in minutes between a comment’s creation and its visibility to other users. | created | Creation date of the user, in Python
datetime. | karma | The user’s karma. | about | The user’s optional self-description. HTML. | submitted | List of the user’s stories, polls and comments. | raw | original JSON response.
Additional properties when
expandis used
| Property | Description | ----------- | ------------------------------------------------------------ | stories | The user’s submitted stories. | comments | The user's submitted comments. | jobs | The user's submitted jobs. | polls | The user's submitted polls. | pollopts | The user's submitted poll options.
For local development do
pipinstallation of
requirements-dev.txt:
pip install -r requirements-dev.txt
Run the test suite by running:
python setup.py develop pytest tests
The mighty MIT license. Please check
LICENSEfor more details.