hnx

Modern async Hacker News API client for Python.

hnx combines the Hacker News Firebase API & Algolia's search API to provide a unified, fully-typed interface for working with stories, comments, users, & discussion threads.

Table of Contents

• Features
• Installation
• Quick Start
• Documentation
• License

Features

• Async-first API built on httpx
• Fully typed Pydantic models combining data from both Algolia & Firebase APIs
• Individual and concurrent batch item retrieval

Installation

Requires Python 3.10 or higher.

pip

pip install hnx

uv

uv add hnx

Poetry

poetry add hnx

Pipenv

pipenv install hnx

Quick Start

Fetch a Story

from hnx import HackerNews

async def main():
    async with HackerNews() as hn:
        story = await hn.item(44321234)

        print(story.title)
        print(story.score)

Fetch Top Stories

from hnx import HackerNews

async def main():
    async with HackerNews() as hn:
        ids = await hn.top()

        print(ids[:10])

Fetch a Complete Thread

from hnx import HackerNews

async def main():
    async with HackerNews() as hn:
        thread = await hn.thread(44321234)

        print(thread.root.title)
        print(thread.comment_count)

        for comment in thread.comments:
            print(comment.author)

Documentation

Complete documentation, API reference, guides, and examples are available at:

https://kavin81.github.io/hnx

License

• MIT