Habiticalib 0.2.0a0__py3-none-any.whl → 0.2.0a1__py3-none-any.whl

habiticalib/__init__.py

@@ -16,6 +16,7 @@ from .types import (
     HabiticaClass,
     HabiticaClassSystemResponse,
     HabiticaErrorResponse,
+    HabiticaGroupMembersResponse,
     HabiticaLoginResponse,
     HabiticaResponse,
     HabiticaScoreResponse,
@@ -49,6 +50,7 @@ __all__ = [
     "HabiticaClassSystemResponse",
     "HabiticaErrorResponse",
     "HabiticaException",
+    "HabiticaGroupMembersResponse",
     "HabiticaLoginResponse",
     "HabiticaResponse",
     "HabiticaScoreResponse",

habiticalib/const.py

@@ -1,6 +1,6 @@
 """Constants for Habiticalib."""
 
-__version__ = "0.2.0a0"
+__version__ = "0.2.0a1"
 
 DEFAULT_URL = "https://habitica.com/"
 ASSETS_URL = "https://habitica-assets.s3.amazonaws.com/mobileApp/images/"
@@ -14,3 +14,5 @@ BACKER_ONLY_GEAR = {
     "shield_special_ks2019": "BackerOnly-Equip-MythicGryphonShield.gif",
     "weapon_special_ks2019": "BackerOnly-Equip-MythicGryphonGlaive.gif",
 }
+
+PAGE_LIMIT = 60

habiticalib/lib.py

@@ -12,7 +12,7 @@ from aiohttp import ClientError, ClientResponseError, ClientSession
 from PIL import Image
 from yarl import URL
 
-from .const import ASSETS_URL, BACKER_ONLY_GEAR, DEFAULT_URL
+from .const import ASSETS_URL, BACKER_ONLY_GEAR, DEFAULT_URL, PAGE_LIMIT
 from .exceptions import (
     BadRequestError,
     NotAuthorizedError,
@@ -32,7 +32,9 @@ from .types import (
     HabiticaClass,
     HabiticaClassSystemResponse,
     HabiticaErrorResponse,
+    HabiticaGroupMembersResponse,
     HabiticaLoginResponse,
+    HabiticaQuestResponse,
     HabiticaResponse,
     HabiticaScoreResponse,
     HabiticaSleepResponse,
@@ -849,7 +851,7 @@ class Habitica:
         if target_id:
             params.update({"targetId": str(target_id)})
         return HabiticaUserResponse.from_json(
-            await self._request("post", url=url, json=params),
+            await self._request("post", url=url, params=params),
         )
 
     async def toggle_sleep(
@@ -1281,6 +1283,443 @@ class Habitica:
             await self._request("post", url=url, json=json),
         )
 
+    async def get_group_members(
+        self,
+        group_id: UUID | None = None,
+        *,
+        limit: int | None = None,
+        tasks: bool = False,
+        public_fields: bool = False,
+        last_id: UUID | None = None,
+    ) -> HabiticaGroupMembersResponse:
+        """Get members of the party or a specific group.
+
+        This method retrieves a list of members for a party or a specified group
+        from the Habitica API. Additional options allow including tasks or public
+        through results if necessary to collect all members. If the API rate limit is
+        exceeded, the method will pause for the duration specified in the `retry-after`
+        header and retry the request.
+
+
+        Parameters
+        ----------
+        group_id : UUID, optional
+            The UUID of the group. Defaults to the user's party if not specified.
+        limit : int, optional
+            Maximum number of members per request (default: 30, max: 60).
+        tasks : bool, optional
+            Whether to include tasks associated with the group.
+        public_fields : bool, optional
+            Whether to include all public fields for group members.
+        last_id : UUID, optional
+            For paginated requests, the UUID of the last member retrieved.
+
+        Returns
+        -------
+        HabiticaGroupMembersResponse
+            A response object containing the group member data.
+
+        Raises
+        ------
+        aiohttp.ClientResponseError
+            For HTTP-related errors, such as HTTP 400 or 500 response status.
+        aiohttp.ClientConnectionError
+            If the connection to the API fails.
+        aiohttp.ClientError
+            For any other exceptions raised by aiohttp during the request.
+        TimeoutError
+            If the connection times out.
+
+        Examples
+        --------
+        >>> members_response = await habitica.get_group_members()
+        >>> for member in members_response.data:
+        ...     print(member.profile.name)
+        """
+
+        if limit is not None and (limit < 1 or limit > PAGE_LIMIT):
+            msg = f"The 'limit' parameter must be between 1 and {PAGE_LIMIT}."
+            raise ValueError(msg)
+
+        group = "party" if not group_id else str(group_id)
+        url = self.url / "api/v3/groups" / group / "members"
+
+        params: dict[str, str | int] = {}
+
+        if tasks:
+            params["includeTasks"] = "true"
+        if public_fields:
+            params["includeAllPublicFields"] = "true"
+        if last_id:
+            params["lastId"] = str(last_id)
+        if limit:
+            params["limit"] = limit
+
+        while True:
+            try:
+                response = HabiticaGroupMembersResponse.from_json(
+                    await self._request("get", url=url, params=params),
+                )
+                break
+            except TooManyRequestsError as e:
+                await asyncio.sleep(e.retry_after)
+
+        if len(response.data) == limit:
+            next_page = await self.get_group_members(
+                group_id=group_id,
+                limit=limit,
+                tasks=tasks,
+                public_fields=public_fields,
+                last_id=response.data[-1].id,
+            )
+            response.data.extend(next_page.data)
+
+        return response
+
+    async def abort_quest(self, group_id: UUID | None = None) -> HabiticaQuestResponse:
+        """Abort an active quest for the party or a specific group.
+
+        Prematurely terminates an ongoing quest, causing all progress to be lost.
+        The quest scroll will be returned to the owner's inventory.
+        Only the quest leader or group leader is allowed to perform this action.
+
+        Parameters
+        ----------
+        group_id : UUID, optional
+            The UUID of the specific group whose quest should be aborted.
+            Defaults to the user's party if not specified.
+
+        Returns
+        -------
+        HabiticaQuestResponse
+            A response object containing updated quest data of the group or party.
+
+        Raises
+        ------
+        NotFoundError
+            If the specified group or quest could not be found.
+        NotAuthorizedError
+            If the user does not have permission to abort the quest.
+        aiohttp.ClientResponseError
+            For HTTP-related errors, such as HTTP 400 or 500 response status.
+        aiohttp.ClientConnectionError
+            If the connection to the API fails.
+        aiohttp.ClientError
+            For any other exceptions raised by aiohttp during the request.
+        TimeoutError
+            If the connection times out.
+
+        Examples
+        --------
+        Abort the party's current quest:
+        >>> response = await habitica.abort_quest()
+        >>> print(response.success)  # True if the quest was successfully aborted.
+
+        Abort a quest for a specific group:
+        >>> group_id = UUID("12345678-1234-5678-1234-567812345678")
+        >>> response = await habitica.abort_quest(group_id)
+        >>> print(response.success)  # True if the quest was successfully aborted.
+        """
+        group = "party" if not group_id else str(group_id)
+        url = self.url / "api/v3/groups" / group / "quests/abort"
+
+        return HabiticaQuestResponse.from_json(
+            await self._request("post", url=url),
+        )
+
+    async def accept_quest(self, group_id: UUID | None = None) -> HabiticaQuestResponse:
+        """Accept a pending invitation to a quest from the party or a specific group.
+
+        Allows a user to accept an invitation to participate in a quest within a
+        specified group.
+
+        Parameters
+        ----------
+        group_id : UUID, optional
+            The UUID of the group for which the quest invitation is being accepted.
+            Defaults to the user's party if not specified.
+
+
+        Returns
+        -------
+        HabiticaQuestResponse
+            A response object containing updated quest data of the group or party.
+
+        Raises
+        ------
+        NotFoundError
+            If the specified group or quest could not be found.
+        aiohttp.ClientResponseError
+            Raised for HTTP-related errors, such as HTTP 400 or 500 response status.
+        aiohttp.ClientConnectionError
+            If the connection to the API fails.
+        aiohttp.ClientError
+            Raised for any other exceptions encountered by `aiohttp` during the request.
+        TimeoutError
+            If the connection to the API times out.
+
+        Examples
+        --------
+        Accept a pending quest invitation from the party:
+        >>> response = await habitica.accept_quest()
+        >>> print(response.success)  # True if the quest invitation was successfully accepted.
+        """
+        group = "party" if not group_id else str(group_id)
+        url = self.url / "api/v3/groups" / group / "quests/accept"
+
+        return HabiticaQuestResponse.from_json(
+            await self._request("post", url=url),
+        )
+
+    async def reject_quest(self, group_id: UUID | None = None) -> HabiticaQuestResponse:
+        """Reject a pending quest invitation from the party or a specific group.
+
+        Allows a user to reject an invitation to participate in a quest within a
+        specified group. The user will not join the quest and will be excluded from
+        its progress and rewards.
+
+        Parameters
+        ----------
+        group_id : UUID, optional
+            The UUID of the group for which the quest invitation is being rejected.
+            Defaults to the user's party if not specified.
+
+
+        Returns
+        -------
+        HabiticaQuestResponse
+            A response object containing updated quest data of the group or party.
+
+        Raises
+        ------
+        NotFoundError
+            If the specified group or quest could not be found.
+        aiohttp.ClientResponseError
+            Raised for HTTP-related errors, such as HTTP 400 or 500 response status.
+        aiohttp.ClientConnectionError
+            If the connection to the API fails.
+        aiohttp.ClientError
+            Raised for any other exceptions encountered by `aiohttp` during the request.
+        TimeoutError
+            If the connection to the API times out.
+
+        Examples
+        --------
+        Reject a pending quest invitation from the party:
+        >>> response = await habitica.reject_quest()
+        >>> print(response.success)  # True if the quest invitation was successfully rejected.
+
+        Reject a pending quest invitation from a specific group:
+        >>> group_id = UUID("12345678-1234-5678-1234-567812345678")
+        >>> response = await habitica.reject_quest(group_id)
+        >>> print(response.success)  # True if the quest invitation was successfully rejected.
+        """
+        group = "party" if not group_id else str(group_id)
+        url = self.url / "api/v3/groups" / group / "quests/reject"
+
+        return HabiticaQuestResponse.from_json(
+            await self._request("post", url=url),
+        )
+
+    async def cancel_quest(self, group_id: UUID | None = None) -> HabiticaQuestResponse:
+        """Cancel a pending quest for the party or a specific group.
+
+        Cancel a quest that has not yet startet. All accepted and pending invitations
+        will be canceled and the quest roll returned to the owner's inventory.
+        Only quest leader or group leader can perform this action.
+
+        Parameters
+        ----------
+        group_id : UUID, optional
+            The UUID of the group for which the quest is being canceled.
+            Defaults to the user's party if not specified.
+
+        Returns
+        -------
+        HabiticaQuestResponse
+            A response object containing details about the canceled quest.
+
+        Raises
+        ------
+        NotFoundError
+            If the specified group or quest could not be found.
+        NotAuthorizedError
+            If the user does not have permission to cancel the quest.
+        aiohttp.ClientResponseError
+            Raised for HTTP-related errors, such as HTTP 400 or 500 response status.
+        aiohttp.ClientConnectionError
+            If the connection to the API fails.
+        aiohttp.ClientError
+            Raised for any other exceptions encountered by `aiohttp` during the request.
+        TimeoutError
+            If the connection to the API times out.
+
+        Examples
+        --------
+        Cancel a pending quest for the party:
+        >>> response = await habitica.cancel_quest()
+        >>> print(response.success)  # True if the quest was successfully canceled.
+        """
+        group = "party" if not group_id else str(group_id)
+        url = self.url / "api/v3/groups" / group / "quests/cancel"
+
+        return HabiticaQuestResponse.from_json(
+            await self._request("post", url=url),
+        )
+
+    async def start_quest(self, group_id: UUID | None = None) -> HabiticaQuestResponse:
+        """Force-start a quest for the party or a specific group.
+
+        Begins a quest immediately, bypassing any pending invitations that haven't been
+        accepted or rejected.
+        Only quest leader or group leader can perform this action.
+
+        Parameters
+        ----------
+        group_id : UUID, optional
+            The UUID of the group for which the quest should be started.
+            Defaults to the user's party if not specified.
+
+
+        Returns
+        -------
+        HabiticaQuestResponse
+            A response object containing updated quest data of the group or party.
+
+        Raises
+        ------
+        NotFoundError
+            If the specified group or quest could not be found.
+        NotAuthorizedError
+            If the user does not have permission to start the quest.
+        aiohttp.ClientResponseError
+            Raised for HTTP-related errors, such as HTTP 400 or 500 response status.
+        aiohttp.ClientConnectionError
+            If the connection to the API fails.
+        aiohttp.ClientError
+            Raised for any other exceptions encountered by `aiohttp` during the request.
+        TimeoutError
+            If the connection to the API times out.
+
+        Examples
+        --------
+        Cancel a pending quest for the party:
+        >>> response = await habitica.cancel_quest()
+        >>> print(response.success)  # True if the quest was successfully canceled.
+        """
+        group = "party" if not group_id else str(group_id)
+        url = self.url / "api/v3/groups" / group / "quests/force-start"
+
+        return HabiticaQuestResponse.from_json(
+            await self._request("post", url=url),
+        )
+
+    async def invite_quest(
+        self,
+        group_id: UUID | None = None,
+        *,
+        quest_key: str,
+    ) -> HabiticaQuestResponse:
+        """Invite members of the party or a specific group to participate in a quest.
+
+        Sends invitations for a quest to all eligible members of the specified group.
+        The quest is started when all members accept or reject the invitation.
+
+        Parameters
+        ----------
+        group_id : UUID, optional
+            The UUID of the group for which the quest invitations should be sent.
+            Defaults to the user's party if not specified.
+        quest_key : str
+            The unique key identifying the quest to invite members to.
+
+        Returns
+        -------
+        HabiticaQuestResponse
+            A response object containing updated quest data of the group or party.
+
+        Raises
+        ------
+        NotFoundError
+            If the specified group or quest could not be found.
+        aiohttp.ClientResponseError
+            Raised for HTTP-related errors, such as HTTP 400 or 500 response status.
+        aiohttp.ClientConnectionError
+            If the connection to the API fails.
+        aiohttp.ClientError
+            Raised for any other exceptions encountered by `aiohttp` during the request.
+        TimeoutError
+            If the connection to the API times out.
+
+        Examples
+        --------
+        Send a quest invitation to the party:
+        >>> response = await habitica.invite_quest(quest_key="dilatory_derby")
+        >>> print(response.success)  # True if invitations were successfully sent.
+
+        Send a quest invitation to a specific group:
+        >>> group_id = UUID("12345678-1234-5678-1234-567812345678")
+        >>> response = await habitica.invite_quest(group_id, quest_key="golden_knight")
+        >>> print(response.success)  # True if invitations were successfully sent.
+        """
+        group = "party" if not group_id else str(group_id)
+        url = self.url / "api/v3/groups" / group / "quests/invite" / quest_key
+
+        return HabiticaQuestResponse.from_json(
+            await self._request("post", url=url),
+        )
+
+    async def leave_quest(self, group_id: UUID | None = None) -> HabiticaQuestResponse:
+        """Leave the current quest from the party or a specific group.
+
+        Allows a user to exit an ongoing quest they are part of. This action removes
+        them from the quest but does not affect its progress for other participants.
+        Users who leave a quest will not contribute to its completion or receive rewards.
+
+        Parameters
+        ----------
+        group_id : UUID, optional
+            The UUID of the group associated with the quest the user is leaving.
+            Defaults to the user's party if not specified.
+        quest_key : str
+            The unique key identifying the quest to invite members to.
+
+        Returns
+        -------
+        HabiticaQuestResponse
+            A response object containing updated quest data of the group or party.
+
+        Raises
+        ------
+        NotFoundError
+            If the specified group or quest could not be found.
+        aiohttp.ClientResponseError
+            Raised for HTTP-related errors, such as HTTP 400 or 500 response status.
+        aiohttp.ClientConnectionError
+            If the connection to the API fails.
+        aiohttp.ClientError
+            Raised for any other exceptions encountered by `aiohttp` during the request.
+        TimeoutError
+            If the connection to the API times out.
+
+        Examples
+        --------
+        Leave the current quest in the user's party:
+        >>> response = await habitica.leave_quest()
+        >>> print(response.success)  # True if the user successfully left the quest.
+
+        Leave the current quest in a specific group:
+        >>> group_id = UUID("12345678-1234-5678-1234-567812345678")
+        >>> response = await habitica.leave_quest(group_id)
+        >>> print(response.success)  # True if the user successfully left the quest.
+        """
+        group = "party" if not group_id else str(group_id)
+        url = self.url / "api/v3/groups" / group / "quests/leave"
+
+        return HabiticaQuestResponse.from_json(
+            await self._request("post", url=url),
+        )
+
     def _cache_asset(self, asset: str, asset_data: IO[bytes]) -> None:
         """Cache an asset and maintain the cache size limit by removing older entries.
 

habiticalib/types.py

@@ -777,6 +777,13 @@ class HabiticaUserResponse(HabiticaResponse):
     data: UserData
 
 
+@dataclass(kw_only=True)
+class HabiticaGroupMembersResponse(HabiticaResponse):
+    """Representation of a group members data response."""
+
+    data: list[UserData]
+
+
 @dataclass(kw_only=True)
 class CompletedBy:
     """Task group completedby data."""
@@ -1107,6 +1114,25 @@ class HabiticaTagResponse(HabiticaResponse, DataClassORJSONMixin):
     data: TagsUser
 
 
+@dataclass(kw_only=True)
+class QuestData:
+    """Quest data."""
+
+    progress: ProgressQuest = field(default_factory=ProgressQuest)
+    active: bool = False
+    members: dict[str, bool | None]
+    extra: dict | None = None
+    key: str
+    leader: UUID | None = None
+
+
+@dataclass(kw_only=True)
+class HabiticaQuestResponse(HabiticaResponse, DataClassORJSONMixin):
+    """Representation of a quest response."""
+
+    data: QuestData
+
+
 @dataclass
 class ChangeClassData:
     """Change class data."""
@@ -1194,7 +1220,7 @@ class Skill(StrEnum):
     VALOROUS_PRESENCE = "valorousPresence"
     INTIMIDATING_GAZE = "intimidate"
     # Rogue skills
-    PICKPOCKET = "Pickpocket"
+    PICKPOCKET = "pickPocket"
     BACKSTAB = "backStab"
     TOOLS_OF_THE_TRADE = "toolsOfTrade"
     STEALTH = "stealth"

{habiticalib-0.2.0a0.dist-info → habiticalib-0.2.0a1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: Habiticalib
-Version: 0.2.0a0
+Version: 0.2.0a1
 Summary: Asynchronous Python client library for the Habitica API
 Project-URL: Documentation, https://tr4nt0r.github.io/habiticalib/
 Project-URL: Source, https://github.com/tr4nt0r/habiticalib

habiticalib-0.2.0a1.dist-info/RECORD

@@ -0,0 +1,11 @@
+habiticalib/__init__.py,sha256=QwR7xcAdEwZ1bAv02KlZCm4sw-8-xKlYOUAaB502mCA,1687
+habiticalib/const.py,sha256=hTmR0O6Bibw96tMCIy-Wsb_AC0K4AH1qiQVCJyJ_TAg,626
+habiticalib/exceptions.py,sha256=oVFCGbHkVn0UpIKIPZPzXfvzs9US4R05ebdEn6cOpqM,1350
+habiticalib/helpers.py,sha256=IRZLYWkDVLI0iVBgBMmvZ6L83KCUl-CnzGhUR_tP6Fg,4576
+habiticalib/lib.py,sha256=_HPEjoH1o0wbSM26mIbzGEbfvAery3O8XDMTmUZEY2U,71271
+habiticalib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+habiticalib/types.py,sha256=ZmAkkDzXl9lj9fNWidlzjKkJ0CQStQVBi24u-3mgMPA,33907
+habiticalib-0.2.0a1.dist-info/METADATA,sha256=Yfdhp5dWPEylm1Ri2yU1zC2569oODmC6vSCERfG80mY,4156
+habiticalib-0.2.0a1.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
+habiticalib-0.2.0a1.dist-info/licenses/LICENSE,sha256=oIinIOSJ49l1iVIRI3XGXFWt6SF7a83kEFBAY8ORwNI,1084
+habiticalib-0.2.0a1.dist-info/RECORD,,

habiticalib-0.2.0a0.dist-info/RECORD

@@ -1,11 +0,0 @@
-habiticalib/__init__.py,sha256=gR6mjGbUe7tD3bR5UDSPXgKCtP-rfgknHi-XIP41HLk,1617
-habiticalib/const.py,sha256=tJbptyPWBga1PdjCeDzutNCVsT5BIyvO9nUfFGO1D90,609
-habiticalib/exceptions.py,sha256=oVFCGbHkVn0UpIKIPZPzXfvzs9US4R05ebdEn6cOpqM,1350
-habiticalib/helpers.py,sha256=IRZLYWkDVLI0iVBgBMmvZ6L83KCUl-CnzGhUR_tP6Fg,4576
-habiticalib/lib.py,sha256=JXx7PGrl74fJdTj_TKKzIr84Kl-hgCBDy0yvaMXXgD8,54316
-habiticalib/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-habiticalib/types.py,sha256=DAIKNhsc0KWSWBcfVrcP7XeZ3QlbFsuWyxt_326Lrvw,33309
-habiticalib-0.2.0a0.dist-info/METADATA,sha256=d_1DFcqvff_2feSeV1blBEmOlkZ1qChdQMxKirA7ics,4156
-habiticalib-0.2.0a0.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87
-habiticalib-0.2.0a0.dist-info/licenses/LICENSE,sha256=oIinIOSJ49l1iVIRI3XGXFWt6SF7a83kEFBAY8ORwNI,1084
-habiticalib-0.2.0a0.dist-info/RECORD,,