python-xbox 0.1.0__py3-none-any.whl

pythonxbox/api/provider/profile/__init__.py

@@ -0,0 +1,140 @@
+"""
+Profile
+
+Get Userprofiles by XUID or Gamertag
+"""
+
+from pythonxbox.api.provider.profile.models import ProfileResponse, ProfileSettings
+from pythonxbox.api.provider.ratelimitedprovider import RateLimitedProvider
+
+
+class ProfileProvider(RateLimitedProvider):
+    PROFILE_URL = "https://profile.xboxlive.com"
+    HEADERS_PROFILE = {"x-xbl-contract-version": "3"}
+    SEPARATOR = ","
+
+    RATE_LIMITS = {"burst": 10, "sustain": 30}
+
+    async def get_profiles(self, xuid_list: list[str], **kwargs) -> ProfileResponse:
+        """
+        Get profile info for list of xuids
+
+        Args:
+            xuid_list (list): List of xuids
+
+        Returns:
+            :class:`ProfileResponse`: Profile Response
+        """
+        post_data = {
+            "settings": [
+                ProfileSettings.GAME_DISPLAY_NAME,
+                ProfileSettings.APP_DISPLAY_NAME,
+                ProfileSettings.APP_DISPLAYPIC_RAW,
+                ProfileSettings.GAMERSCORE,
+                ProfileSettings.GAMERTAG,
+                ProfileSettings.GAME_DISPLAYPIC_RAW,
+                ProfileSettings.ACCOUNT_TIER,
+                ProfileSettings.TENURE_LEVEL,
+                ProfileSettings.XBOX_ONE_REP,
+                ProfileSettings.PREFERRED_COLOR,
+                ProfileSettings.LOCATION,
+                ProfileSettings.BIOGRAPHY,
+                ProfileSettings.WATERMARKS,
+                ProfileSettings.REAL_NAME,
+            ],
+            "userIds": xuid_list,
+        }
+        url = self.PROFILE_URL + "/users/batch/profile/settings"
+        resp = await self.client.session.post(
+            url,
+            json=post_data,
+            headers=self.HEADERS_PROFILE,
+            rate_limits=self.rate_limit_read,
+            **kwargs,
+        )
+        resp.raise_for_status()
+        return ProfileResponse(**resp.json())
+
+    async def get_profile_by_xuid(self, target_xuid: str, **kwargs) -> ProfileResponse:
+        """
+        Get Userprofile by xuid
+
+        Args:
+            target_xuid: XUID to get profile for
+
+        Returns:
+            :class:`ProfileResponse`: Profile Response
+        """
+        url = self.PROFILE_URL + f"/users/xuid({target_xuid})/profile/settings"
+        params = {
+            "settings": self.SEPARATOR.join(
+                [
+                    ProfileSettings.GAMERTAG,
+                    ProfileSettings.MODERN_GAMERTAG,
+                    ProfileSettings.MODERN_GAMERTAG_SUFFIX,
+                    ProfileSettings.UNIQUE_MODERN_GAMERTAG,
+                    ProfileSettings.REAL_NAME_OVERRIDE,
+                    ProfileSettings.BIOGRAPHY,
+                    ProfileSettings.LOCATION,
+                    ProfileSettings.GAMERSCORE,
+                    ProfileSettings.GAME_DISPLAYPIC_RAW,
+                    ProfileSettings.TENURE_LEVEL,
+                    ProfileSettings.ACCOUNT_TIER,
+                    ProfileSettings.XBOX_ONE_REP,
+                    ProfileSettings.PREFERRED_COLOR,
+                    ProfileSettings.WATERMARKS,
+                    ProfileSettings.IS_QUARANTINED,
+                ]
+            )
+        }
+        resp = await self.client.session.get(
+            url,
+            params=params,
+            headers=self.HEADERS_PROFILE,
+            rate_limits=self.rate_limit_read,
+            **kwargs,
+        )
+        resp.raise_for_status()
+        return ProfileResponse(**resp.json())
+
+    async def get_profile_by_gamertag(self, gamertag: str, **kwargs) -> ProfileResponse:
+        """
+        Get Userprofile by gamertag
+
+        Args:
+            gamertag: Gamertag to get profile for
+
+        Returns:
+            :class:`ProfileResponse`: Profile Response
+        """
+        url = self.PROFILE_URL + f"/users/gt({gamertag})/profile/settings"
+        params = {
+            "settings": self.SEPARATOR.join(
+                [
+                    ProfileSettings.GAMERTAG,
+                    ProfileSettings.MODERN_GAMERTAG,
+                    ProfileSettings.MODERN_GAMERTAG_SUFFIX,
+                    ProfileSettings.UNIQUE_MODERN_GAMERTAG,
+                    ProfileSettings.REAL_NAME_OVERRIDE,
+                    ProfileSettings.BIOGRAPHY,
+                    ProfileSettings.LOCATION,
+                    ProfileSettings.GAMERSCORE,
+                    ProfileSettings.GAME_DISPLAYPIC_RAW,
+                    ProfileSettings.TENURE_LEVEL,
+                    ProfileSettings.ACCOUNT_TIER,
+                    ProfileSettings.XBOX_ONE_REP,
+                    ProfileSettings.PREFERRED_COLOR,
+                    ProfileSettings.WATERMARKS,
+                    ProfileSettings.IS_QUARANTINED,
+                ]
+            )
+        }
+        resp = await self.client.session.get(
+            url,
+            params=params,
+            headers=self.HEADERS_PROFILE,
+            rate_limits=self.rate_limit_read,
+            **kwargs,
+        )
+        resp.raise_for_status()
+        return ProfileResponse(**resp.json())

pythonxbox/api/provider/profile/models.py

@@ -0,0 +1,47 @@
+from enum import Enum
+
+from pythonxbox.common.models import CamelCaseModel
+
+
+class ProfileSettings(str, Enum):
+    """
+    Profile settings, used as parameter for Profile API
+    """
+
+    GAME_DISPLAY_NAME = "GameDisplayName"
+    APP_DISPLAY_NAME = "AppDisplayName"
+    APP_DISPLAYPIC_RAW = "AppDisplayPicRaw"
+    GAME_DISPLAYPIC_RAW = "GameDisplayPicRaw"
+    PUBLIC_GAMERPIC = "PublicGamerpic"
+    SHOW_USER_AS_AVATAR = "ShowUserAsAvatar"
+    GAMERSCORE = "Gamerscore"
+    GAMERTAG = "Gamertag"
+    MODERN_GAMERTAG = "ModernGamertag"
+    MODERN_GAMERTAG_SUFFIX = "ModernGamertagSuffix"
+    UNIQUE_MODERN_GAMERTAG = "UniqueModernGamertag"
+    ACCOUNT_TIER = "AccountTier"
+    TENURE_LEVEL = "TenureLevel"
+    XBOX_ONE_REP = "XboxOneRep"
+    PREFERRED_COLOR = "PreferredColor"
+    LOCATION = "Location"
+    BIOGRAPHY = "Bio"
+    WATERMARKS = "Watermarks"
+    REAL_NAME = "RealName"
+    REAL_NAME_OVERRIDE = "RealNameOverride"
+    IS_QUARANTINED = "IsQuarantined"
+
+
+class Setting(CamelCaseModel):
+    id: str
+    value: str
+
+
+class ProfileUser(CamelCaseModel):
+    id: str
+    host_id: str
+    settings: list[Setting]
+    is_sponsored_user: bool
+
+
+class ProfileResponse(CamelCaseModel):
+    profile_users: list[ProfileUser]

pythonxbox/api/provider/ratelimitedprovider.py

@@ -0,0 +1,79 @@
+"""
+RateLimitedProvider
+
+Subclassed by providers with rate limit support
+"""
+
+from typing import TYPE_CHECKING
+from pythonxbox.api.provider.baseprovider import BaseProvider
+from pythonxbox.common.exceptions import XboxException
+from pythonxbox.common.ratelimits import CombinedRateLimit
+from pythonxbox.common.ratelimits.models import LimitType, ParsedRateLimit, TimePeriod
+
+if TYPE_CHECKING:
+    from pythonxbox.api.client import XboxLiveClient
+
+
+class RateLimitedProvider(BaseProvider):
+    # dict -> Dict (typing.dict) https://stackoverflow.com/a/63460173
+    RATE_LIMITS: dict[str, int | dict[str, int]]
+
+    def __init__(self, client: "XboxLiveClient") -> None:
+        """
+        Initialize Baseclass
+
+        Args:
+            client (:class:`XboxLiveClient`): Instance of XboxLiveClient
+        """
+        super().__init__(client)
+
+        # Check that RATE_LIMITS set defined in the child class
+        if hasattr(self, "RATE_LIMITS"):
+            # Note: we cannot check (type(self.RATE_LIMITS) == dict) as the type hints have already defined it as such
+            if "burst" and "sustain" in self.RATE_LIMITS:
+                # We have the required keys, attempt to parse.
+                # (type-checking for the values is performed in __parse_rate_limit_key)
+                self.__handle_rate_limit_setup()
+            else:
+                raise XboxException(
+                    "RATE_LIMITS object missing required keys 'burst', 'sustain'"
+                )
+        else:
+            raise XboxException(
+                "RateLimitedProvider as parent class but RATE_LIMITS not set!"
+            )
+
+    def __handle_rate_limit_setup(self) -> None:
+        # Retrieve burst and sustain from the dict
+        burst_key = self.RATE_LIMITS["burst"]
+        sustain_key = self.RATE_LIMITS["sustain"]
+
+        # Parse the rate limit dict values
+        burst_rate_limits = self.__parse_rate_limit_key(burst_key, TimePeriod.BURST)
+        sustain_rate_limits = self.__parse_rate_limit_key(
+            sustain_key, TimePeriod.SUSTAIN
+        )
+
+        # Instanciate CombinedRateLimits for read and write respectively
+        self.rate_limit_read = CombinedRateLimit(
+            burst_rate_limits, sustain_rate_limits, type=LimitType.READ
+        )
+        self.rate_limit_write = CombinedRateLimit(
+            burst_rate_limits, sustain_rate_limits, type=LimitType.WRITE
+        )
+
+    def __parse_rate_limit_key(
+        self, key: int | dict[str, int], period: TimePeriod
+    ) -> ParsedRateLimit:
+        if isinstance(key, int) and not isinstance(key, bool):
+            # bool is a subclass of int, hence the explicit check
+            return ParsedRateLimit(read=key, write=key, period=period)
+        elif isinstance(key, dict):
+            # TODO: schema here?
+            # Since the key-value pairs match we can just pass the dict to the model
+            return ParsedRateLimit(**key, period=period)
+            # return ParsedRateLimit(read=key["read"], write=key["write"])
+        else:
+            raise XboxException(
+                "RATE_LIMITS value types not recognised. Must be one of 'int, 'dict'."
+            )

pythonxbox/api/provider/screenshots/__init__.py

@@ -0,0 +1,167 @@
+"""
+Screenshots - Get screenshot info
+"""
+
+from pythonxbox.api.provider.baseprovider import BaseProvider
+from pythonxbox.api.provider.screenshots.models import ScreenshotResponse
+
+
+class ScreenshotsProvider(BaseProvider):
+    SCREENSHOTS_METADATA_URL = "https://screenshotsmetadata.xboxlive.com"
+    HEADERS_SCREENSHOTS_METADATA = {"x-xbl-contract-version": "5"}
+
+    async def get_recent_community_screenshots_by_title_id(
+        self, title_id: str, **kwargs
+    ) -> ScreenshotResponse:
+        """
+        Get recent community screenshots by Title Id
+
+        Args:
+            title_id: Title Id to get screenshots for
+
+        Returns:
+            :class:`ScreenshotResponse`: Screenshot Response
+        """
+        url = self.SCREENSHOTS_METADATA_URL + f"/public/titles/{title_id}/screenshots"
+        params = {"qualifier": "created"}
+        resp = await self.client.session.get(
+            url, params=params, headers=self.HEADERS_SCREENSHOTS_METADATA, **kwargs
+        )
+        resp.raise_for_status()
+        return ScreenshotResponse(**resp.json())
+
+    async def get_recent_own_screenshots(
+        self, title_id: str = None, skip_items: int = 0, max_items: int = 25, **kwargs
+    ) -> ScreenshotResponse:
+        """
+        Get own recent screenshots, optionally filter for title Id
+
+        Args:
+            title_id: Title ID to filter
+            skip_items: Item count to skip
+            max_items: Maximum item count to load
+
+        Returns:
+            :class:`ScreenshotResponse`: Screenshot Response
+        """
+        url = self.SCREENSHOTS_METADATA_URL + "/users/me"
+        if title_id:
+            url += f"/titles/{title_id}"
+        url += "/screenshots"
+
+        params = {"skipItems": skip_items, "maxItems": max_items}
+        resp = await self.client.session.get(
+            url, params=params, headers=self.HEADERS_SCREENSHOTS_METADATA, **kwargs
+        )
+        resp.raise_for_status()
+        return ScreenshotResponse(**resp.json())
+
+    async def get_recent_screenshots_by_xuid(
+        self,
+        xuid: str,
+        title_id: str = None,
+        skip_items: int = 0,
+        max_items: int = 25,
+        **kwargs,
+    ) -> ScreenshotResponse:
+        """
+        Get recent screenshots by XUID, optionally filter for title Id
+
+        Args:
+            xuid: XUID of user to get screenshots from
+            title_id: Optional title id filter
+            skip_items: Item count to skip
+            max_items: Maximum item count to load
+
+        Returns:
+            :class:`ScreenshotResponse`: Screenshot Response
+        """
+        url = self.SCREENSHOTS_METADATA_URL + f"/users/xuid({xuid})"
+        if title_id:
+            url += f"/titles/{title_id}"
+        url += "/screenshots"
+
+        params = {"skipItems": skip_items, "maxItems": max_items}
+        resp = await self.client.session.get(
+            url, params=params, headers=self.HEADERS_SCREENSHOTS_METADATA, **kwargs
+        )
+        resp.raise_for_status()
+        return ScreenshotResponse(**resp.json())
+
+    async def get_saved_community_screenshots_by_title_id(
+        self, title_id: str, **kwargs
+    ) -> ScreenshotResponse:
+        """
+        Get saved community screenshots by Title Id
+
+        Args:
+            title_id: Title Id to get screenshots for
+
+        Returns:
+            :class:`ScreenshotResponse`: Screenshot Response
+        """
+        url = f"{self.SCREENSHOTS_METADATA_URL}/public/titles/{title_id}/screenshots/saved"
+        params = {"qualifier": "created"}
+        resp = await self.client.session.get(
+            url, params=params, headers=self.HEADERS_SCREENSHOTS_METADATA, **kwargs
+        )
+        resp.raise_for_status()
+        return ScreenshotResponse(**resp.json())
+
+    async def get_saved_own_screenshots(
+        self, title_id: str = None, skip_items: int = 0, max_items: int = 25, **kwargs
+    ) -> ScreenshotResponse:
+        """
+        Get own saved screenshots, optionally filter for title Id an
+
+        Args:
+            title_id: Optional Title ID to filter
+            skip_items: Item count to skip
+            max_items: Maximum item count to load
+
+        Returns:
+            :class:`ScreenshotResponse`: Screenshot Response
+        """
+        url = self.SCREENSHOTS_METADATA_URL + "/users/me"
+        if title_id:
+            url += f"/titles/{title_id}"
+        url += "/screenshots/saved"
+
+        params = {"skipItems": skip_items, "maxItems": max_items}
+        resp = await self.client.session.get(
+            url, params=params, headers=self.HEADERS_SCREENSHOTS_METADATA, **kwargs
+        )
+        resp.raise_for_status()
+        return ScreenshotResponse(**resp.json())
+
+    async def get_saved_screenshots_by_xuid(
+        self,
+        xuid: str,
+        title_id: str = None,
+        skip_items: int = 0,
+        max_items: int = 25,
+        **kwargs,
+    ) -> ScreenshotResponse:
+        """
+        Get saved screenshots by XUID, optionally filter for title Id
+
+        Args:
+            xuid: XUID of user to get screenshots from
+            title_id: Optional title id filter
+            skip_items: Item count to skip
+            max_items: Maximum item count to load
+
+        Returns:
+            :class:`ScreenshotResponse`: Screenshot Response
+        """
+        url = self.SCREENSHOTS_METADATA_URL + f"/users/xuid({xuid})"
+        if title_id:
+            url += f"/titles/{title_id}"
+        url += "/screenshots/saved"
+
+        params = {"skipItems": skip_items, "maxItems": max_items}
+        resp = await self.client.session.get(
+            url, params=params, headers=self.HEADERS_SCREENSHOTS_METADATA, **kwargs
+        )
+        resp.raise_for_status()
+        return ScreenshotResponse(**resp.json())

pythonxbox/api/provider/screenshots/models.py

@@ -0,0 +1,56 @@
+from datetime import datetime
+from typing import Any
+
+from pythonxbox.common.models import CamelCaseModel
+
+
+class Thumbnail(CamelCaseModel):
+    uri: str
+    file_size: int
+    thumbnail_type: int
+
+
+class ScreenshotUri(CamelCaseModel):
+    uri: str
+    file_size: int
+    uri_type: int
+    expiration: datetime
+
+
+class Screenshot(CamelCaseModel):
+    screenshot_id: str
+    resolution_height: int
+    resolution_width: int
+    state: int
+    date_published: datetime
+    date_taken: datetime
+    last_modified: datetime
+    user_caption: str
+    type: int
+    scid: str
+    title_id: int
+    rating: float
+    rating_count: int
+    views: int
+    title_data: str
+    system_properties: str
+    saved_by_user: bool
+    achievement_id: str
+    greatest_moment_id: Any = None
+    thumbnails: list[Thumbnail]
+    screenshot_uris: list[ScreenshotUri]
+    xuid: str
+    screenshot_name: str
+    title_name: str
+    screenshot_locale: str
+    screenshot_content_attributes: int
+    device_type: str
+
+
+class PagingInfo(CamelCaseModel):
+    continuation_token: str | None = None
+
+
+class ScreenshotResponse(CamelCaseModel):
+    screenshots: list[Screenshot]
+    paging_info: PagingInfo