Add support for individual participant event endpoint

Author: JamesMCo

README.md

@@ -1,7 +1,7 @@
 # Python MCC API
 
 [![🐍 PyPI](https://img.shields.io/pypi/v/mcc-api?label=🐍%20PyPI)](https://pypi.org/project/mcc-api/)
-[![👑 Targeting Event API v1.4.0](https://img.shields.io/badge/👑_Targeting_Event_API-v1.4.0-red)](https://github.com/Noxcrew/mcchampionship-api/releases/tag/v1.4.0)
+[![👑 Targeting Event API v1.5.0](https://img.shields.io/badge/👑_Targeting_Event_API-v1.5.0-red)](https://github.com/Noxcrew/mcchampionship-api/releases/tag/v1.5.0)
 [![🏝️ Targeting Island API v24.05.06](https://img.shields.io/badge/🏝️_Targeting_Island_API-v24.05.06-aqua)](https://github.com/Noxcrew/mccisland-api/releases/tag/v24.05.06)
 
 A helper library for the [MC Championship](https://mcchampionship.com) APIs

docs/index.rst

@@ -4,9 +4,9 @@ python_mcc_api
 .. image:: https://img.shields.io/pypi/v/mcc-api?label=🐍%20PyPI
    :alt: 🐍 PyPI
    :target: https://pypi.org/project/mcc-api/
-.. image:: https://img.shields.io/badge/👑_Targeting_Event_API-v1.4.0-red
-   :alt: 👑 Targeting Event API v1.4.0
-   :target: https://github.com/Noxcrew/mcchampionship-api/releases/tag/v1.4.0
+.. image:: https://img.shields.io/badge/👑_Targeting_Event_API-v1.5.0-red
+   :alt: 👑 Targeting Event API v1.5.0
+   :target: https://github.com/Noxcrew/mcchampionship-api/releases/tag/v1.5.0
 .. image:: https://img.shields.io/badge/🏝️_Targeting_Island_API-v24.05.06-aqua
    :alt: 🏝️ Targeting Island API v24.05.06
    :target: https://github.com/Noxcrew/mccisland-api/releases/tag/v24.05.06

mcc_api/__init__.py

@@ -4,5 +4,8 @@
     "__version__"
 ]
 
-__version__ = "1.1.4"
+__version__ = "1.1.5"
 __user_agent: t.Final[str] = f"python_mcc_api/{__version__} (https://github.com/JamesMCo/python_mcc_api)"
+
+# update version of package
+# update targeted api version

mcc_api/event/__init__.py

@@ -8,6 +8,7 @@
     EventsResponse,
     HallOfFameGameResponse,
     HallOfFameResponse,
+    ParticipantResponse,
     ParticipantsResponse,
     ParticipantsTeamResponse,
     RundownResponse
@@ -129,6 +130,20 @@ def get_rundown(event: t.Optional[str] = None, *, timeout: int = 5) -> RundownRe
         return RundownResponse(__request("rundown", timeout))
 
 
+def get_participant(uuid: str, *, timeout: int = 5) -> ParticipantResponse:
+    """Get an individual participant in the current event cycle by their Minecraft UUID.
+
+    - Accepts both dashed (e.g. 3e7a89ee-c4e2-4392-a317-444b861b0794) and un-dashed
+      (e.g. 3e7a89eec4e24392a317444b861b0794) UUIDs
+    - Calls the `/participant <https://api.mcchampionship.com/docs/#/v1/AppController_getParticipant>`_ endpoint.
+    - Returns an :class:`mcc_api.ParticipantResponse` representing the individual participant in the current event
+      cycle's event.
+    - May raise a :class:`requests.Timeout` exception, with the number of seconds before timing out specified by the
+      `timeout` parameter and defaulting to 5.
+    """
+    return ParticipantResponse(__request(f"participant/{uuid}", timeout))
+
+
 @t.overload
 def get_participants(*, timeout: int = 5) -> ParticipantsResponse: ...
 @t.overload

mcc_api/event/exceptions.py

@@ -26,6 +26,10 @@ class InvalidGameError(MCCAPIError):
     pass
 
 
+class InvalidParticipantError(MCCAPIError):
+    """Exception raised when the requested participant does not exist."""
+    pass
+
 class InvalidTeamError(MCCAPIError):
     """Exception raised when the requested team does not exist."""
     pass

mcc_api/event/responses.py

@@ -1,4 +1,4 @@
-from .exceptions import InvalidEventError, InvalidGameError, InvalidTeamError, RateLimitError
+from .exceptions import InvalidEventError, InvalidGameError, InvalidParticipantError, InvalidTeamError, RateLimitError
 from .enums import Game, Team
 from dataclasses import dataclass
 from datetime import datetime
@@ -323,6 +323,27 @@ class Creator:
     """The team of the participant."""
 
 
+class ParticipantResponse(BaseResponse):
+    """Response object representing an individual participant in the current event cycle."""
+
+    data: Creator
+
+    def __init__(self: "ParticipantResponse", request: requests.Response | dict[str, t.Any]) -> None:
+        data: dict[str, t.Any] = super()._extract_json_data(request)
+        super().__init__(data)
+
+        if self.code == 404:
+            raise InvalidParticipantError(self.code, self.reason)
+
+        self.data = Creator(
+            username=data["data"]["username"],
+            uuid=data["data"]["uuid"],
+            stream=data["data"]["stream"],
+            icon=data["data"]["icon"],
+            team=Team(data["data"]["team"])
+        )
+
+
 class ParticipantsResponse(BaseResponse):
     """Response object representing all teams and their participants in the current event cycle."""
 

tests/event/mock_data/200_participant.json

@@ -0,0 +1,11 @@
+{
+    "code": 200,
+    "data":
+    {
+        "username": "Noxite",
+        "uuid": "3e7a89eec4e24392a317444b861b0794",
+        "stream": "https://twitch.tv/thenoxcrew",
+        "icon": "https://static-cdn.jtvnw.net/jtv_user_pictures/a5ba63c7-923b-460c-87b0-1917e7a95ab9-profile_image-50x50.png?u=1",
+        "team": "SPECTATORS"
+    }
+}

tests/event/mock_data/404_participant.json

@@ -0,0 +1,4 @@
+{
+    "status": 404,
+    "reason": "Not Found - Participant not found"
+}

tests/event/test_participants.py

@@ -4,6 +4,36 @@
 import unittest
 
 
+class TestEventParticipant200(unittest.TestCase):
+    response_json: dict[str, t.Any]
+    response_object: event_api.ParticipantResponse
+
+    def setUp(self: "TestEventParticipant200") -> None:
+        with open("event/mock_data/200_participant.json") as f:
+            f: t.TextIO
+            self.response_json = json.loads(f.read())
+        self.response_object = event_api.ParticipantResponse(self.response_json)
+
+    def test_creator_returned(self: "TestEventParticipant200") -> None:
+        self.assertIsInstance(self.response_object.data, event_api.responses.Creator)
+
+
+class TestParticipantEndpoint404(unittest.TestCase):
+    def test_participant_invalid_team_exception(self: "TestParticipantEndpoint404") -> None:
+        with open("event/mock_data/404_participant.json") as f:
+            f: t.TextIO
+            response_json: dict[str, t.Any] = json.loads(f.read())
+        self.assertRaises(event_api.exceptions.InvalidParticipantError, event_api.ParticipantResponse, response_json)
+
+
+class TestParticipantEndpoint429(unittest.TestCase):
+    def test_participant_ratelimit_exception(self: "TestParticipantEndpoint429") -> None:
+        with open("event/mock_data/429_ratelimit.json") as f:
+            f: t.TextIO
+            response_json: dict[str, t.Any] = json.loads(f.read())
+        self.assertRaises(event_api.exceptions.RateLimitError, event_api.ParticipantResponse, response_json)
+
+
 class TestEventParticipants200(unittest.TestCase):
     response_json: dict[str, t.Any]
     response_object: event_api.ParticipantsResponse