Add and fix some typings

beetsplug/api.py

@@ -70,7 +70,7 @@ def get_audible_album_region(url: str) -> str | None:
         return None
 
 
-def make_request(url: str) -> bytes:
+def make_request(url: str) -> bytes | None:
     """Makes a request to the specified url and returns received response
     The request will be retried up to 3 times in case of failure.
     """

beetsplug/audible.py

@@ -131,7 +131,7 @@ def __init__(self):
         region = mediafile.MediaField()
         self.add_media_field("region", region)
 
-    def candidates(self, items, artist, album, va_likely):
+    def candidates(self, items, artist, album, va_likely) -> list[AlbumInfo]:
         """Returns a list of AlbumInfo objects for Audible search results
         matching an album and artist (if not various).
         """
@@ -203,7 +203,7 @@ def candidates(self, items, artist, album, va_likely):
                 )
         return albums
 
-    def maybe_align_tracks_with_items(self, album_info, items, *, is_likely_match=True):
+    def maybe_align_tracks_with_items(self, album_info, items, *, is_likely_match=True) -> int | None:
         """Override chapter data from Audible with the current file list when needed."""
         if not is_likely_match or not items or not album_info.tracks:
             return None
@@ -232,7 +232,7 @@ def maybe_align_tracks_with_items(self, album_info, items, *, is_likely_match=Tr
         ]
         return chapter_count_from_audible
 
-    def get_album_from_yaml_metadata(self, data, items):
+    def get_album_from_yaml_metadata(self, data, items) -> AlbumInfo:
         """Returns an `AlbumInfo` object by populating it with details from metadata.yml"""
         title = data["title"]
         subtitle = data.get("subtitle")
@@ -313,7 +313,7 @@ def get_album_from_yaml_metadata(self, data, items):
             **common_attributes,
         )
 
-    def album_for_id(self, album_id):
+    def album_for_id(self, album_id) -> AlbumInfo | None:
         """
         Fetches book info by its asin and returns an AlbumInfo object
         or None if the book was not found.
@@ -327,7 +327,7 @@ def album_for_id(self, album_id):
             self._log.debug(f"Exception while getting book {asin}", exc_info=True)
             return None
 
-    def get_albums(self, query, region):
+    def get_albums(self, query, region) -> list[AlbumInfo]:
         """Returns a list of AlbumInfo objects for an Audible search query."""
 
         try:
@@ -357,7 +357,7 @@ def get_albums(self, query, region):
             self._log.warning("Error while fetching book information from Audnex", exc_info=True)
             return []
 
-    def get_album_info(self, asin, region):
+    def get_album_info(self, asin, region) -> AlbumInfo:
         """Returns an AlbumInfo object for a book given its asin."""
 
         (book, chapters) = get_book_info(asin, region)
@@ -490,11 +490,11 @@ def get_album_info(self, asin, region):
             **common_attributes,
         )
 
-    def track_for_id(self, track_id: str):
+    def track_for_id(self, track_id: str) -> None:
         self._log.debug("Searching for track {}", track_id)
         return None
 
-    def item_candidates(self, item, artist, title):
+    def item_candidates(self, item, artist, title) -> list[TrackInfo]:
         """Returns a list of TrackInfo objects for individual track search.
 
         Audiobooks are not searched by individual tracks, so this returns an empty list.
@@ -505,7 +505,7 @@ def item_candidates(self, item, artist, title):
         return []
 
     @staticmethod
-    def on_write(item, path, tags):
+    def on_write(item, path, tags) -> None:
         # Strip unwanted tags that Beets automatically adds
         tags["mb_albumid"] = None
         tags["mb_trackid"] = None
@@ -521,7 +521,7 @@ def on_write(item, path, tags):
                 # The "mvi" tag for m4b files only accepts integers
                 tags["mvi"] = int(tags.get("series_position"))
 
-    def fetch_art(self, session, task):
+    def fetch_art(self, session, task) -> None:
         # Only fetch art for albums
         if task.is_album:
             if task.album.artpath and os.path.isfile(task.album.artpath):
@@ -546,7 +546,7 @@ def fetch_art(self, session, task):
                     f"Error while downloading cover art for {title} by {author} from {cover_url}", exc_info=True
                 )
 
-    def fetch_image(self, url):
+    def fetch_image(self, url) -> bytes:
         """Downloads an image from a URL and returns a path to the downloaded image."""
         image = make_request(url)
         ext = url[-4:]  # e.g, ".jpg"
@@ -555,14 +555,14 @@ def fetch_image(self, url):
         self._log.debug("downloaded art to: {0}", util.displayable_path(fh.name))
         return util.bytestring_path(fh.name)
 
-    def on_import_task_files(self, task, session):
+    def on_import_task_files(self, task, session) -> None:
         self.write_book_description_and_narrator(task.imported_items())
         if self.config["fetch_art"] and task in self.cover_art:
             cover_path = self.cover_art.pop(task)
             task.album.set_art(cover_path, True)
             task.album.store()
 
-    def write_book_description_and_narrator(self, items):
+    def write_book_description_and_narrator(self, items) -> None:
         """Write description.txt, reader.txt and cover art"""
         if len(items) == 0:
             return
@@ -580,7 +580,7 @@ def write_book_description_and_narrator(self, items):
             with open(os.path.join(destination, b"reader.txt"), "w") as f:
                 f.write(narrator)
 
-    def on_album_matched(self, match):
+    def on_album_matched(self, match) -> None:
         """Adjust final album matches to align tracks with imported files where needed."""
         if match.info.data_source != self.data_source:
             return
@@ -598,10 +598,10 @@ def on_album_matched(self, match):
         match.extra_tracks = extra_tracks
         match.distance = distance(all_items, match.info, item_info_pairs)
 
-    def before_choose_candidate_event(self, session, task):
+    def before_choose_candidate_event(self, session, task) -> list[ui.commands.PromptChoice]:
         return [PromptChoice("r", "Region switch", self.book_level_region_switch)]
 
-    def book_level_region_switch(self, session, task):
+    def book_level_region_switch(self, session, task) -> None:
         """Prompts the book level region value"""
         available_region_codes = ", ".join(ui.colorize("text_diff_added", reg) for reg in AUDIBLE_REGIONS)
 
@@ -640,7 +640,7 @@ def book_level_region_switch(self, session, task):
         task.lookup_candidates()
 
 
-def get_item_region(item):
+def get_item_region(item) -> str | None:
     """Get the value of the 'region' field, if it is available, or can be extracted from 'album_url'."""
     available_field_names = item.keys()
     album_url = None

beetsplug/book.py

@@ -117,7 +117,7 @@ def __init__(
         self.region = region
 
     @staticmethod
-    def from_audnex_book(b: dict):
+    def from_audnex_book(b: dict) -> "Book":
         """
         Creates a `Book` from an Audnex book result
         """
@@ -209,7 +209,7 @@ def __init__(
         self.runtime_length_sec = runtime_length_sec
 
     @staticmethod
-    def from_audnex_chapter_info(c: dict):
+    def from_audnex_chapter_info(c: dict) -> "BookChapters":
         """
         Creates a `BookChapters` instance from audnex's /book/{asin}/chapters endpoint
         """

beetsplug/goodreads.py

@@ -24,7 +24,7 @@ def get_original_date(self, asin: str, authors: str, title: str) -> dict:
     return original_date
 
 
-def goodreads_get_best_match(self, response: Element, author: str, title: str) -> Element:
+def goodreads_get_best_match(self, response: Element, author: str, title: str) -> Element | None:
     # returns best matching work from results
     author_cleaned = author.replace(" ", "")
     # get all works
@@ -50,7 +50,7 @@ def goodreads_get_total_result(response: Element) -> int:
     return int(response.findtext("./search/total-results"))
 
 
-def parse_original_date(work: Element) -> dict:
+def parse_original_date(work: Element) -> dict[str, int | None]:
     original_date = {}
     if work is not None:
         year = work.findtext("original_publication_year")