Metadata-Version: 2.3
Name: hnx
Version: 0.5.1
Summary: Modern async Hacker News API client
Keywords: hackernews,hacker news,hn,algolia,firebase,async
Author: kavin
Author-email: kavin <kavin.srinivasan2@gmail.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: httpx>=0.28.1
Requires-Dist: pydantic>=2.13.4
Requires-Python: >=3.10
Project-URL: Homepage, https://github.com/kavin81/hnx
Project-URL: Issues, https://github.com/kavin81/hnx/issues
Project-URL: Repository, https://github.com/kavin81/hnx
Description-Content-Type: text/markdown

# 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](#features)
* [Installation](#installation)
* [Quick Start](#quick-start)
* [Documentation](#documentation)
* [License](#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

```bash
pip install hnx
```

### uv

```bash
uv add hnx
```

### Poetry

```bash
poetry add hnx
```

### Pipenv

```bash
pipenv install hnx
```

## Quick Start

### Fetch a Story

```python
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

```python
from hnx import HackerNews

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

        print(ids[:10])
```

### Fetch a Complete Thread

```python
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](LICENSE)
