Skip to main content

Unofficial Python wrapper for Hacker News API

Project description

#haxor

[![travis](https://img.shields.io/travis/avinassh/haxor.svg)](http://travis-ci.org/avinassh/haxor)
[![coverall](https://img.shields.io/coveralls/avinassh/haxor.svg)](https://coveralls.io/r/avinassh/haxor?branch=master)
[![version](https://img.shields.io/pypi/v/haxor.svg)](https://pypi.python.org/pypi/haxor/)
[![supported](https://img.shields.io/pypi/pyversions/haxor.svg)](https://pypi.python.org/pypi/haxor/)
![license](https://img.shields.io/pypi/l/haxor.svg)

Unofficial Python wrapper for official Hacker News API.

Installation
============
```python
pip install haxor
```
Usage
=====

import and initialization:
```python
from hackernews import HackerNews
hn = HackerNews()
```
Get certain user info by user id (i.e. username on Hacker News)
```python
user = hn.get_user('pg')
# >>> user.user_id
# pg
# >>> user.karma
# 155040
```
Stories, comments, jobs, Ask HNs and even polls are just items and they
have unique item id. To get info of an item by item id:
```python
item = hn.get_item(8863)
# >>> item.title
# "My YC app: Dropbox - Throw away your USB drive"
# >>> item.type
# story
# >>> item.kids
# [ 8952, 9224, 8917, ...]
```
To get item ids of current top stories:
```python
top_story_ids = hn.top_stories()
# >>> top_story_ids
# [8432709, 8432616, 8433237, ...]
```
To get current largest item id:
```python
max_item = hn.get_max_item()
# >>> max_item
# 8433746
```
Examples
========

Get top 10 stories:
```python
for story_id in hn.top_stories(limit=10):
print hn.get_item(story_id)

# <hackernews.Item: 8432709 - Redis cluster, no longer vaporware>
# <hackernews.Item: 8432423 - Fluid Actuators from Disney Research Make Soft, Safe Robot Arms>
# <hackernews.Item: 8433237 - Is Capturing Carbon from the Air Practical?>
# ...
# ...
```
Find all the 'jobs' post from Top Stories:
```python
for story_id in hn.top_stories():
story = hn.get_item(story_id)
if story.item_type == 'job':
print story

# <hackernews.Item: 8437631 - Lever (YC S12) hiring JavaScript experts, realtime systems engineers, to scale DerbyJS>
# <hackernews.Item: 8437036 - Product Designer (employee #1) to Organize the World's Code – Blockspring (YC S14)>
# <hackernews.Item: 8436584 - Django and iOS Hackers Needed – fix healthcare with Drchrono>
# ...
# ...
```
Find Python jobs from monthly who is hiring thread:
```python
# Who is hiring
# https://news.ycombinator.com/item?id=8394339

who_is_hiring = hn.get_item(8394339)

for comment_id in who_is_hiring.kids:
comment = hn.get_item(comment_id)
if 'python' in comment.text.lower():
print comment.item_id

# 8395568
# 8394964
# ...
# ...
```
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


`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


`top_stories`
-------------

Description: Returns list of item ids of current top stories

**Parameters:**

| Name | Type | Required | Description | Default
| --------- | ----- | --------- | ------------------------------------- | --------
| `limit` | int | No | specifies the number of stories to be returned | None


`new_stories`
-------------

Description: Returns list of item ids of current new stories

**Parameters:**

| Name | Type | Required | Description | Default
| --------- | ----- | --------- | ------------------------------------- | --------
| `limit` | int | No | specifies the number of stories to be returned | None


`ask_stories`
-------------

Description: Returns list of item ids of latest Ask HN stories

**Parameters:**

| Name | Type | Required | Description | Default
| --------- | ----- | --------- | ------------------------------------- | --------
| `limit` | int | No | specifies the number of stories to be returned | None


`show_stories`
-------------

Description: Returns list of item ids of latest Show HN stories

**Parameters:**

| Name | Type | Required | Description | Default
| --------- | ----- | --------- | ------------------------------------- | --------
| `limit` | int | No | specifies the number of stories to be returned | None


`job_stories`
-------------

Description: Returns list of item ids of latest Job stories

**Parameters:**

| Name | Type | Required | Description | Default
| --------- | ----- | --------- | ------------------------------------- | --------
| `limit` | int | No | specifies the number of stories to be returned | None


`updates`
--------------

Description: Returns list of item ids and user ids that have been changed/updated recently.


`get_max_item`
--------------

Description: Returns current largest item id

Class: `Item`
=============

From [Official HackerNews
Item](https://github.com/HackerNews/API/blob/master/README.md#items):

| 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.
| 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.
| raw | original JSON response.


Class: `User`
=============

From [Official HackerNews
User](https://github.com/HackerNews/API/blob/master/README.md#users):

| 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.

Development
===========

For local development do `pip` installation of `requirements-dev.txt`:

pip install -r requirements-dev.txt

LICENSE
=======

The mighty MIT license. Please check `LICENSE` for more details.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

haxor-0.3.1.tar.gz (7.6 kB view hashes)

Uploaded Source

Built Distribution

haxor-0.3.1-py2-none-any.whl (25.5 kB view hashes)

Uploaded Python 2

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page