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.
from hn import search_by_date
from utils import output_results
results = search_by_date('python')
By default, all the different "post types" will be included: stories, comments, polls, etc.
output_results(results, 10)
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:
# 'pg' is Paul Graham: https://news.ycombinator.com/user?id=pg
results = search_by_date('lisp', 'pg')
output_results(results, 10)
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
.
results = search_by_date('python', stories=True)
output_results(results, 10)
Also filtering by author:
results = search_by_date('lisp', author='pg', stories=True)
output_results(results, 10)
Filtering by query, author and including both stories and comments:
results = search_by_date('lisp', author='pg', stories=True, comments=True)
output_results(results, 10)
Other examples:
results = search_by_date('lisp', author='pg', polls=True)
output_results(results, 10)
results = search_by_date('python', show_hn=True)
output_results(results, 10)
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 optionsstory
,comment
,poll
,pollopt
,show_hn
,ask_hn
,front_page
.Author
: receives the username as param (Author('pg')
).StoryID
: receives the story id (StoryID('6902129')
)
PostType
s also have aliases that can be used instead of writing the full tag.
from hn import PostType, Author, StoryID
from hn.tags import Story, Comment, AskHN, ShowHN
PostType('story') == Story
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 |
:
tags = PostType('ask_hn') | PostType('show_hn')
results = search_by_date('python', tags=tags)
output_results(results, 10)
Using aliases:
tags = AskHN | ShowHN
results = search_by_date('python', tags=tags)
output_results(results, 10)
To combine tags with an and
expression, the operator is &
. For example, all the posts that are comments of the story ID 7261591:
tags = PostType('comment') & StoryID('7261591')
results = search_by_date(tags=tags)
output_results(results, 10)
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. Exampleponts__lt=100
lte
(<=
): Lower than or equals to. Exampleponts__lte=100
gt
(>
): Greater than. Examplecreated_at__gt='2018'
(created after 2018-01-01).gte
(>=
): Greater than or equals to. Examplenum_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
).
results = search_by_date(stories=True, created_at__gt='2018-10')
output_results(results, 10)
Created after October 1st, 2017 and before January 1st 2018¶
results = search_by_date(stories=True, created_at__gt='2017-10', created_at__lt='2018')
output_results(results, 10)
A few more examples:¶
# Stories with *exactly* 1000 points
results = search_by_date(stories=True, points=1000)
output_results(results, 10)
# Stories including "Python" with more than 1000 points
results = search_by_date('python', stories=True, points__gt=1000)
output_results(results, 10)
# Comments with more than 50 points
results = search_by_date('python', comments=True, points__gt=50)
output_results(results, 10)
# Stories with 100 comments or more
results = search_by_date(stories=True, num_comments__gt=100)
output_results(results, 10)