Some type improvements

src/dvd-compare-python/dvd_compare.py

@@ -1,3 +1,4 @@
+from datetime import timedelta
 import aiohttp
 from bs4 import BeautifulSoup
 import re
@@ -7,8 +8,52 @@ class UnknownFormatError(Exception):
     pass
 
 
+class DcVideoInfo:
+    """Container to hold video specifications."""
+
+    def __init__(self):
+        self.title: str
+        """Video title."""
+        self.duration: timedelta
+        """Video duration parsed as timedelta."""
+        self.timestamp: str
+        """Video duration as printed on the website."""
+        self.category: str
+        """Parent category of video."""
+        self.disc: int
+        """Disc number this video is on."""
+
+    def __repr__(self):
+        return f"{self.title} ({self.timestamp}) [{self.category}] Disc {self.disc}"
+
+
+class DcDiscInfo:
+    """Container to hold disc specifications."""
+
+    def __init__(self):
+        self.number: int
+        """Disc number, starting at 1."""
+        self.format: str
+        """Physical disc format, e.g. DVD, Blu-Ray, etc."""
+
+
+class DcReleaseDetails:
+    """Container outlining all release details and lists all discs and videos."""
+
+    def __init__(self):
+        self.label: str
+        """Release Label taken from source."""
+        self.year: int
+        """Release year."""
+        self.discs: list[DcDiscInfo]
+        """Details about all discs included in the release."""
+        self.is_cut: bool
+        """If the version contains any special cuts."""
+        self.runtime
+
+
 class DcSearchResult:
-    """Simple container for DVD Compare Search Results, containing basic details."""
+    """Container for DVD Compare Search Results, containing basic details."""
 
     def __init__(self):
         self.label: str
@@ -18,7 +63,7 @@ class DcSearchResult:
         self.years: str
         """Entire year value, might indicate a range, parsed from label. Parsing has not been tested on all cases, some errors might occure."""
         self.titles: list[str]
-        """List of constructed title parsed from label. Media can have multiple alternative titles, but will most often be just one. Parsing has not been tested on all cases, some errors might occure."""
+        """List of constructed titles parsed from label. Media can have multiple alternative titles, but will most often be just one. Parsing has not been tested on all cases, some errors might occure."""
         self.tagline: str
         """Unprocessed tagline returned by search."""
         self.formats: list[str]
@@ -30,6 +75,10 @@ class DcSearchResult:
         self.description: str
         """Description, listing available publications to label, as returned by search."""
 
+    async def get_releases_async(self) -> list[DcReleaseDetails]:
+        """QoL Proxy to get releases to search results."""
+        return await DvdCompare.get_releases_async(self)
+
     def __repr__(self):
         return f"{self.label}\n{self.tagline}\n{self.year} | {self.years} | {' | '.join(self.formats)}\n{' | '.join(self.titles)}\n[{self.fid} | {self.url}]\n{self.description}\n"
 
@@ -40,9 +89,11 @@ class DvdCompare:
     BASE_URL: str = "https://dvdcompare.net"
     """ Can be adjusted, if the domain should ever be changed."""
 
+    @staticmethod
     def _reduce_spaces(text: str) -> str:
         return re.sub(r"\s+", " ", text).strip()
 
+    @staticmethod
     def _parse_result(item) -> DcSearchResult:
         result = DcSearchResult()
 
@@ -100,14 +151,15 @@ class DvdCompare:
 
         return result
 
+    @staticmethod
     async def search_async(
         title: str | None,
         *,
-        director: str = None,
-        year: int = None,
-        country: str = None,
-        company: str = None,
-        edition: str = None,
+        director: str | None = None,
+        year: int | None = None,
+        country: str | None = None,
+        company: str | None = None,
+        edition: str | None = None,
         search_type: str = "and",
     ) -> list[DcSearchResult]:
         """Employs the advanced search feature and parses the immediate results to python objects.
@@ -159,6 +211,12 @@ class DvdCompare:
 
         return [DvdCompare._parse_result(i) for i in result_parent.find_all("li")]
 
+    @staticmethod
+    async def get_releases_async(
+        search_result_or_fid_or_url: DcSearchResult | int | str,
+    ) -> list[DcReleaseDetails]:
+        pass
+
 
 if __name__ == "__main__":
     import asyncio