Skip to main content

Yet another object-based Hacker News API wrapper for Python.

Project description

a Hacker News API wrapper written in Python

Build Status Coverage Status


This was written with the goal of sticking close to the API in terms of naming and structure, but with the added benefits that come with using Python objects.


Use one of the following, depending on how your system is configured:

pip install hnpy
pip3 install hnpy
python3 -m pip install hnpy


Create an instance of the main class like this:

import hnpy

hn = hnpy.HackerNews()


If you know an item’s ID, you can access it like this:

post = hn.item(8863)

An Item can be one of five types: “job”, “story”, “comment”, “poll”, or “pollopt.” You can determine its type by accessing post.type.

Item objects are loaded lazily, meaning they only make network requests when information that they don’t already have is needed.

Items can be checked for equality against other Items or against the ID in int or str form.

Items have various attributes which depend on their type. You can use hasattr() to programmatically determine whether a certain Item has an attribute or not. More on attributes here. Attribute names in hnpy are copied from field names in the API.

Items have five special attributes:

Attribute name Explanation
content The “meat” of the Item — text, url, or title, with a fallback to an empty string if none exist.
link URL to access the Item.
parent Item that this one replies to (not always present).
poll Item of type poll that this one belongs to (only present on pollopt Items).
by User who created this Item.

The link and content attributes are noted here because the API does not directly provide them, so they are not documented elsewhere. The parent, poll and by attributes are noted because they contain fully-featured, lazily-loaded Items as opposed to just the IDs that the API responds with. The rest of an Items attributes are delivered in the same format that they are received from the API.

The attributes can be accessed like so:


Items also have 2 special methods which iterate and deliver Items. Each takes an optional limit= parameter which defaults to 25.

Method name Use
kids() Iterate over the comments that reply to this Item.
parts() Iterate over the options of this Item (only present on poll types).

The methods can be used like this:

for kid in
for opt in


You can use hnpy to view the following listings provided by Hacker News:

  • Top (this is the view shown on the homepage of Hacker News)
  • Best
  • New
  • Ask HN Stories
  • Show HN Stories
  • Job Stories

Just like the special methods of an Item, these methods of a HackerNews object take an optional limit= parameter. They iterate over the specified listing, yielding lazy Items as they go.


for post in

The method names are:

  • top()
  • best()
  • new()
  • ask()
  • show()
  • jobs()


A User can be created from a user’s name using the HackerNews.user() method:

user = hn.user('jl')

Besides the attributes noted in the Hacker News API documentation, Users contain the following attributes and methods:

Attribute/method name Purpose
link A URL to view the User’s profile online.
submitted() Iterate over Items created by the user, with optional limit= parameter.


The HackerNews object has a method updates() which returns an Updates object, which has iterating methods just like those of other objects (optional limit= parameter, objects yielded) which give the most recently changed item and profiles (more info here). Its two methods are items() and profiles().

The HackerNews object also has a method max_item() which returns a lazy version of the newest Item.


This package came originally from my A Bot project. It was adapted to support lazy loading of objects, and as a consequence has only four classes (HackerNews, Item, User, Updates), rather than having a class for every type of Item with a complex inheritance model. This version also supports Users and Updates, which the old version did not.

This package was inspired by the Python Reddit API Wrapper aka PRAW (docs/source) in its use of objects and iteration methods and limit= parameters.

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

hnpy-0.2.1.tar.gz (6.3 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page