Introduction

Welcome to aiohn, a lightweight fully asyncronouse hacker news api wrapper offering usefull high level abstractions!

This project wraps around the official HN api.

Concepts

Sessions

The wrapper provides a aiohn.Session class intended to be used in any situation that requires more than one http request.

Sessions are a performance optimization for both the user and HN since they provide:

• A single aiohttp.ClientSession instance to conduct all http requests via
• client side request throttling since the HN API doesn’t actually have any ratelimiting logic

Models

Unless the user prefers to work with the HN API’s responses directly, the wrapper provides several classes that are constructed directly from raw API responses and produce clean Pythonic interfaces for OOP inspired API interactions.

There are two main types of models:

• Item models, these represent: stories, polls, comments, etc.
• User models, these represent HN users.

Ratelimits

The HN API does not officially provide any known ratelimits so the general consensus on usage is to use common sense.

Unfortunately we are human and prone to error and its far too easy to abuse endpoints even accidentally. This is why the wrapper provides virtual ratelimiting via client side request throttling.

What this actually means is that every request you make is scheduled separately in a queue that is steadilly bled at a fixed rate, currently the default bleeding period is once every 0.25 seconds which means that no matter what the session will not make more than four requests per second.

The bleeding rate is not fixed and can be manually configured via the bleeding_delay keyword argument of aiohn.Session.

Caching

Additonally caching middlewares are planned to be introduced in order to reduce overall network roundtrips.