qbreader package#

Submodules#

Module contents#

The official qbreader API python wrapper.

Note

Even though useful type aliases defined in qbreader.types are reexported here, they are not documented here by sphinx-autodoc, but are documented in the types module.

See:
class qbreader.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

class qbreader.Sync#

Bases: object

The synchronous qbreader API wrapper.

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

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, …]

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, …]

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

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

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, …]

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, …]

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

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, …]

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, …]

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

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

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

class qbreader.Tossup(question: str, formatted_answer: str | None, answer: str, category: Category, subcategory: Subcategory, set: str, year: int, packet_number: int, question_number: int, difficulty: Difficulty)#

Bases: object

Tossup class.

classmethod from_json(json: dict[str, Any]) → Self#

Create a Tossup from a JSON object.

See https://www.qbreader.org/api-docs/schemas#tossups for schema.

check_answer_sync(givenAnswer: str) → AnswerJudgement#

Check whether an answer is correct.

async check_answer_async(givenAnswer: str, session: ClientSession | None = None) → AnswerJudgement#

Asynchronously check whether an answer is correct.

class qbreader.Bonus(leadin: str, parts: Sequence[str], formatted_answers: Sequence[str] | None, answers: Sequence[str], category: Category, subcategory: Subcategory, set: str, year: int, packet_number: int, question_number: int, difficulty: Difficulty)#

Bases: object

Bonus class.

classmethod from_json(json: dict[str, Any]) → Self#

Create a Bonus from a JSON object.

See https://www.qbreader.org/api-docs/schemas#bonus for schema.

check_answer_sync(part: int, givenAnswer: str) → AnswerJudgement#

Check whether an answer is correct.

async check_answer_async(part: int, givenAnswer: str, session: ClientSession) → AnswerJudgement#

Asynchronously check whether an answer is correct.

class qbreader.Packet(tossups: Sequence[Tossup], bonuses: Sequence[Bonus], number: int | None = None, name: str | None = None, year: int | None = None)#

Bases: object

Class for packets in sets.

classmethod from_json(json: dict[str, Any], number: int | None = None) → Self#

Create a Packet from a JSON object.

See https://www.qbreader.org/api-docs/packet#returns for schema.

paired_questions() → zip[tuple[Tossup, Bonus]]#

Yield pairs of tossups and bonuses.

class qbreader.QueryResponse(tossups: Sequence[Tossup], bonuses: Sequence[Bonus], tossups_found: int, bonuses_found: int, query_string: str)#

Bases: object

Class for responses to api/query requests.

classmethod from_json(json: dict[str, Any]) → Self#

Create a QueryResponse from a JSON object.

See https://www.qbreader.org/api-docs/query#returns for schema.

class qbreader.AnswerJudgement(directive: Directive, directed_prompt: str | None = None)#

Bases: object

A judgement given by api/check-answer.

correct() → bool#

Return whether the answer was correct.

classmethod from_json(json: dict[str, Any]) → Self#

Create an AnswerJudgement from a JSON object.

See https://www.qbreader.org/api-docs/check-answer#returns for schema.

classmethod check_answer_sync(answerline: str, givenAnswer: str) → Self#

Create an AnswerJudgement given an answerline and an answer.

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.

async classmethod check_answer_async(answerline: str, givenAnswer: str, session: ClientSession | None = None) → Self#

Asynchronously create an AnswerJudgement given an answerline and an answer.

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.

  • session (aiohttp.ClientSession) – The aiohttp session to use for the request.

class qbreader.Category(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: StrEnum

Question category enum.

LITERATURE = 'Literature'#
HISTORY = 'History'#
SCIENCE = 'Science'#
FINE_ARTS = 'Fine Arts'#
RELIGION = 'Religion'#
MYTHOLOGY = 'Mythology'#
PHILOSOPHY = 'Philosophy'#
SOCIAL_SCIENCE = 'Social Science'#
CURRENT_EVENTS = 'Current Events'#
GEOGRAPHY = 'Geography'#
OTHER_ACADEMIC = 'Other Academic'#
TRASH = 'Trash'#
class qbreader.Subcategory(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: StrEnum

Question subcategory enum.

LITERATURE = 'Literature'#
HISTORY = 'History'#
SCIENCE = 'Science'#
FINE_ARTS = 'Fine Arts'#
RELIGION = 'Religion'#
MYTHOLOGY = 'Mythology'#
PHILOSOPHY = 'Philosophy'#
SOCIAL_SCIENCE = 'Social Science'#
CURRENT_EVENTS = 'Current Events'#
GEOGRAPHY = 'Geography'#
OTHER_ACADEMIC = 'Other Academic'#
TRASH = 'Trash'#
AMERICAN_LITERATURE = 'American Literature'#
BRITISH_LITERATURE = 'British Literature'#
CLASSICAL_LITERATURE = 'Classical Literature'#
EUROPEAN_LITERATURE = 'European Literature'#
WORLD_LITERATURE = 'World Literature'#
OTHER_LITERATURE = 'Other Literature'#
AMERICAN_HISTORY = 'American History'#
ANCIENT_HISTORY = 'Ancient History'#
EUROPEAN_HISTORY = 'European History'#
WORLD_HISTORY = 'World History'#
OTHER_HISTORY = 'Other History'#
BIOLOGY = 'Biology'#
CHEMISTRY = 'Chemistry'#
PHYSICS = 'Physics'#
OTHER_SCIENCE = 'Other Science'#
VISUAL_FINE_ARTS = 'Visual Fine Arts'#
AUDITORY_FINE_ARTS = 'Auditory Fine Arts'#
OTHER_FINE_ARTS = 'Other Fine Arts'#
class qbreader.Difficulty(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: StrEnum

Question difficulty enum.

UNRATED = '0'#
MS = '1'#
HS_EASY = '2'#
HS_REGS = '3'#
HS_HARD = '4'#
HS_NATS = '5'#
ONE_DOT = '6'#
TWO_DOT = '7'#
THREE_DOT = '8'#
FOUR_DOT = '9'#
OPEN = '10'#
class qbreader.Directive(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)#

Bases: StrEnum

Directives given by api/check-answer.

ACCEPT = 'accept'#
REJECT = 'reject'#
PROMPT = 'prompt'#