compuglobal 0.3.6__tar.gz → 0.3.8__tar.gz

{compuglobal-0.3.6 → compuglobal-0.3.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: compuglobal
-Version: 0.3.6
+Version: 0.3.8
 Summary: Python wrapper for the CGHMC API (Frinkiac, Morbotron Master Of All Science and more.
 Keywords: The Simpsons,Futurama,Rick and Morty,West Wing,Frinkiac,Morbotron,Master of all Science,Capital Beat,API,API Wrapper,CompuGlobal,CompuGlobalHyperMegaNet,CGHMC
 Author: MitchellAW
@@ -12,7 +12,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Operating System :: OS Independent
 Classifier: Intended Audience :: Developers
 License-File: LICENSE
-Requires-Dist: aiohttp>=3.13.0
+Requires-Dist: aiohttp>=3.14.0
 Requires-Dist: pydantic>=2.13.0
 Project-URL: Documentation, https://compuglobal.readthedocs.io/en/latest/
 Project-URL: Source, https://github.com/MitchellAW/CompuGlobal
@@ -25,10 +25,15 @@ CompuGlobal
 
 .. image:: https://img.shields.io/pypi/v/compuglobal.svg
    :target: https://pypi.python.org/pypi/compuglobal
+
 .. image:: https://img.shields.io/pypi/pyversions/compuglobal.svg
    :target: https://pypi.python.org/pypi/compuglobal
-.. image:: https://img.shields.io/badge/PRs-welcome-brightgreen.svg
-   :target: http://makeapullrequest.com
+
+.. image:: https://img.shields.io/github/actions/workflow/status/MitchellAW/CompuGlobal/test.yml?label=tests
+   :target: https://github.com/MitchellAW/CompuGlobal/actions/workflows/test.yml
+
+.. image:: https://img.shields.io/github/license/mitchellaw/compuglobal
+   :target: https://github.com/MitchellAW/CompuGlobal/blob/main/LICENSE
 
 Python wrapper for all endpoints of the following undocumented APIs:
 

{compuglobal-0.3.6 → compuglobal-0.3.8}/README.rst

@@ -6,10 +6,15 @@ CompuGlobal
 
 .. image:: https://img.shields.io/pypi/v/compuglobal.svg
    :target: https://pypi.python.org/pypi/compuglobal
+
 .. image:: https://img.shields.io/pypi/pyversions/compuglobal.svg
    :target: https://pypi.python.org/pypi/compuglobal
-.. image:: https://img.shields.io/badge/PRs-welcome-brightgreen.svg
-   :target: http://makeapullrequest.com
+
+.. image:: https://img.shields.io/github/actions/workflow/status/MitchellAW/CompuGlobal/test.yml?label=tests
+   :target: https://github.com/MitchellAW/CompuGlobal/actions/workflows/test.yml
+
+.. image:: https://img.shields.io/github/license/mitchellaw/compuglobal
+   :target: https://github.com/MitchellAW/CompuGlobal/blob/main/LICENSE
 
 Python wrapper for all endpoints of the following undocumented APIs:
 

{compuglobal-0.3.6 → compuglobal-0.3.8}/compuglobal/__init__.py

@@ -16,11 +16,12 @@ from compuglobal.models.frame import Frame, FrameResult
 from compuglobal.models.screencap import Screencap, ScreencapMoment
 from compuglobal.models.stream import Stream, StreamOverlay
 from compuglobal.models.subtitle import Subtitle
+from compuglobal.models.timestamp import Timestamp
 
 __title__ = "compuglobal"
 __author__ = "MitchellAW"
 __license__ = "MIT"
-__version__ = "0.3.6"
+__version__ = "0.3.8"
 
 __all__ = [
     "APIPageStatusError",
@@ -47,4 +48,5 @@ __all__ = [
     "Stream",
     "StreamOverlay",
     "Subtitle",
+    "Timestamp",
 ]

{compuglobal-0.3.6 → compuglobal-0.3.8}/compuglobal/aio.py

@@ -91,13 +91,22 @@ class AsyncCompuGlobalAPI:
         caption = await self.client.handle_request(request)
         return Screencap.model_validate(caption)
 
-    async def search(self, search_text: str) -> list[FrameResult]:
+    async def search(
+        self,
+        search_text: str,
+        season_minimum: int | None = None,
+        season_maximum: int | None = None,
+    ) -> list[FrameResult]:
         """Perform a search of the given search text and returns a list of all the Frames.
 
         Parameters
         ----------
         search_text : str
             The search text to query
+        season_minimum: int | None, optional
+            The minimum season allowed in the search results
+        season_maximum: int | None, optional
+            The maximum season allowed in the search results
 
         Returns
         -------
@@ -110,9 +119,11 @@ class AsyncCompuGlobalAPI:
             Raises an error if no search results are found
 
         """
-        params = {"q": search_text}
+        optional_params = {"smin": season_minimum, "smax": season_maximum}
+        query = {"q": search_text}
+        query |= {k: v for k, v in optional_params.items() if v is not None}
 
-        request = self.discovery.SEARCH.build_request(self.client.base_url, query=params)
+        request = self.discovery.SEARCH.build_request(self.client.base_url, query=query)
         search_results = await self.client.handle_request(request)
 
         if len(search_results) > 0:
@@ -120,13 +131,22 @@ class AsyncCompuGlobalAPI:
 
         raise NoSearchResultsFoundError
 
-    async def search_for_screencap(self, search_text: str) -> Screencap:
+    async def search_for_screencap(
+        self,
+        search_text: str,
+        season_minimum: int | None = None,
+        season_maximum: int | None = None,
+    ) -> Screencap:
         """Perform a search of the given search text and returns the top result.
 
         Parameters
         ----------
         search_text : str
             The search text to query
+        season_minimum: int | None, optional
+            The minimum season allowed in the search
+        season_maximum: int | None, optional
+            The maximum season allowed in the search
 
         Returns
         -------
@@ -134,11 +154,15 @@ class AsyncCompuGlobalAPI:
             The screencap of the top search result
 
         """
-        search_results = await self.search(search_text)
+        search_results = await self.search(search_text, season_minimum=season_minimum, season_maximum=season_maximum)
         result = search_results[0]
         return await self.get_screencap(result.key, result.timestamp)
 
-    async def get_random_screencap(self) -> Screencap:
+    async def get_random_screencap(
+        self,
+        season_minimum: int | None = None,
+        season_maximum: int | None = None,
+    ) -> Screencap:
         """Get a random TV Show screencap.
 
         Returns
@@ -147,7 +171,9 @@ class AsyncCompuGlobalAPI:
             A random screencap object.
 
         """
-        request = self.discovery.RANDOM.build_request(self.client.base_url)
+        optional_params = {"smin": season_minimum, "smax": season_maximum}
+        query = {k: v for k, v in optional_params.items() if v is not None}
+        request = self.discovery.RANDOM.build_request(self.client.base_url, query=query)
         random = await self.client.handle_request(request)
         return Screencap.model_validate(random)
 

{compuglobal-0.3.6 → compuglobal-0.3.8}/compuglobal/api/discovery.py

@@ -26,7 +26,7 @@ class DiscoveryAPI:
     CAPTION = Endpoint(
         path="/api/caption",
         method=RequestMethod.GET,
-        query_params=frozenset({"e", "t", "nearby"}),
+        required_query_params=frozenset({"e", "t", "nearby"}),
     )
 
     DISCOVER = Endpoint(
@@ -37,6 +37,7 @@ class DiscoveryAPI:
     RANDOM = Endpoint(
         path="/api/random",
         method=RequestMethod.GET,
+        optional_query_params=frozenset({"smin", "smax"}),
     )
 
     NAVIGATOR = Endpoint(
@@ -47,7 +48,8 @@ class DiscoveryAPI:
     SEARCH = Endpoint(
         path="/api/search",
         method=RequestMethod.GET,
-        query_params=frozenset({"q"}),
+        required_query_params=frozenset({"q"}),
+        optional_query_params=frozenset({"smin", "smax"}),
     )
 
     FRAMES = Endpoint(

{compuglobal-0.3.6 → compuglobal-0.3.8}/compuglobal/api/endpoint.py

@@ -52,11 +52,13 @@ class Endpoint:
     Attributes
     ----------
     path: str
-        The url path
+        The url path containing any path parameter names
     method: RequestMethod, optional
         The HTTP RequestMethod for the request (GET/POST/PUT)
-    query_params: dict[str, Any] | None, optional
-        The query parameters to use in the request
+    required_query_params: dict[str, Any] | None, optional
+        The required query parameters to use in the request
+    optional_query_params: dict[str, Any] | None, optional
+        Optional query params that can be used in the request
     body_model: type[BaseModel], optional
         The pydantic model for the json body
 
@@ -64,7 +66,8 @@ class Endpoint:
 
     path: str
     method: RequestMethod = RequestMethod.GET
-    query_params: frozenset[str] = frozenset()
+    required_query_params: frozenset[str] = frozenset()
+    optional_query_params: frozenset[str] = frozenset()
     body_model: type[BaseModel] | None = None
 
     def build_url(
@@ -178,8 +181,8 @@ class Endpoint:
             Raises error if contains missing or unexpected params from the definition of the endpoint
 
         """
-        missing = set(self.query_params - query.keys())
-        unexpected = query.keys() - self.query_params
+        missing = set(self.required_query_params - query.keys())
+        unexpected = query.keys() - (self.required_query_params | self.optional_query_params)
 
         if missing:
             raise ValueError(

{compuglobal-0.3.6 → compuglobal-0.3.8}/compuglobal/api/media.py

@@ -33,13 +33,13 @@ class MediaAPI:
     COMIC_PANEL = Endpoint(
         path="/comic/img",
         method=RequestMethod.GET,
-        query_params=frozenset({"b64"}),
+        required_query_params=frozenset({"b64"}),
     )
 
     COMIC_STRIP = Endpoint(
         path="/comic/img",
         method=RequestMethod.GET,
-        query_params=frozenset({"b64", "layout"}),
+        required_query_params=frozenset({"b64", "layout"}),
     )
 
     RENDER_GIF = Endpoint(
@@ -56,7 +56,7 @@ class MediaAPI:
     DETECT_LOOP = Endpoint(
         path="/api/detect-loop",
         method=RequestMethod.GET,
-        query_params=frozenset(
+        required_query_params=frozenset(
             {"episode", "start", "end"},
         ),
     )

{compuglobal-0.3.6 → compuglobal-0.3.8}/compuglobal/api/metadata.py

@@ -23,5 +23,5 @@ class MetadataAPI:
     TRANSCRIPT = Endpoint(
         path="/api/transcript",
         method=RequestMethod.GET,
-        query_params=frozenset({"e", "t"}),
+        required_query_params=frozenset({"e", "t"}),
     )

{compuglobal-0.3.6 → compuglobal-0.3.8}/compuglobal/models/frame.py

@@ -3,6 +3,7 @@
 from pydantic import Field
 
 from compuglobal.models.base import BaseCompuGlobalModel
+from compuglobal.models.timestamp import Timestamp
 
 
 class Frame(BaseCompuGlobalModel):
@@ -32,10 +33,7 @@ class Frame(BaseCompuGlobalModel):
             A readable timestamp for the frame in format `mm:ss`.
 
         """
-        seconds = int(self.timestamp / 1000)
-        minutes = int(seconds / 60)
-        seconds -= minutes * 60
-        return f"{minutes}:{seconds:02d}"
+        return Timestamp.get_real_timestamp(timestamp=self.timestamp)
 
     def __str__(self) -> str:
         """Get the string representation of the Frame.

{compuglobal-0.3.6 → compuglobal-0.3.8}/compuglobal/models/screencap.py

@@ -6,6 +6,7 @@ from compuglobal.models.base import BaseCompuGlobalModel
 from compuglobal.models.episode import EpisodeMetadata
 from compuglobal.models.frame import Frame
 from compuglobal.models.subtitle import Subtitle
+from compuglobal.models.timestamp import Timestamp
 
 
 class ScreencapMoment(BaseCompuGlobalModel):
@@ -29,6 +30,17 @@ class ScreencapMoment(BaseCompuGlobalModel):
     content: str = Field(alias="Content")
     title: str = Field(alias="Title")
 
+    def get_real_timestamp(self) -> str:
+        """Get a readable timestamp for the moments timestamp in format `mm:ss`.
+
+        Returns
+        -------
+        str
+            A readable timestamp in format `mm:ss`.
+
+        """
+        return Timestamp.get_real_timestamp(self.timestamp)
+
 
 class Screencap(BaseCompuGlobalModel):
     """A Screencap of an episode at a point in time of a TV Show.
@@ -58,7 +70,7 @@ class Screencap(BaseCompuGlobalModel):
     max_timestamp: int = Field(alias="MaxTimestamp", ge=0)
 
     def get_real_timestamp(self) -> str:
-        """Get a readable timestamp for the frame in format "mm:ss".
+        """Get a readable timestamp for the frame in format `mm:ss`.
 
         Returns
         -------
@@ -66,10 +78,21 @@ class Screencap(BaseCompuGlobalModel):
             A readable timestamp for the frame in format `mm:ss`.
 
         """
-        return self.frame.get_real_timestamp()
+        return Timestamp.get_real_timestamp(timestamp=self.frame.timestamp)
+
+    def get_duration(self) -> int:
+        """Get duration of screencap subtitles in milliseconds.
+
+        Returns
+        -------
+        int
+            Duration in milliseconds
+
+        """
+        return Timestamp.get_subtitles_duration(self.subtitles)
 
     def captions(self) -> list[str]:
-        """Get a list of captions for the screencap from all subttiles.
+        """Get a list of captions for the screencap from all subtitles.
 
         Returns
         -------

{compuglobal-0.3.6 → compuglobal-0.3.8}/compuglobal/models/subtitle.py

@@ -3,6 +3,7 @@
 from pydantic import Field
 
 from compuglobal.models.base import BaseCompuGlobalModel
+from compuglobal.models.timestamp import Timestamp
 
 
 class Subtitle(BaseCompuGlobalModel):
@@ -41,7 +42,7 @@ class Subtitle(BaseCompuGlobalModel):
         Returns
         -------
         int
-            The duration in milliseonds.
+            The duration in milliseconds.
 
         """
-        return self.end_timestamp - self.start_timestamp
+        return Timestamp.get_duration(start_timestamp=self.start_timestamp, end_timestamp=self.end_timestamp)

compuglobal-0.3.8/compuglobal/models/timestamp.py

@@ -0,0 +1,76 @@
+"""Timestamp module with helper class for working with timestamps."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from compuglobal.models.subtitle import Subtitle
+
+
+class Timestamp:
+    """Helper class for working with timestamps."""
+
+    @staticmethod
+    def get_minutes_seconds(milliseconds: int) -> tuple[int, int]:
+        """Get minutes and seconds from milliseconds.
+
+        Parameters
+        ----------
+        milliseconds : int
+            The length of time in milliseconds
+
+        Returns
+        -------
+        tuple[int, int]
+            The minutes, and seconds as a tuple
+
+        """
+        seconds = int(milliseconds / 1000)
+        minutes = int(seconds / 60)
+        seconds -= minutes * 60
+        return minutes, seconds
+
+    @staticmethod
+    def get_real_timestamp(timestamp: int) -> str:
+        """Get a readable timestamp for the frame in format `mm:ss`.
+
+        Returns
+        -------
+        str
+            A readable timestamp for the frame in format `mm:ss`.
+
+        """
+        minutes, seconds = Timestamp.get_minutes_seconds(timestamp)
+        return f"{minutes}:{seconds:02d}"
+
+    @staticmethod
+    def get_duration(start_timestamp: int, end_timestamp: int) -> int:
+        """Get the duration of the subtitle in milliseconds.
+
+        Returns
+        -------
+        int
+            The duration in milliseconds.
+
+        """
+        return end_timestamp - start_timestamp
+
+    @staticmethod
+    def get_subtitles_duration(subtitles: list[Subtitle]) -> int:
+        """Get the duration between the start of the earliest subtitle, and the end of the latest subtitle.
+
+        Parameters
+        ----------
+        subtitles : list[Subtitle]
+            The subtitles
+
+        Returns
+        -------
+        int
+            The duration in milliseconds
+
+        """
+        start_timestamp = min(subtitle.start_timestamp for subtitle in subtitles)
+        end_timestamp = max(subtitle.end_timestamp for subtitle in subtitles)
+        return Timestamp.get_duration(start_timestamp, end_timestamp)

{compuglobal-0.3.6 → compuglobal-0.3.8}/pyproject.toml

@@ -12,7 +12,7 @@ license = "MIT"
 requires-python = ">=3.13"
 dynamic = ["version", "description"]
 dependencies = [
-    "aiohttp>=3.13.0", "pydantic>=2.13.0"
+    "aiohttp>=3.14.0", "pydantic>=2.13.0"
 ]
 classifiers = [
     "Programming Language :: Python :: 3.13",