ctftime-api 0.1.0__tar.gz → 0.1.2__tar.gz

{ctftime_api-0.1.0 → ctftime_api-0.1.2}/PKG-INFO

@@ -1,14 +1,16 @@
 Metadata-Version: 2.3
 Name: ctftime_api
-Version: 0.1.0
+Version: 0.1.2
 Summary: CTFTime API wrapper
 Keywords: ctftime,api,wrapper
 Author: John Toniutti
 Author-email: john.toniutti@gmail.com
 Requires-Python: >=3.11
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
+Classifier: Framework :: Pydantic
+Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12

{ctftime_api-0.1.0 → ctftime_api-0.1.2}/ctftime_api/client.py

@@ -1,14 +1,15 @@
 from datetime import datetime
+from typing import Any
 
 import httpx
-from httpx import URL
+from httpx import URL, Timeout
 
 from pydantic_extra_types.country import CountryAlpha2
 
+from ctftime_api.models.vote import Vote
 from ctftime_api.models.event import Event, EventResult
 from ctftime_api.models.team import TeamRank, Team, TeamComplete
 
-
 __all__ = ["CTFTimeClient"]
 
 
@@ -26,6 +27,18 @@ class CTFTimeClient:
             self._client = httpx.AsyncClient(*args, **kwargs)
         self._base_url = URL("https://ctftime.org/api/v1/")
 
+    async def _get(self, url: str | URL, **kwargs) -> Any:
+        """
+        Perform a GET request.
+        :param url: The url to make the request to.
+        :param kwargs: Additional arguments to pass to the request.
+        :return: The response JSON.
+        :raise httpx.HTTPStatusError: If the response status code is not successful.
+        """
+        response = await self._client.get(url, **kwargs)
+        response.raise_for_status()
+        return response.json()
+
     async def close(self):
         """Close the underlying httpx.AsyncClient."""
         await self._client.aclose()
@@ -38,16 +51,16 @@ class CTFTimeClient:
         :param year: The year to get the top teams for. If None, the current year will be used.
         :param limit: The number of teams to get.
         :return: A list of the top teams.
+        :raise httpx.HTTPStatusError: If the response status code is not successful.
         """
         if year is None:
             url = self._base_url.join("top/")
             year = datetime.now().year
         else:
             url = self._base_url.join(f"top/{year}/")
-        response = await self._client.get(url, params={"limit": limit})
-        response.raise_for_status()
 
-        teams = response.json().get(f"{year}", [])
+        response: dict[str, list[dict]] = await self._get(url, params={"limit": limit})
+        teams = response.get(f"{year}", [])
 
         return [TeamRank.model_validate(team) for team in teams]
 
@@ -59,6 +72,8 @@ class CTFTimeClient:
         :param country: The country to get the top teams for.
             It can be a pycountry Country object or a two-letter country code.
         :return: A list of the top teams.
+        :raise httpx.HTTPStatusError: If the response status code is not successful.
+        :raise ValueError: If the country is not a two-letter country code or a pycountry Country object.
         """
         if isinstance(country, CountryAlpha2):
             country = country
@@ -69,10 +84,7 @@ class CTFTimeClient:
                 )
 
         url = self._base_url.join("top-by-country/").join(f"{country}/")
-        response = await self._client.get(url)
-        response.raise_for_status()
-
-        teams = response.json()
+        teams: list[dict[str, Any]] = await self._get(url)
 
         return [TeamRank.model_validate(team) for team in teams]
 
@@ -87,6 +99,8 @@ class CTFTimeClient:
             It can be a Unix timestamp or a datetime object.
         :param limit: The number of events to get.
         :return: A list of events.
+        :raise httpx.HTTPStatusError: If the response status code is not successful.
+        :raise ValueError: If the start date is after the end date.
         """
         if isinstance(start, datetime):
             start = int(start.timestamp())
@@ -97,12 +111,9 @@ class CTFTimeClient:
             raise ValueError("The start date must be before the end date.")
 
         url = self._base_url.join("events/")
-        response = await self._client.get(
+        events: list[dict[str, Any]] = await self._get(
             url, params={"start": start, "finish": end, "limit": limit}
         )
-        response.raise_for_status()
-
-        events = response.json()
 
         return [Event.model_validate(event) for event in events]
 
@@ -111,12 +122,10 @@ class CTFTimeClient:
         Get information about a specific event.
         :param event_id: The ID of the event.
         :return: The event information.
+        :raise httpx.HTTPStatusError: If the response status code is not successful.
         """
         url = self._base_url.join(f"events/{event_id}/")
-        response = await self._client.get(url)
-        response.raise_for_status()
-
-        event = response.json()
+        event: dict[str, Any] = await self._get(url)
 
         return Event.model_validate(event)
 
@@ -128,14 +137,14 @@ class CTFTimeClient:
         :param limit: The number of teams to get.
         :param offset: The offset to start from.
         :return: A list of teams.
+        :raise httpx.HTTPStatusError: If the response status code is not successful.
         """
         url = self._base_url.join("teams/")
-        response = await self._client.get(
+
+        response: dict[str, Any] = await self._get(
             url, params={"limit": limit, "offset": offset}
         )
-        response.raise_for_status()
-
-        teams = response.json().get("results", [])
+        teams: list[dict[str, Any]] = response.get("results", [])
 
         return [Team.model_validate(team) for team in teams]
 
@@ -144,12 +153,10 @@ class CTFTimeClient:
         Get information about a specific team.
         :param team_id: The ID of the team.
         :return: The team information.
+        :raise httpx.HTTPStatusError: If the response status code is not successful.
         """
         url = self._base_url.join(f"teams/{team_id}/")
-        response = await self._client.get(url)
-        response.raise_for_status()
-
-        team = response.json()
+        team: dict[str, Any] = await self._get(url)
 
         return TeamComplete.model_validate(team)
 
@@ -161,18 +168,39 @@ class CTFTimeClient:
         :param year: The year to get the results for.
             If None, the current year will be used.
         :return: A dictionary of event results.
+        :raise httpx.HTTPStatusError: If the response status code is not successful.
         """
         if year is None:
             url = self._base_url.join("results/")
         else:
             url = self._base_url.join(f"results/{year}/")
 
-        response = await self._client.get(url)
-        response.raise_for_status()
-
-        event = response.json()
+        event: dict[str, dict] = await self._get(url)
 
         return {
-            int(ctf_id): EventResult(**result, ctf_id=ctf_id)
+            int(ctf_id): EventResult(**result, ctf_id=int(ctf_id))
             for ctf_id, result in event.items()
         }
+
+    async def get_votes_per_year(
+        self, year: int | None, timeout: Timeout | int | float | None = None
+    ) -> list[Vote]:
+        """
+        Get the votes for a specific year.
+        This API call may take a long time to complete.
+        :param year: The year to get the votes for or None for the current year.
+        :param timeout: The timeout for the request.
+            If None, the session timeout will be used.
+        :return: A list of votes.
+        :raise httpx.HTTPStatusError: If the response status code is not successful.
+        """
+        if year is None:
+            year = datetime.now().year
+
+        if timeout is None:
+            timeout = self._client.timeout
+
+        url = self._base_url.join(f"votes/{year}/")
+        votes: list[dict] = await self._get(url, timeout=timeout)
+
+        return [Vote(**vote) for vote in votes]

ctftime_api-0.1.2/ctftime_api/models/vote.py

@@ -0,0 +1,14 @@
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+__all__ = ["Vote"]
+
+
+class Vote(BaseModel):
+    event_id: int
+    user_id: int
+    user_teams: list[int]  # list of team IDs
+    weight: str
+    creation_date: datetime

{ctftime_api-0.1.0 → ctftime_api-0.1.2}/pyproject.toml

@@ -1,15 +1,17 @@
 [project]
 name = "ctftime_api"
-version = "0.1.0"
+version = "0.1.2"
 description = "CTFTime API wrapper"
 authors = [
     {name = "John Toniutti",email = "john.toniutti@gmail.com"}
 ]
 keywords = ["ctftime", "api", "wrapper"]
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)",
+    "Framework :: Pydantic",
+    "Operating System :: OS Independent",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",