============ 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 :class:`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 :class:`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 :class:`aiohn.Session`. Caching ******* Additonally caching middlewares are planned to be introduced in order to reduce overall network roundtrips.