chzzk-python 0.1.0__py3-none-any.whl

chzzk/__init__.py

@@ -0,0 +1,175 @@
+"""Chzzk Python SDK - Unofficial Python SDK for Chzzk streaming platform."""
+
+from chzzk.api import (
+    AsyncCategoryService,
+    AsyncChannelService,
+    AsyncChatService,
+    AsyncLiveService,
+    AsyncRestrictionService,
+    AsyncSessionService,
+    AsyncUserService,
+    CategoryService,
+    ChannelService,
+    ChatService,
+    LiveService,
+    RestrictionService,
+    SessionService,
+    UserService,
+)
+from chzzk.auth import (
+    AsyncChzzkOAuth,
+    CallbackTokenStorage,
+    ChzzkOAuth,
+    FileTokenStorage,
+    InMemoryTokenStorage,
+    Token,
+    TokenStorage,
+)
+from chzzk.client import AsyncChzzkClient, ChzzkClient
+from chzzk.exceptions import (
+    AuthenticationError,
+    ChzzkAPIError,
+    ChzzkError,
+    EventSubscriptionError,
+    ForbiddenError,
+    InvalidClientError,
+    InvalidStateError,
+    InvalidTokenError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    SessionConnectionError,
+    SessionError,
+    SessionLimitExceededError,
+    TokenExpiredError,
+)
+from chzzk.models import (
+    Badge,
+    Category,
+    CategoryType,
+    ChannelInfo,
+    ChannelManager,
+    ChatAvailableCondition,
+    ChatAvailableGroup,
+    ChatEvent,
+    ChatMessageResponse,
+    ChatProfile,
+    ChatSettings,
+    DonationEvent,
+    DonationType,
+    EventType,
+    Follower,
+    LiveInfo,
+    LiveListResponse,
+    LiveSetting,
+    LiveSettingCategory,
+    Page,
+    RestrictedChannel,
+    SessionAuthResponse,
+    SessionInfo,
+    SessionListResponse,
+    StreamKey,
+    SubscribedEvent,
+    Subscriber,
+    SubscriberSortType,
+    SubscriptionEvent,
+    SystemEvent,
+    SystemEventData,
+    SystemMessageType,
+    UpdateChatSettingsRequest,
+    UpdateLiveSettingRequest,
+    UserInfo,
+    UserRole,
+    UserRoleCode,
+)
+from chzzk.realtime import AsyncChzzkEventClient, ChzzkEventClient
+
+try:
+    from chzzk._version import __version__
+except ImportError:
+    __version__ = "0.0.0.dev0"  # 개발 환경 fallback
+
+__all__ = [
+    # Clients
+    "AsyncChzzkClient",
+    "AsyncChzzkEventClient",
+    "ChzzkClient",
+    "ChzzkEventClient",
+    # Services
+    "AsyncCategoryService",
+    "AsyncChannelService",
+    "AsyncChatService",
+    "AsyncLiveService",
+    "AsyncRestrictionService",
+    "AsyncSessionService",
+    "AsyncUserService",
+    "CategoryService",
+    "ChannelService",
+    "ChatService",
+    "LiveService",
+    "RestrictionService",
+    "SessionService",
+    "UserService",
+    # Auth
+    "AsyncChzzkOAuth",
+    "CallbackTokenStorage",
+    "ChzzkOAuth",
+    "FileTokenStorage",
+    "InMemoryTokenStorage",
+    "Token",
+    "TokenStorage",
+    # Models
+    "Badge",
+    "Category",
+    "CategoryType",
+    "ChannelInfo",
+    "ChannelManager",
+    "ChatAvailableCondition",
+    "ChatAvailableGroup",
+    "ChatEvent",
+    "ChatMessageResponse",
+    "ChatProfile",
+    "ChatSettings",
+    "DonationEvent",
+    "DonationType",
+    "EventType",
+    "Follower",
+    "LiveInfo",
+    "LiveListResponse",
+    "LiveSetting",
+    "LiveSettingCategory",
+    "Page",
+    "RestrictedChannel",
+    "SessionAuthResponse",
+    "SessionInfo",
+    "SessionListResponse",
+    "StreamKey",
+    "SubscribedEvent",
+    "Subscriber",
+    "SubscriberSortType",
+    "SubscriptionEvent",
+    "SystemEvent",
+    "SystemEventData",
+    "SystemMessageType",
+    "UpdateChatSettingsRequest",
+    "UpdateLiveSettingRequest",
+    "UserInfo",
+    "UserRole",
+    "UserRoleCode",
+    # Exceptions
+    "AuthenticationError",
+    "ChzzkAPIError",
+    "ChzzkError",
+    "EventSubscriptionError",
+    "ForbiddenError",
+    "InvalidClientError",
+    "InvalidStateError",
+    "InvalidTokenError",
+    "NotFoundError",
+    "RateLimitError",
+    "ServerError",
+    "SessionConnectionError",
+    "SessionError",
+    "SessionLimitExceededError",
+    "TokenExpiredError",
+]

chzzk/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

chzzk/api/__init__.py

@@ -0,0 +1,29 @@
+"""API services for Chzzk SDK."""
+
+from chzzk.api.base import AsyncBaseService, BaseService
+from chzzk.api.category import AsyncCategoryService, CategoryService
+from chzzk.api.channel import AsyncChannelService, ChannelService
+from chzzk.api.chat import AsyncChatService, ChatService
+from chzzk.api.live import AsyncLiveService, LiveService
+from chzzk.api.restriction import AsyncRestrictionService, RestrictionService
+from chzzk.api.session import AsyncSessionService, SessionService
+from chzzk.api.user import AsyncUserService, UserService
+
+__all__ = [
+    "AsyncBaseService",
+    "AsyncCategoryService",
+    "AsyncChannelService",
+    "AsyncChatService",
+    "AsyncLiveService",
+    "AsyncRestrictionService",
+    "AsyncSessionService",
+    "AsyncUserService",
+    "BaseService",
+    "CategoryService",
+    "ChannelService",
+    "ChatService",
+    "LiveService",
+    "RestrictionService",
+    "SessionService",
+    "UserService",
+]

chzzk/api/base.py

@@ -0,0 +1,147 @@
+"""Base service class for API services."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from chzzk.http.client import AsyncHTTPClient, HTTPClient
+
+
+class BaseService:
+    """Base class for synchronous API services."""
+
+    def __init__(
+        self,
+        http_client: HTTPClient,
+        *,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+        access_token: str | None = None,
+        token_refresher: Callable[[], str | None] | None = None,
+    ) -> None:
+        """Initialize the service.
+
+        Args:
+            http_client: HTTP client instance for making requests.
+            client_id: Client ID for API authentication.
+            client_secret: Client secret for API authentication.
+            access_token: Access token for user-authenticated requests.
+            token_refresher: Optional callback to get/refresh access token.
+        """
+        self._http = http_client
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._access_token = access_token
+        self._token_refresher = token_refresher
+
+    def _get_client_headers(self) -> dict[str, str]:
+        """Get headers for Client-authenticated requests.
+
+        Returns:
+            Headers dict with Client-Id and Client-Secret.
+        """
+        headers: dict[str, str] = {}
+        if self._client_id:
+            headers["Client-Id"] = self._client_id
+        if self._client_secret:
+            headers["Client-Secret"] = self._client_secret
+        return headers
+
+    def _get_token_headers(self) -> dict[str, str]:
+        """Get headers for Access Token-authenticated requests.
+
+        If a token_refresher callback is configured, it will be called
+        to get the current access token (and potentially refresh it).
+
+        Returns:
+            Headers dict with Authorization Bearer token.
+        """
+        # Use token refresher if available (may refresh expired token)
+        if self._token_refresher:
+            token = self._token_refresher()
+            if token:
+                self._access_token = token
+
+        headers: dict[str, str] = {}
+        if self._access_token:
+            headers["Authorization"] = f"Bearer {self._access_token}"
+        return headers
+
+    def set_access_token(self, token: str) -> None:
+        """Update the access token.
+
+        Args:
+            token: New access token.
+        """
+        self._access_token = token
+
+
+class AsyncBaseService:
+    """Base class for asynchronous API services."""
+
+    def __init__(
+        self,
+        http_client: AsyncHTTPClient,
+        *,
+        client_id: str | None = None,
+        client_secret: str | None = None,
+        access_token: str | None = None,
+        async_token_refresher: Callable[[], str | None] | None = None,
+    ) -> None:
+        """Initialize the async service.
+
+        Args:
+            http_client: Async HTTP client instance for making requests.
+            client_id: Client ID for API authentication.
+            client_secret: Client secret for API authentication.
+            access_token: Access token for user-authenticated requests.
+            async_token_refresher: Optional async callback to get/refresh access token.
+        """
+        self._http = http_client
+        self._client_id = client_id
+        self._client_secret = client_secret
+        self._access_token = access_token
+        self._async_token_refresher = async_token_refresher
+
+    def _get_client_headers(self) -> dict[str, str]:
+        """Get headers for Client-authenticated requests.
+
+        Returns:
+            Headers dict with Client-Id and Client-Secret.
+        """
+        headers: dict[str, str] = {}
+        if self._client_id:
+            headers["Client-Id"] = self._client_id
+        if self._client_secret:
+            headers["Client-Secret"] = self._client_secret
+        return headers
+
+    async def _get_token_headers(self) -> dict[str, str]:
+        """Get headers for Access Token-authenticated requests.
+
+        If an async_token_refresher callback is configured, it will be called
+        to get the current access token (and potentially refresh it).
+
+        Returns:
+            Headers dict with Authorization Bearer token.
+        """
+        # Use async token refresher if available (may refresh expired token)
+        if self._async_token_refresher:
+            token = await self._async_token_refresher()
+            if token:
+                self._access_token = token
+
+        headers: dict[str, str] = {}
+        if self._access_token:
+            headers["Authorization"] = f"Bearer {self._access_token}"
+        return headers
+
+    def set_access_token(self, token: str) -> None:
+        """Update the access token.
+
+        Args:
+            token: New access token.
+        """
+        self._access_token = token

chzzk/api/category.py

@@ -0,0 +1,65 @@
+"""Category API service for Chzzk."""
+
+from __future__ import annotations
+
+from chzzk.api.base import AsyncBaseService, BaseService
+from chzzk.http import CATEGORIES_SEARCH_URL
+from chzzk.models.category import Category
+
+
+class CategoryService(BaseService):
+    """Synchronous Category API service.
+
+    Provides access to category-related API endpoints.
+    """
+
+    def search(self, query: str, *, size: int = 20) -> list[Category]:
+        """Search for categories.
+
+        Args:
+            query: Search query string.
+            size: Maximum number of results to return (default: 20).
+
+        Returns:
+            List of Category objects matching the query.
+
+        Raises:
+            ChzzkAPIError: If the API request fails.
+        """
+        params = {"query": query, "size": size}
+        data = self._http.get(
+            CATEGORIES_SEARCH_URL,
+            params=params,
+            headers=self._get_client_headers(),
+        )
+        categories = data.get("data", [])
+        return [Category.model_validate(item) for item in categories]
+
+
+class AsyncCategoryService(AsyncBaseService):
+    """Asynchronous Category API service.
+
+    Provides access to category-related API endpoints.
+    """
+
+    async def search(self, query: str, *, size: int = 20) -> list[Category]:
+        """Search for categories.
+
+        Args:
+            query: Search query string.
+            size: Maximum number of results to return (default: 20).
+
+        Returns:
+            List of Category objects matching the query.
+
+        Raises:
+            ChzzkAPIError: If the API request fails.
+        """
+        params = {"query": query, "size": size}
+        data = await self._http.get(
+            CATEGORIES_SEARCH_URL,
+            params=params,
+            headers=self._get_client_headers(),
+        )
+        categories = data.get("data", [])
+        return [Category.model_validate(item) for item in categories]

chzzk/api/channel.py

@@ -0,0 +1,218 @@
+"""Channel API service for Chzzk."""
+
+from __future__ import annotations
+
+from chzzk.api.base import AsyncBaseService, BaseService
+from chzzk.http import (
+    CHANNEL_FOLLOWERS_URL,
+    CHANNEL_ROLES_URL,
+    CHANNEL_SUBSCRIBERS_URL,
+    CHANNELS_URL,
+)
+from chzzk.models.channel import (
+    ChannelInfo,
+    ChannelManager,
+    Follower,
+    Subscriber,
+    SubscriberSortType,
+)
+
+
+class ChannelService(BaseService):
+    """Synchronous Channel API service.
+
+    Provides access to channel-related API endpoints.
+    """
+
+    def get_channels(self, channel_ids: list[str]) -> list[ChannelInfo]:
+        """Get information for multiple channels.
+
+        Args:
+            channel_ids: List of channel IDs to look up (max 20).
+
+        Returns:
+            List of ChannelInfo objects.
+
+        Raises:
+            ChzzkAPIError: If the API request fails.
+        """
+        params = {"channelIds": ",".join(channel_ids)}
+        data = self._http.get(
+            CHANNELS_URL,
+            params=params,
+            headers=self._get_client_headers(),
+        )
+        channels = data.get("data", [])
+        return [ChannelInfo.model_validate(item) for item in channels]
+
+    def get_streaming_roles(self) -> list[ChannelManager]:
+        """Get channel managers for the authenticated user's channel.
+
+        Returns:
+            List of ChannelManager objects.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        data = self._http.get(CHANNEL_ROLES_URL, headers=self._get_token_headers())
+        managers = data.get("data", [])
+        return [ChannelManager.model_validate(item) for item in managers]
+
+    def get_followers(
+        self,
+        *,
+        page: int = 0,
+        size: int = 20,
+    ) -> list[Follower]:
+        """Get followers for the authenticated user's channel.
+
+        Args:
+            page: Page number (0-indexed).
+            size: Number of results per page.
+
+        Returns:
+            List of Follower objects.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        params = {"page": page, "size": size}
+        data = self._http.get(
+            CHANNEL_FOLLOWERS_URL,
+            params=params,
+            headers=self._get_token_headers(),
+        )
+        followers = data.get("data", [])
+        return [Follower.model_validate(item) for item in followers]
+
+    def get_subscribers(
+        self,
+        *,
+        page: int = 0,
+        size: int = 20,
+        sort: SubscriberSortType = SubscriberSortType.RECENT,
+    ) -> list[Subscriber]:
+        """Get subscribers for the authenticated user's channel.
+
+        Args:
+            page: Page number (0-indexed).
+            size: Number of results per page.
+            sort: Sort order (RECENT or LONGER).
+
+        Returns:
+            List of Subscriber objects.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        params = {"page": page, "size": size, "sortType": sort.value}
+        data = self._http.get(
+            CHANNEL_SUBSCRIBERS_URL,
+            params=params,
+            headers=self._get_token_headers(),
+        )
+        subscribers = data.get("data", [])
+        return [Subscriber.model_validate(item) for item in subscribers]
+
+
+class AsyncChannelService(AsyncBaseService):
+    """Asynchronous Channel API service.
+
+    Provides access to channel-related API endpoints.
+    """
+
+    async def get_channels(self, channel_ids: list[str]) -> list[ChannelInfo]:
+        """Get information for multiple channels.
+
+        Args:
+            channel_ids: List of channel IDs to look up (max 20).
+
+        Returns:
+            List of ChannelInfo objects.
+
+        Raises:
+            ChzzkAPIError: If the API request fails.
+        """
+        params = {"channelIds": ",".join(channel_ids)}
+        data = await self._http.get(
+            CHANNELS_URL,
+            params=params,
+            headers=self._get_client_headers(),
+        )
+        channels = data.get("data", [])
+        return [ChannelInfo.model_validate(item) for item in channels]
+
+    async def get_streaming_roles(self) -> list[ChannelManager]:
+        """Get channel managers for the authenticated user's channel.
+
+        Returns:
+            List of ChannelManager objects.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        data = await self._http.get(CHANNEL_ROLES_URL, headers=await self._get_token_headers())
+        managers = data.get("data", [])
+        return [ChannelManager.model_validate(item) for item in managers]
+
+    async def get_followers(
+        self,
+        *,
+        page: int = 0,
+        size: int = 20,
+    ) -> list[Follower]:
+        """Get followers for the authenticated user's channel.
+
+        Args:
+            page: Page number (0-indexed).
+            size: Number of results per page.
+
+        Returns:
+            List of Follower objects.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        params = {"page": page, "size": size}
+        data = await self._http.get(
+            CHANNEL_FOLLOWERS_URL,
+            params=params,
+            headers=await self._get_token_headers(),
+        )
+        followers = data.get("data", [])
+        return [Follower.model_validate(item) for item in followers]
+
+    async def get_subscribers(
+        self,
+        *,
+        page: int = 0,
+        size: int = 20,
+        sort: SubscriberSortType = SubscriberSortType.RECENT,
+    ) -> list[Subscriber]:
+        """Get subscribers for the authenticated user's channel.
+
+        Args:
+            page: Page number (0-indexed).
+            size: Number of results per page.
+            sort: Sort order (RECENT or LONGER).
+
+        Returns:
+            List of Subscriber objects.
+
+        Raises:
+            InvalidTokenError: If the access token is invalid.
+            ChzzkAPIError: If the API request fails.
+        """
+        params = {"page": page, "size": size, "sortType": sort.value}
+        data = await self._http.get(
+            CHANNEL_SUBSCRIBERS_URL,
+            params=params,
+            headers=await self._get_token_headers(),
+        )
+        subscribers = data.get("data", [])
+        return [Subscriber.model_validate(item) for item in subscribers]