Conforms package to new API schema

README.md

@@ -13,21 +13,50 @@
 `qbreader` is a Python wrapper to the qbreader API as well as a general quizbowl library. It provides
 both asynchronous and synchronous interfaces to the API along with functionality for representing questions.
 
+## Tossup Example
+
 ```py
 >>> from qbreader import Sync as qbr # synchronous interface
->>> tossup = qbr.random_tossup()[0]
+>>> sync_client = qbr()
+>>> tossup = sync_client.random_tossup()[0]
 >>> tossup.question
+'<b>Tim Peters wrote 19 “guiding principles” of this programming language, which include the maxim “Complex is better than complicated.” The “pandas” library was written for this language. Unicode string values had to be defined with a “u” in version 2 of this language. Libraries in this language include Tkinter, Tensorflow, (*)</b> NumPy (“numb pie”) and SciPy (“sigh pie”). The framework Django was written in this language. This language uses “duck typing.” Variables in this language are often named “spam” and “eggs.” Guido van Rossum invented, for 10 points, what programming language named for a British comedy troupe?'
+>>> tossup.question_sanitized
 'Tim Peters wrote 19 “guiding principles” of this programming language, which include the maxim “Complex is better than complicated.” The “pandas” library was written for this language. Unicode string values had to be defined with a “u” in version 2 of this language. Libraries in this language include Tkinter, Tensorflow, (*) NumPy (“numb pie”) and SciPy (“sigh pie”). The framework Django was written in this language. This language uses “duck typing.” Variables in this language are often named “spam” and “eggs.” Guido van Rossum invented, for 10 points, what programming language named for a British comedy troupe?'
 >>> tossup.answer
+'<b><u>Python</u></b>'
+>>> tossup.answer_sanitized
 'Python'
 >>> tossup.category
 <Category.SCIENCE: 'Science'>
 >>> tossup.subcategory
 <Subcategory.OTHER_SCIENCE: 'Other Science'>
 >>> tossup.difficulty
 <Difficulty.HS_HARD: '4'>
->>> tossup.set
+>>> tossup.set.name
 '2022 Prison Bowl'
->>> (tossup.packet_number, tossup.question_number)
+>>> (tossup.packet.number, tossup.number)
 (4, 20)
 ```
+
+## Bonus Example
+
+```py
+>>> bonus = sync_client.random_bonus()[0]
+>>> bonus.leadin
+'The Curry–Howard isomorphism states that computer programs are directly equivalent to these mathematical constructs, which can be automated using the languages Lean or Rocq (“rock”). For 10 points each:'
+>>> bonus.leadin_sanitized
+'The Curry-Howard isomorphism states that computer programs are directly equivalent to these mathematical constructs, which can be automated using the languages Lean or Rocq ("rock"). For 10 points each:'
+>>> bonus.parts
+('Name these mathematical constructs that are used to formally demonstrate the truth of a mathematical statement.', 'According to the Curry–Howard isomorphism, these programming concepts correspond to individual propositions of a proof. One method of “inferring” these things in programming languages like Python is named for the duck test.', 'Haskell Curry also lends his name to “currying,” a common tool in functional programming languages that transforms a function into a sequence of functions each with a smaller value for this property. A description is acceptable.')
+>>> bonus.parts_sanitized
+('Name these mathematical constructs that are used to formally demonstrate the truth of a mathematical statement.', 'According to the Curry-Howard isomorphism, these programming concepts correspond to individual propositions of a proof. One method of "inferring" these things in programming languages like Python is named for the duck test.', 'Haskell Curry also lends his name to "currying," a common tool in functional programming languages that transforms a function into a sequence of functions each with a smaller value for this property. A description is acceptable.')
+>>> bonus.answers
+('mathematical <b><u>proof</u>s</b> [or formal <b><u>proof</u></b>s or <b><u>proof</u></b>s of correctness; accept <b><u>proof</u></b> assistant or theorem <b><u>prover</u></b> or Rocq <b><u>prover</u></b>]', 'data <b><u>type</u></b>s [accept <b><u>type</u></b> inference or duck <b><u>typing</u></b>]', '<b><u>arity</u></b> [accept descriptions of the <b><u>number of argument</u></b>s or the <b><u>number of parameter</u></b>s or the <b><u>number of</u> <u>input</u></b>s of a function]')
+>>> bonus.answers_sanitized
+('mathematical proofs [or formal proofs or proofs of correctness; accept proof assistant or theorem prover or Rocq prover]', 'data types [accept type inference or duck typing]', 'arity [accept descriptions of the number of arguments or the number of parameters or the number of inputs of a function]')
+>>> bonus.difficultyModifiers
+('e', 'm', 'h')
+>>> bonus.values
+(10, 10, 10)
+```

pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "qbreader"
-version = "1.0.0-rc.2"
+version = "1.0.0-rc.3"
 description = "Quizbowl library and Python wrapper for the qbreader API"
 authors = [
     "Sky \"g3ner1c\" Hong <[email protected]>",
@@ -27,7 +27,7 @@ classifiers = [
 ]
 
 [tool.poetry.dependencies]
-python = "^3.11"
+python = "~3.11"
 requests = "^2.31.0"
 aiohttp = "^3.8.4"
 

qbreader/asynchronous.py

@@ -19,6 +19,7 @@
     UnnormalizedCategory,
     UnnormalizedDifficulty,
     UnnormalizedSubcategory,
+    Year,
 )
 
 
@@ -210,8 +211,8 @@ async def random_tossup(
         categories: UnnormalizedCategory = None,
         subcategories: UnnormalizedSubcategory = None,
         number: int = 1,
-        min_year: int = 2010,
-        max_year: int = 2023,
+        min_year: int = Year.MIN_YEAR,
+        max_year: int = Year.CURRENT_YEAR,
     ) -> tuple[Tossup, ...]:
         """Get random tossups from the database.
 
@@ -231,9 +232,9 @@ async def random_tossup(
             between categories and subcategories.
         number : int, default = 1
             The number of tossups to return.
-        min_year : int, default = 2010
+        min_year : int, default = Year.MIN_YEAR
             The oldest year to search for.
-        max_year : int, default = 2023
+        max_year : int, default = Year.CURRENT_YEAR
             The most recent year to search for.
 
         Returns
@@ -280,8 +281,8 @@ async def random_bonus(
         categories: UnnormalizedCategory = None,
         subcategories: UnnormalizedSubcategory = None,
         number: int = 1,
-        min_year: int = 2010,
-        max_year: int = 2023,
+        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.
@@ -302,9 +303,9 @@ async def random_bonus(
             between categories and subcategories.
         number : int, default = 1
             The number of bonuses to return.
-        min_year : int, default = 2010
+        min_year : int, default = Year.MIN_YEAR
             The oldest year to search for.
-        max_year : int, default = 2023
+        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.

qbreader/synchronous.py

@@ -19,6 +19,7 @@
     UnnormalizedCategory,
     UnnormalizedDifficulty,
     UnnormalizedSubcategory,
+    Year,
 )
 
 
@@ -175,8 +176,8 @@ def random_tossup(
         categories: UnnormalizedCategory = None,
         subcategories: UnnormalizedSubcategory = None,
         number: int = 1,
-        min_year: int = 2010,
-        max_year: int = 2023,
+        min_year: int = Year.MIN_YEAR,
+        max_year: int = Year.CURRENT_YEAR,
     ) -> tuple[Tossup, ...]:
         """Get random tossups from the database.
 
@@ -196,9 +197,9 @@ def random_tossup(
             between categories and subcategories.
         number : int, default = 1
             The number of tossups to return.
-        min_year : int, default = 2010
+        min_year : int, default = Year.MIN_YEAR
             The oldest year to search for.
-        max_year : int, default = 2023
+        max_year : int, default = Year.CURRENT_YEAR
             The most recent year to search for.
 
         Returns
@@ -245,8 +246,8 @@ def random_bonus(
         categories: UnnormalizedCategory = None,
         subcategories: UnnormalizedSubcategory = None,
         number: int = 1,
-        min_year: int = 2010,
-        max_year: int = 2023,
+        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.
@@ -267,9 +268,9 @@ def random_bonus(
             between categories and subcategories.
         number : int, default = 1
             The number of bonuses to return.
-        min_year : int, default = 2010
+        min_year : int, default = Year.MIN_YEAR
             The oldest year to search for.
-        max_year : int, default = 2023
+        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.