diff --git a/qbreader/_api_utils.py b/qbreader/_api_utils.py index 23ab000..c138c32 100644 --- a/qbreader/_api_utils.py +++ b/qbreader/_api_utils.py @@ -4,17 +4,17 @@ import warnings from enum import Enum, EnumType -from typing import Iterable, Optional, Union, Tuple +from typing import Iterable, Optional, Tuple, Union from qbreader.types import ( - Difficulty, + AlternateSubcategory, Category, + Difficulty, Subcategory, - AlternateSubcategory, + UnnormalizedAlternateSubcategory, UnnormalizedCategory, UnnormalizedDifficulty, UnnormalizedSubcategory, - UnnormalizedAlternateSubcategory, ) @@ -106,7 +106,8 @@ def normalize_subcat(unnormalized_subcats: UnnormalizedCategory): def category_correspondence( typed_alt_subcat: AlternateSubcategory, -) -> Tuple[Category, Subcategory]: +) -> Tuple[Category | None, Subcategory | None]: + """Return the corresponding category/subcategory for a alternate_subcategory.""" if typed_alt_subcat in [ AlternateSubcategory.ASTRONOMY, AlternateSubcategory.COMPUTER_SCIENCE, @@ -147,18 +148,19 @@ def category_correspondence( ]: return (Category.LITERATURE, None) + # Accounts for AlternateSubcategory.PRACTICES and AlternateSubcategory.BELIEFS + return (None, None) + def normalize_cats( unnormalized_cats: UnnormalizedCategory, unnormalized_subcats: UnnormalizedSubcategory, unnormalized_alt_subcats: UnnormalizedAlternateSubcategory, -) -> Tuple[Category, Subcategory, AlternateSubcategory]: - """ - Normalize a single or list of categories, subcategories, and alternate_subcategories - to their corresponding comma-separated strings, taking into account categories and - subcategories that must be added for the alternate_subcategories to work. - """ - +) -> Tuple[str, str, str]: + """Normalize a single or list of categories, subcategories, and\ + alternate_subcategories to their corresponding comma-separated strings, taking into\ + account categories and subcategories that must be added for the\ + alternate_subcategories to work.""" typed_alt_subcats: list[AlternateSubcategory] = [] if isinstance(unnormalized_alt_subcats, str): @@ -183,8 +185,8 @@ def normalize_cats( elif isinstance(unnormalized_cats, str): final_cats = [Category(unnormalized_cats), *to_be_pushed_cats] elif isinstance(unnormalized_cats, Iterable): - for subcat in unnormalized_cats: - final_cats.append(Subcategory(subcat)) + for unnormalized_cat in unnormalized_cats: + final_cats.append(Category(unnormalized_cat)) final_cats.append(*to_be_pushed_cats) final_subcats = [] @@ -193,8 +195,8 @@ def normalize_cats( elif isinstance(unnormalized_subcats, str): final_subcats = [Subcategory(unnormalized_subcats), *to_be_pushed_subcats] elif isinstance(unnormalized_subcats, Iterable): - for subcat in unnormalized_subcats: - final_subcats.append(Subcategory(subcat)) + for unnormalized_subcat in unnormalized_subcats: + final_subcats.append(Subcategory(unnormalized_subcat)) final_subcats.append(*to_be_pushed_subcats) return ( diff --git a/qbreader/asynchronous.py b/qbreader/asynchronous.py index 414b184..97265fb 100644 --- a/qbreader/asynchronous.py +++ b/qbreader/asynchronous.py @@ -16,10 +16,10 @@ QuestionType, SearchType, Tossup, + UnnormalizedAlternateSubcategory, UnnormalizedCategory, UnnormalizedDifficulty, UnnormalizedSubcategory, - UnnormalizedAlternateSubcategory, Year, ) @@ -116,7 +116,8 @@ class type. 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. - alternate_subcategories : qbreader.types.UnnormalizedAlternateSubcategory, optional + alternate_subcategories : qbreader.types.UnnormalizedAlternateSubcategory,\ + optional The alternate subcategories to search for. Can be a single or an array of `AlternateSubcategory` enums or strings. The API does not check for consistency between categories and subcategories @@ -244,7 +245,8 @@ async def random_tossup( 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. - alternate_subcategories : qbreader.types.UnnormalizedAlternateSubcategory, optional + alternate_subcategories : qbreader.types.UnnormalizedAlternateSubcategory,\ + optional The alternate subcategories to search for. Can be a single or an array of `AlternateSubcategory` enums or strings. The API does not check for consistency between categories and subcategories @@ -327,10 +329,11 @@ async def random_bonus( 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. - alternate_subcategories: qbreaader.types.UnnormalizedAlternateSubcategory, optional + alternate_subcategories: qbreader.types.UnnormalizedAlternateSubcategory, \ + optional The alternates subcategories to search for. Can be a single or an array of - `AlternateSubcategory` enum variants or strings. The API does not check for consistency - between categories, subcategories, and alternate subcategories. + `AlternateSubcategory` enum variants or strings. The API does not check for + consistency between categories, subcategories, and alternate subcategories. number : int, default = 1 The number of bonuses to return. min_year : int, default = Year.MIN_YEAR diff --git a/qbreader/synchronous.py b/qbreader/synchronous.py index 217528d..31c1bb0 100644 --- a/qbreader/synchronous.py +++ b/qbreader/synchronous.py @@ -16,10 +16,10 @@ QuestionType, SearchType, Tossup, - UnnormalizedDifficulty, + UnnormalizedAlternateSubcategory, UnnormalizedCategory, + UnnormalizedDifficulty, UnnormalizedSubcategory, - UnnormalizedAlternateSubcategory, Year, ) @@ -81,10 +81,11 @@ class type. 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. - alternate_subcategories: qbreaader.types.UnnormalizedAlternateSubcategory, optional + alternate_subcategories: qbreaader.types.UnnormalizedAlternateSubcategory,\ + optional The alternates subcategories to search for. Can be a single or an array of - `AlternateSubcategory` enum variants or strings. The API does not check for consistency - between categories, subcategories, and alternate subcategories. + `AlternateSubcategory` enum variants or strings. The API does not check for + consistency between categories, subcategories, and alternate subcategories. maxReturnLength : int, default = 25 The maximum number of questions to return. tossupPagination : int, default = 1 @@ -209,10 +210,11 @@ def random_tossup( 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. - alternate_subcategories: qbreaader.types.UnnormalizedAlternateSubcategory, optional + alternate_subcategories: qbreaader.types.UnnormalizedAlternateSubcategory, + optional The alternates subcategories to search for. Can be a single or an array of - `AlternateSubcategory` enum variants or strings. The API does not check for consistency - between categories, subcategories, and alternate subcategories. + `AlternateSubcategory` enum variants or strings. The API does not check for + consistency between categories, subcategories, and alternate subcategories. number : int, default = 1 The number of tossups to return. min_year : int, default = Year.MIN_YEAR @@ -283,19 +285,20 @@ def 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. + 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. + 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. - alternate_subcategories: qbreaader.types.UnnormalizedAlternateSubcategory, optional + alternate_subcategories : qbreaader.types.UnnormalizedAlternateSubcategory, + optional The alternates subcategories to search for. Can be a single or an array of - `AlternateSubcategory` enum variants or strings. The API does not check for consistency - between categories, subcategories, and alternate subcategories. + `AlternateSubcategory` enum variants or strings. The API does not check for + consistency between categories, subcategories, and alternate subcategories. number : int, default = 1 The number of bonuses to return. min_year : int, default = Year.MIN_YEAR diff --git a/qbreader/types.py b/qbreader/types.py index c90fdb3..9ae73db 100644 --- a/qbreader/types.py +++ b/qbreader/types.py @@ -88,6 +88,7 @@ class AlternateSubcategory(enum.StrEnum): DANCE = "Dance" FILM = "Film" JAZZ = "Jazz" + MUSICALS = "Musicals" OPERA = "Opera" PHOTOGRAPHY = "Photography" MISC_ARTS = "Misc Arts" @@ -290,7 +291,7 @@ def __init__( self.packet: PacketMetadata = packet self.set: SetMetadata = set self.number: int = number - self.alternate_subcategory: AlternateSubcategory = alternate_subcategory + self.alternate_subcategory: AlternateSubcategory | None = alternate_subcategory @classmethod def from_json(cls: Type[Self], json: dict[str, Any]) -> Self: @@ -384,7 +385,7 @@ def __init__( self.set: SetMetadata = set self.packet: PacketMetadata = packet self.number: int = number - self.alternate_subcategory: AlternateSubcategory = alternate_subcategory + self.alternate_subcategory: AlternateSubcategory | None = alternate_subcategory self.values: Optional[tuple[int, ...]] = tuple(values) if values else None self.difficultyModifiers: Optional[tuple[DifficultyModifier, ...]] = ( tuple(difficultyModifiers) if difficultyModifiers else None @@ -687,8 +688,8 @@ def __str__(self) -> str: UnnormalizedAlternateSubcategory: TypeAlias = Optional[ Union[AlternateSubcategory, str, Iterable[Union[AlternateSubcategory, str]]] ] -"""Type alias for unnormalized alternate subcategories. Union of `AlternateSubcategory`, `str`, and -`collections.abc.Iterable` containing either.""" +"""Type alias for unnormalized alternate subcategories. Union of `AlternateSubcategory`, +`str`, and `collections.abc.Iterable` containing either.""" __all__ = (