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 = Year.MIN_YEAR, max_year: int = Year.CURRENT_YEAR) → 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 = Year.MIN_YEAR) – The oldest year to search for.

  • max_year (int, default = Year.CURRENT_YEAR) – 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 = Year.MIN_YEAR, max_year: int = Year.CURRENT_YEAR, 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 = Year.MIN_YEAR) – The oldest year to search for.

  • max_year (int, default = Year.CURRENT_YEAR) – 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 = Year.MIN_YEAR, max_year: int = Year.CURRENT_YEAR) → 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 = Year.MIN_YEAR) – The oldest year to search for.

  • max_year (int, default = Year.CURRENT_YEAR) – 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 = Year.MIN_YEAR, max_year: int = Year.CURRENT_YEAR, 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 = Year.MIN_YEAR) – The oldest year to search for.

  • max_year (int, default = Year.CURRENT_YEAR) – 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, question_sanitized: str, answer: str, answer_sanitized: str, difficulty: Difficulty, category: Category, subcategory: Subcategory, packet: PacketMetadata, set: SetMetadata, number: int)

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, leadin_sanitized: str, parts: Sequence[str], parts_sanitized: Sequence[str], answers: Sequence[str], answers_sanitized: Sequence[str], difficulty: Difficulty, category: Category, subcategory: Subcategory, set: SetMetadata, packet: PacketMetadata, number: int, values: Sequence[int] | None = None, difficultyModifiers: Sequence[DifficultyModifier] | None = None)

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=<not given>, *values, 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=<not given>, *values, 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=<not given>, *values, 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=<not given>, *values, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: StrEnum

Directives given by api/check-answer.

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