I'm a developer

haxor

by avinassh

avinassh / haxor

Unofficial Python wrapper for official Hacker News API

128 Stars 28 Forks Last release: over 1 year ago (v1.2.2) MIT License 107 Commits 9 Releases

Available items

No Items, yet!

The developer of this repository has not created any items for sale yet. Need a bug fixed? Help with integration? A different license? Create a request here:

haxor

travis coverall version supported license

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 Queries


To 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 

expand
flag 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=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: 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 

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 | ----------- | ------------------------------------------------------------ | itemid | The item’s unique id. | deleted | 

true
if 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 | 
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:

python setup.py develop
pytest tests

LICENSE

The mighty MIT license. Please check 

LICENSE
for more details.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.