Python HN Library Interactive Docs

Version: 0.0.3

python-hn is a small library to access Hacker New's Search API powered by Algolia.

It's designed to be simple to use and pythonic, but also provide the full power of Search API.

This is an interactive documentation page, you can fork this project and start playing with it immediately using the Fork button to the right of this page 👉

Quick example¶

The main function of the library is search_by_date, which accepts multiple parameters; among them, is a query string containing the phrase to search for.

By default, all the different "post types" will be included: stories, comments, polls, etc.

As you can see, we're receiving both results for stories and comments.

Searching by author¶

The second parameter of the search_by_date function is the author's username of the post (story or comment). Example:

Filtering results by post type¶

You can pass multiple boolean parameters to filter the post types: stories, comments, show_hn, ask_hn, front_page, polls, pollopt.

Also filtering by author:

Filtering by query, author and including both stories and comments:

Other examples:

Tags¶

HN Search API supports "tags", that can be logically combined to create complex expressions. There are 3 types of tags included in python-hn:

• PostType: with options story, comment, poll, pollopt, show_hn, ask_hn, front_page.
• Author: receives the username as param (Author('pg')).
• StoryID: receives the story id (StoryID('6902129'))

PostTypes also have aliases that can be used instead of writing the full tag.

The power of the tags arise when we combine them logically with or and and expressions. For example, you could ask for posts that are either Ask HN or Show HN. To combine tags with an or expression, the operator is |:

Using aliases:

To combine tags with an and expression, the operator is &. For example, all the posts that are comments of the story ID 7261591:

Filtering by date, points or number of comments¶

It is also possible to pass different filters to restrain the search by creation date, number of points or comments. Namely, the parameters are:

• Creation Date: created_at
• Points: points
• Number of comments: num_comments

They accept >, <, >=, <= operators with a syntax similar to Django's:

• lt (<): Lower than. Example ponts__lt=100
• lte (<=): Lower than or equals to. Example ponts__lte=100
• gt (>): Greater than. Example created_at__gt='2018' (created after 2018-01-01).
• gte (>=): Greater than or equals to. Example num_comments__gte=50.

A few more examples using filters:

All post types created after October 1st, 2018¶

The filter is created_at__gt, gt is the > operator. The created_at filter will try to parse dates automatically (eg: 2018 is interpreted as 2018-01-01).

Created after October 1st, 2017 and before January 1st 2018¶

A few more examples:¶