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:
| Property | Description |
|---|---|
| item_id | The item’s unique id. |
| deleted | true if the item is deleted. |
| item_type | 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 | true if 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 expand is 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 pip installation of requirements-dev.txt:
pip install -r requirements-dev.txt
Testing
Run the test suite by running:
echo "0.0.0-dev" > version.txt
python setup.py develop
pytest tests
LICENSE
The mighty MIT license. Please check LICENSE for more details.
1 maintainer
Metadata
1 maintainer
Release files for haxor 1.2.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| haxor-1.2.4.tar.gz | 14.0 kB | Without provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| haxor-1.2.4-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 31.1 kB
Release files / haxor-1.2.4.tar.gz
| Download URL | haxor-1.2.4.tar.gz |
|---|---|
| Size | 14.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d55a36001a535de5b97284830ee815bfbcb4aed59cefd9f17643f5aeeb0ccf60
|
|
BLAKE2b-256 checksum How to use checksums |
a706a84ad7ab37f2bccf2a8430e64541c90ae633dfc6e852364052a27c64722c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.12.0
|
Release files / haxor-1.2.4-py3-none-any.whl
| Download URL | haxor-1.2.4-py3-none-any.whl |
|---|---|
| Size | 17.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
dc2a4929b34a85f26a117d55867da718b1268329c05ab8932c1df19e6bf4132f
|
|
BLAKE2b-256 checksum How to use checksums |
29c081c786882a7bd9ea62571b0c7b59f1e26c54058731561629381ab3cb0ab0
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/4.0.2 CPython/3.12.0
|
Security for haxor 1.2.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
