API

Session

class aiohn.Session(session: Optional[aiohttp.client.ClientSession] = None, *, loop: Optional[asyncio.events.AbstractEventLoop] = None, bleeding_delay: float = 0.25)

A http session used to make api requests.

It’s recommended to always use a Session object and share it across as many api requests as possible. This is because currently, at the time of writing, the HN api has no form of ratelimiting. So we implement client side ratelimiting so we dont absolutely demolish their endpoints.

Parameters:
fetch(url: str) → Dict[str, Union[str, int, List[int]]]

Fetch raw json from the api.

Note

This method applies virtual ratelimiting as the HN firebase api does not supply any.

Parameters:url (str) – The url to fetch.
fetch_item(ident: Union[str, int]) → Dict[str, Union[str, int, List[int]]]

Fetch a raw item object from HN.

Parameters:ident (Union[str, int]) – The identifier to use.
Returns:item – The item.
Return type:ApiResponse
fetch_maxitem() → Dict[str, Union[str, int, List[int]]]

Fetch the current maxitem id.

Returns:maxitem – The current maxitem.
Return type:ApiResponse
fetch_maxitem_id() → int

Fetch the current maxitem id.

Returns:maxitem – The current maxitem id.
Return type:ApiResponse
fetch_user(ident: Union[str, int]) → Dict[str, Union[str, int, List[int]]]

Fetch a raw user object from HN.

Parameters:ident (Union[str, int]) – The identifier to use.
Returns:user – The user.
Return type:ApiResponse
request(*args, **kwargs) → Dict[str, Union[str, int, List[int]]]

Fetch raw data from the api.

Note

This method does not apply any ratelimiting logic and can be dangerous when abused.

User

class aiohn.User(session: aiohn.http.Session, id: dataclasses.InitVar, created: Union[int, datetime.datetime], karma: int, delay: Optional[int] = None, about: Optional[str] = None, submitted: List[int] = <factory>)

A HN User.

>>> await User.from_id("jl")
<aiohn.User <ident='jl', karma=4226, created=datetime.datetime(2007, 3, 15, 1, 50, 46)>>
ident

The user’s unique username. Case-sensitive.

Type:str
created

A datetime object of when the user was created.

Type:datetime.datetime
karma

The user’s karma.

Type:int
delay

Delay in minutes between a comment’s creation and its visibility to other users.

Type:Optional[int]
about

Delay in minutes between a comment’s creation and its visibility to other users.

Type:Optional[str]
submitted

List of the user’s stories, polls and comments.

Type:Optional[List[int]]
fetch_comments(predicate: Optional[Callable[[aiohn.models.Poll], bool]] = None) → AsyncIterator[aiohn.models.Poll]

Fetch comments submitted by this user.

Parameters:predicate (Optional[Callable[[aiohn.Poll], bool]]) – A predicate to filter resulting comments by, the predicate must returns True for items to be yielded and False to be discarded.
Returns:comments – An async iterator yielding Poll objects.
Return type:AsyncIterator[aiohn.Poll]
fetch_items(predicate: Optional[Callable[[aiohn.models.Item], bool]] = None) → AsyncIterator[aiohn.models.Item]

Fetch all submitted items by this user.

Parameters:predicate (Optional[Callable[[aiohn.Item], bool]]) – A predicate to filter resulting items by, the predicate must returns True for items to be yielded and False to be discarded.
Returns:items – An async iterator yielding Item objects.
Return type:AsyncIterator[aiohn.Item]
fetch_polls(predicate: Optional[Callable[[aiohn.models.Poll], bool]] = None) → AsyncIterator[aiohn.models.Poll]

Fetch polls submitted by this user.

Parameters:predicate (Optional[Callable[[aiohn.Poll], bool]]) – A predicate to filter resulting polls by, the predicate must returns True for items to be yielded and False to be discarded.
Returns:polls – An async iterator yielding Poll objects.
Return type:AsyncIterator[aiohn.Poll]
fetch_stories(predicate: Optional[Callable[[aiohn.models.Story], bool]] = None) → AsyncIterator[aiohn.models.Story]

Fetch stories submitted by this user.

Parameters:predicate (Optional[Callable[[aiohn.Story], bool]]) – A predicate to filter resulting stories by, the predicate must returns True for items to be yielded and False to be discarded.
Returns:stories – An async iterator yielding Story objects.
Return type:AsyncIterator[aiohn.Story]

Item

class aiohn.Item(id: dataclasses.InitVar, session: aiohn.http.Session, type: str, deleted: Optional[bool] = None, by: Optional[str] = None, time: Optional[int] = None, text: Optional[str] = None, dead: Optional[bool] = None, parent: Optional[int] = None, poll: Optional[int] = None, kids: Optional[List[int]] = None, url: Optional[str] = None, score: Optional[int] = None, title: Optional[str] = None, parts: Optional[List[int]] = None, descendants: Optional[int] = None)

Base class for all items.

Comment

class aiohn.Comment(id: dataclasses.InitVar, session: aiohn.http.Session, type: str, deleted: Optional[bool] = None, by: Optional[str] = None, time: Optional[int] = None, text: Optional[str] = None, dead: Optional[bool] = None, parent: Optional[int] = None, poll: Optional[int] = None, kids: Optional[List[int]] = None, url: Optional[str] = None, score: Optional[int] = None, title: Optional[str] = None, parts: Optional[List[int]] = None, descendants: Optional[int] = None)

A HN Comment object.

Story

class aiohn.Story(id: dataclasses.InitVar, session: aiohn.http.Session, type: str, deleted: Optional[bool] = None, by: Optional[str] = None, time: Optional[int] = None, text: Optional[str] = None, dead: Optional[bool] = None, parent: Optional[int] = None, poll: Optional[int] = None, kids: Optional[List[int]] = None, url: Optional[str] = None, score: Optional[int] = None, title: Optional[str] = None, parts: Optional[List[int]] = None, descendants: Optional[int] = None)

A HN Story object.

Poll

class aiohn.Poll(id: dataclasses.InitVar, session: aiohn.http.Session, type: str, deleted: Optional[bool] = None, by: Optional[str] = None, time: Optional[int] = None, text: Optional[str] = None, dead: Optional[bool] = None, parent: Optional[int] = None, poll: Optional[int] = None, kids: Optional[List[int]] = None, url: Optional[str] = None, score: Optional[int] = None, title: Optional[str] = None, parts: Optional[List[int]] = None, descendants: Optional[int] = None)

A HN Poll object.

PollOpt

class aiohn.PollOpt(id: dataclasses.InitVar, session: aiohn.http.Session, type: str, deleted: Optional[bool] = None, by: Optional[str] = None, time: Optional[int] = None, text: Optional[str] = None, dead: Optional[bool] = None, parent: Optional[int] = None, poll: Optional[int] = None, kids: Optional[List[int]] = None, url: Optional[str] = None, score: Optional[int] = None, title: Optional[str] = None, parts: Optional[List[int]] = None, descendants: Optional[int] = None)

A HN Poll opt object.