qbreader.asynchronous module#

Directly access the qbreader API asynchronously.

class qbreader.asynchronous.Async#

Bases: object

The asynchronous qbreader API wrapper.

session: ClientSession#
async classmethod create(session: ClientSession | None = None) → Self#

Create a new Async instance. __init__() is not async, so this is necessary.

Parameters:

session (aiohttp.ClientSession, optional) – The aiohttp session to use for requests. If none is provided, a new session will be created.

Returns:

The new Async instance.

Return type:

Async

async close() → None#

Close the aiohttp session.

async query(questionType: qbreader.types.QuestionType = 'all', searchType: qbreader.types.SearchType = 'all', queryString: str | None = '', exactPhrase: bool | None = False, ignoreDiacritics: bool | None = False, ignoreWordOrder: bool | None = False, regex: bool | None = False, randomize: bool | None = False, setName: str | None = None, difficulties: qbreader.types.UnnormalizedDifficulty = None, categories: qbreader.types.UnnormalizedCategory = None, subcategories: qbreader.types.UnnormalizedSubcategory = None, maxReturnLength: int | None = 25, tossupPagination: int | None = 1, bonusPagination: int | None = 1) → QueryResponse#

Query the qbreader database for questions.

Original API doc at https://www.qbreader.org/api-docs/query.

Parameters:

  • questionType (qbreader.types.QuestionType) – The type of question to search for. Can be either a string or a question class type.

  • searchType (qbreader.types.SearchType) – Where to search for the query string. Can only be a string.

  • queryString (str, optional) – The string to search for.

  • exactPhrase (bool, default = False) – Ensure that the query string is an exact phrase.

  • ignoreDiacritics (bool, default = False) – Ignore or transliterate diacritical marks in queryString.

  • ignoreWordOrder (bool, default = False) – Treat queryString as a set of keywords that can appear in any order.

  • regex (bool, default = False) – Treat queryString as a regular expression.

  • randomize (bool, default = False) – Randomize the order of the returned questions.

  • setName (str, optional) – The name of the set to search in.

  • difficulties (qbreader.types.UnnormalizedDifficulty, optional) – The difficulties to search for. Can be a single or an array of Difficulty enums, strings, or integers.

  • categories (qbreader.types.UnnormalizedCategory, optional) – The categories to search for. Can be a single or an array of Category enums or strings.

  • subcategories (qbreader.types.UnnormalizedSubcategory, optional) – The subcategories to search for. Can be a single or an array of Subcategory enums or strings. The API does not check for consistency between categories and subcategories.

  • maxReturnLength (int, default = 25) – The maximum number of questions to return.

  • tossupPagination (int, default = 1) – The page of tossups to return.

  • bonusPagination (int, default = 1) – The page of bonuses to return.

Returns:

A QueryResponse object containing the results of the query.

Return type:

QueryResponse

async random_tossup(difficulties: qbreader.types.UnnormalizedDifficulty = None, categories: qbreader.types.UnnormalizedCategory = None, subcategories: qbreader.types.UnnormalizedSubcategory = None, number: int = 1, min_year: int = 2010, max_year: int = 2023) → tuple[Tossup, ...]#

Get random tossups from the database.

Original API doc at https://www.qbreader.org/api-docs/random-tossup.

Parameters:

  • difficulties (qbreader.types.UnnormalizedDifficulty, optional) – The difficulties to search for. Can be a single or an array of Difficulty enums, strings, or integers.

  • categories (qbreader.types.UnnormalizedCategory, optional) – The categories to search for. Can be a single or an array of Category enums or strings.

  • subcategories (qbreader.types.UnnormalizedSubcategory, optional) – The subcategories to search for. Can be a single or an array of Subcategory enums or strings. The API does not check for consistency between categories and subcategories.

  • number (int, default = 1) – The number of tossups to return.

  • min_year (int, default = 2010) – The oldest year to search for.

  • max_year (int, default = 2023) – The most recent year to search for.

Returns:

A tuple of Tossup objects.

Return type:

tuple[Tossup, …]

async random_bonus(difficulties: qbreader.types.UnnormalizedDifficulty = None, categories: qbreader.types.UnnormalizedCategory = None, subcategories: qbreader.types.UnnormalizedSubcategory = None, number: int = 1, min_year: int = 2010, max_year: int = 2023, three_part_bonuses: bool = False) → tuple[Bonus, ...]#

Get random bonuses from the database.

Original API doc at https://www.qbreader.org/api-docs/random-bonus.

Parameters:

  • difficulties (qbreader.types.UnnormalizedDifficulty, optional) – The difficulties to search for. Can be a single or an array of Difficulty enums, strings, or integers.

  • categories (qbreader.types.UnnormalizedCategory, optional) – The categories to search for. Can be a single or an array of Category enums or strings.

  • subcategories (qbreader.types.UnnormalizedSubcategory, optional) – The subcategories to search for. Can be a single or an array of Subcategory enums or strings. The API does not check for consistency between categories and subcategories.

  • number (int, default = 1) – The number of bonuses to return.

  • min_year (int, default = 2010) – The oldest year to search for.

  • max_year (int, default = 2023) – The most recent year to search for.

  • three_part_bonuses (bool, default = False) – Whether to only return bonuses with 3 parts.

Returns:

A tuple of Bonus objects.

Return type:

tuple[Bonus, …]

async random_name() → str#

Get a random adjective-noun pair that can be used as a name.

Original API doc at https://www.qbreader.org/api-docs/random-name.

Returns:

A string containing the random name.

Return type:

str

async packet(setName: str, packetNumber: int) → Packet#

Get a specific packet from a set.

Original API doc at https://www.qbreader.org/api-docs/packet.

Parameters:

  • setName (str) – The name of the set. See set_list() for a list of valid set names.

  • packetNumber (int) – The number of the packet in the set, starting from 1.

Returns:

A Packet object containing the packet’s tossups and bonuses.

Return type:

Packet

async packet_tossups(setName: str, packetNumber: int) → tuple[Tossup, ...]#

Get only tossups from a packet.

Original API doc at https://www.qbreader.org/api-docs/packet-tossups.

Parameters:

  • setName (str) – The name of the set. See set_list() for a list of valid set names.

  • packetNumber (int) – The number of the packet in the set, starting from 1.

Returns:

A tuple of Tossup objects.

Return type:

tuple[Tossup, …]

async packet_bonuses(setName: str, packetNumber: int) → tuple[Bonus, ...]#

Get only bonuses from a packet.

Original API doc at https://www.qbreader.org/api-docs/packet-bonuses.

Parameters:

  • setName (str) – The name of the set. See set_list() for a list of valid set names.

  • packetNumber (int) – The number of the packet in the set, starting from 1.

Returns:

A tuple of Bonus objects.

Return type:

tuple[Bonus, …]

async num_packets(setName: str) → int#

Get the number of packets in a set.

Original API doc at https://www.qbreader.org/api-docs/num-packets.

Parameters:

setName (str) – The name of the set to search. Can be obtained from set_list().

Returns:

The number of packets in the set.

Return type:

int

async set_list() → tuple[str, ...]#

Get a list of all the sets in the database.

Original API doc at https://www.qbreader.org/api-docs/set-list.

Returns:

A tuple containing the names of all the sets in the database, sorted in reverse alphanumeric order.

Return type:

tuple[str, …]

async room_list() → tuple[dict, ...]#

Get a list of public rooms.

Original API doc at https://www.qbreader.org/api-docs/multiplayer/room-list.

Returns:

A tuple containing the room data for all the public rooms.

Return type:

tuple[dict, …]

async check_answer(answerline: str, givenAnswer: str) → AnswerJudgement#

Judge an answer to be correct, incorrect, or prompt (can be directed).

Original API doc at https://www.qbreader.org/api-docs/check-answer.

Parameters:

  • answerline (str) – The answerline to check against. Preferably including the HTML tags <b> and <u>, if they are present.

  • givenAnswer (str) – The answer to check.

Returns:

A AnswerJudgement object containing the response.

Return type:

AnswerJudgement

async tossup_by_id(id: str) → Tossup#

Get a tossup by its ID.

Original API doc at https://www.qbreader.org/api-docs/tossup-by-id.

Parameters:

id (str) – The ID of the tossup to get.

Returns:

A Tossup object.

Return type:

Tossup

async bonus_by_id(id: str) → Bonus#

Get a bonus by its ID.

Original API doc at https://www.qbreader.org/api-docs/bonus-by-id.

Parameters:

id (str) – The ID of the bonus to get.

Returns:

A Bonus object.

Return type:

Bonus