avinassh/ haxor
About the developer
139 Stars 
31 Forks 
MIT License 
110 Commits 
4 Opened issues 
Description
Unofficial Python wrapper for official Hacker News API
Services available
Contributors list
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: ```python 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: ```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])
>>> items
[, <hackernews.Item:
37236 - None>, ]
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 # [, ]
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: ```python topstories = hn.topstories()
>>> top_stories
[, ...]
#### 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)
>>> max_item
To get the x most recent Items: ```python last_ten = hn.get_last(10) # >>> last_ten # [, ...]
Users
HN users are also queryable.
To query users by userid (i.e. username on Hacker News): ```python user = hn.getuser('pg')
>>> user.user_id
'pg'
>>> user.karma
155040
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'])
>>> users
[, ]
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)
<hackernews.Item: 16925047 - Taplytics (YC W14) is solving hard engineering problems in
Toronto and hiring>
...
...
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:>
API Reference
Class: 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
Class: 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.
Class: 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.
Development
For local development do
pipinstallation of
requirements-dev.txt:
pip install -r requirements-dev.txt
Testing
Run the test suite by running:
python setup.py develop pytest tests
LICENSE
The mighty MIT license. Please check
LICENSEfor more details.