chzzk-python 0.1.0__py3-none-any.whl

chzzk_python-0.1.0.dist-info/METADATA

@@ -0,0 +1,314 @@
+Metadata-Version: 2.4
+Name: chzzk-python
+Version: 0.1.0
+Summary: Unofficial Python SDK for Chzzk (NAVER Live Streaming Platform) API
+Project-URL: Homepage, https://github.com/hypn4/chzzk-python
+Project-URL: Repository, https://github.com/hypn4/chzzk-python
+Project-URL: Documentation, https://github.com/hypn4/chzzk-python#readme
+Project-URL: Bug Tracker, https://github.com/hypn4/chzzk-python/issues
+Project-URL: Changelog, https://github.com/hypn4/chzzk-python/blob/main/CHANGELOG.md
+Author: hypn4
+License: MIT
+License-File: LICENSE
+Keywords: api,chat,chzzk,korean,live-streaming,naver,sdk,streaming,websocket
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: python-socketio[asyncio-client]<5.0.0,>=4.6.0
+Requires-Dist: websocket-client>=1.9.0
+Description-Content-Type: text/markdown
+
+# chzzk-python
+
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Unofficial Python SDK for Chzzk (NAVER Live Streaming Platform) API
+
+[한국어](README_KO.md)
+
+## Installation
+
+```bash
+# Using uv (recommended)
+uv add chzzk-python
+
+# Using pip
+pip install chzzk-python
+```
+
+## Quick Start
+
+```python
+from chzzk import ChzzkClient, FileTokenStorage
+
+# Create client with OAuth support
+client = ChzzkClient(
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+    redirect_uri="http://localhost:8080/callback",
+    token_storage=FileTokenStorage("token.json"),
+)
+
+# Generate authorization URL
+auth_url, state = client.get_authorization_url()
+# User visits auth_url and authorizes the app
+
+# Exchange code for token (after OAuth callback)
+token = client.authenticate(code="auth-code", state=state)
+
+# Use the API
+user = client.user.get_me()
+print(f"Channel: {user.channel_name}")
+```
+
+## API Categories & Implementation Status
+
+| Category | Status | Description |
+|----------|--------|-------------|
+| **Authorization** | ✅ Implemented | OAuth 2.0, Token issue/refresh/revoke |
+| **User** | ✅ Implemented | Get logged-in user info |
+| **Channel** | ✅ Implemented | Channel info, managers, followers, subscribers |
+| **Category** | ✅ Implemented | Category search |
+| **Live** | ✅ Implemented | Live list, stream key, broadcast settings |
+| **Chat** | ✅ Implemented | Send messages, announcements, chat settings |
+| **Session** | ✅ Implemented | Session create/list, event subscription |
+| **Restriction** | ✅ Implemented | Activity restriction list management |
+| **Drops** | ❌ Not Implemented | - |
+| **Webhook Event** | ❌ Not Implemented | - |
+
+## Features
+
+### Sync/Async Support
+
+Both synchronous and asynchronous clients are available:
+
+```python
+# Synchronous
+from chzzk import ChzzkClient
+
+with ChzzkClient(client_id="...", client_secret="...") as client:
+    user = client.user.get_me()
+
+# Asynchronous
+from chzzk import AsyncChzzkClient
+
+async with AsyncChzzkClient(client_id="...", client_secret="...") as client:
+    user = await client.user.get_me()
+```
+
+### Token Storage
+
+Multiple token storage options:
+
+```python
+from chzzk import InMemoryTokenStorage, FileTokenStorage, CallbackTokenStorage
+
+# In-memory (default)
+storage = InMemoryTokenStorage()
+
+# File-based persistence
+storage = FileTokenStorage("token.json")
+
+# Custom callback
+storage = CallbackTokenStorage(
+    get_callback=lambda: load_from_db(),
+    save_callback=lambda token: save_to_db(token),
+    delete_callback=lambda: delete_from_db(),
+)
+```
+
+### Realtime Events
+
+Receive chat, donation, and subscription events in realtime:
+
+```python
+from chzzk import ChzzkClient, ChatEvent, DonationEvent, SubscriptionEvent
+
+client = ChzzkClient(...)
+event_client = client.create_event_client()
+
+@event_client.on_chat
+def on_chat(event: ChatEvent):
+    print(f"{event.profile.nickname}: {event.content}")
+
+@event_client.on_donation
+def on_donation(event: DonationEvent):
+    print(f"{event.donator_nickname} donated {event.pay_amount}won")
+
+@event_client.on_subscription
+def on_subscription(event: SubscriptionEvent):
+    print(f"{event.subscriber_nickname} subscribed!")
+
+# Connect and subscribe
+event_client.connect()
+event_client.subscribe_chat()
+event_client.subscribe_donation()
+event_client.subscribe_subscription()
+event_client.run_forever()
+```
+
+## Usage Examples
+
+### OAuth Authentication Flow
+
+```python
+from chzzk import ChzzkClient, FileTokenStorage
+
+client = ChzzkClient(
+    client_id="your-client-id",
+    client_secret="your-client-secret",
+    redirect_uri="http://localhost:8080/callback",
+    token_storage=FileTokenStorage("token.json"),
+    auto_refresh=True,  # Automatically refresh expired tokens
+)
+
+# 1. Generate authorization URL
+auth_url, state = client.get_authorization_url()
+print(f"Visit: {auth_url}")
+
+# 2. After user authorizes, exchange code for token
+token = client.authenticate(code="received-code", state=state)
+
+# 3. Refresh token manually if needed
+new_token = client.refresh_token()
+
+# 4. Revoke token on logout
+client.revoke_token()
+```
+
+### Channel & Live Information
+
+```python
+# Get channel info
+channel = client.channel.get_channel("channel-id")
+print(f"Channel: {channel.channel_name}")
+print(f"Description: {channel.channel_description}")
+
+# Get followers
+followers = client.channel.get_followers(size=20)
+for follower in followers.data:
+    print(f"Follower: {follower.nickname}")
+
+# Get live broadcasts
+lives = client.live.get_lives(size=10)
+for live in lives.data:
+    print(f"{live.channel_name}: {live.live_title} ({live.concurrent_user_count} viewers)")
+
+# Get/Update live settings
+setting = client.live.get_setting()
+client.live.update_setting(default_live_title="My Stream Title")
+```
+
+### Chat Messages
+
+```python
+# Send chat message
+client.chat.send_message(channel_id="channel-id", message="Hello!")
+
+# Set chat announcement
+client.chat.set_notice(
+    channel_id="channel-id",
+    message="Welcome to the stream!",
+)
+
+# Get/Update chat settings
+settings = client.chat.get_settings(channel_id="channel-id")
+client.chat.update_settings(
+    channel_id="channel-id",
+    chat_available_group="FOLLOWER",
+)
+```
+
+### Async Example
+
+```python
+import asyncio
+from chzzk import AsyncChzzkClient, FileTokenStorage
+
+async def main():
+    async with AsyncChzzkClient(
+        client_id="your-client-id",
+        client_secret="your-client-secret",
+        redirect_uri="http://localhost:8080/callback",
+        token_storage=FileTokenStorage("token.json"),
+    ) as client:
+        # Get user info
+        user = await client.user.get_me()
+        print(f"Channel: {user.channel_name}")
+
+        # Get live broadcasts
+        lives = await client.live.get_lives(size=10)
+        for live in lives.data:
+            print(f"{live.channel_name}: {live.live_title}")
+
+asyncio.run(main())
+```
+
+## Exception Handling
+
+```python
+from chzzk import (
+    ChzzkError,              # Base exception
+    ChzzkAPIError,           # API error response
+    AuthenticationError,     # 401 errors
+    InvalidTokenError,       # Invalid/expired token
+    InvalidClientError,      # Invalid client credentials
+    ForbiddenError,          # 403 errors
+    NotFoundError,           # 404 errors
+    RateLimitError,          # 429 errors
+    ServerError,             # 5xx errors
+    TokenExpiredError,       # Token expired, need re-auth
+    InvalidStateError,       # OAuth state mismatch
+    SessionError,            # Session-related errors
+    SessionConnectionError,  # Socket.IO connection failed
+    SessionLimitExceededError,  # Max session limit exceeded
+    EventSubscriptionError,  # Event subscription failed
+)
+
+try:
+    user = client.user.get_me()
+except InvalidTokenError:
+    # Token is invalid or expired
+    token = client.refresh_token()
+except RateLimitError:
+    # Rate limit exceeded, wait and retry
+    time.sleep(60)
+except ChzzkAPIError as e:
+    print(f"API Error: [{e.status_code}] {e.error_code}: {e.message}")
+```
+
+## Examples
+
+See the [examples](examples/) directory for complete working examples:
+
+- `oauth_server.py` - OAuth authentication with Flask
+- `realtime_chat.py` - Realtime chat/donation/subscription events (sync)
+- `realtime_chat_async.py` - Realtime events (async)
+- `session_management.py` - Session management example
+
+## API Reference
+
+For detailed API documentation, see the [Official Chzzk API Documentation](https://chzzk.gitbook.io/chzzk).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Disclaimer
+
+This is an unofficial SDK and is not affiliated with NAVER or Chzzk. Use at your own risk.

chzzk_python-0.1.0.dist-info/RECORD

@@ -0,0 +1,37 @@
+chzzk/__init__.py,sha256=1TXefU4G9kkQy40hPBoqeZnJvHE8--Wc_T-dRaIeXdE,3766
+chzzk/_version.py,sha256=5jwwVncvCiTnhOedfkzzxmxsggwmTBORdFL_4wq0ZeY,704
+chzzk/client.py,sha256=zkS5RxU8q8_JjKj682fDZs77E8_jbS22xuZt-Z9mpc4,17953
+chzzk/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+chzzk/api/__init__.py,sha256=UfHYFruwdPx966QxBsaDXZXA9F7IULFJQrNHAyZ40eQ,935
+chzzk/api/base.py,sha256=hziWCfL-JgtqImqjy95qgARKHSX27eKYoeB_VsSUCn4,4909
+chzzk/api/category.py,sha256=zgIMttpxYZWgNXBEi2bLcC7UgU6ee2M8uHjJ9nyN7mE,1925
+chzzk/api/channel.py,sha256=ceVzuMiVtJuBqr6hPkRcmM1jqGQ2d1UBCl0_qn11FsI,6600
+chzzk/api/chat.py,sha256=1G-Cq3FHIopkBo27g8XFE_nPvjvxRyYGnDDFFmTlGjQ,8016
+chzzk/api/live.py,sha256=CLc_3NfmklpOtS-lVfnLtlKIQtn61xuY4y6KuSjRvSU,6645
+chzzk/api/restriction.py,sha256=1sPDnR83DQG06ZjEdTcGhWezhW4CgfR7K3dGXP0mF2I,4418
+chzzk/api/session.py,sha256=lk_UGucJf19anp2cX_f-BhrFi0iMAjgdUbhXo55lCUw,13610
+chzzk/api/user.py,sha256=a-Z4I2lzHlHcC6DJ7GpSM1tHJYW34BEcwkWidmITmw0,1385
+chzzk/auth/__init__.py,sha256=Q72PXxMDFWGFMU1rayT_wR4VzOB4Xsf3xJvrWoPtaqk,716
+chzzk/auth/models.py,sha256=jRIsEjKeew1zlaaS3yKsGI2mGAa-FSvTDIb0oaNRVmI,3487
+chzzk/auth/oauth.py,sha256=Nhe7BNmB5zfhI9a7ARm1SVOGOHW-R659a6TkOH7NJ6E,13935
+chzzk/auth/token.py,sha256=N0Zz5QZU50sm62nGihRhFmfR_KLfX2GoWMT97GA7PSY,3651
+chzzk/exceptions/__init__.py,sha256=cYYlVe2R_tV8KXB2bOsRBpzNEjZlzxJ_UDFx8_PQsEQ,793
+chzzk/exceptions/errors.py,sha256=Q2c7jPM7I_eluBngLFHmDGNTvXg3QNVnHTEWj2Ra8ls,4096
+chzzk/http/__init__.py,sha256=545jgKZ1cLa1qPvmaFDCFsBjMAzoDjblP9_QTm53cBs,1746
+chzzk/http/client.py,sha256=nyGE5adrh83C53LwwDOFsvsm9C4XVtg-3Z6zmMMfRhQ,8804
+chzzk/http/endpoints.py,sha256=U32XOYEljI-A2CrPEHBhAPD3FkBJ5vmf8pVyE0bbSe8,2068
+chzzk/models/__init__.py,sha256=JdQ-RmfEzDS57YyWwQykep_0dESA360jloDpkhvVq9c,1824
+chzzk/models/category.py,sha256=d4fWTCMmVKsw5m58XHaTZQcgqlduou6ouT82wD6lKgs,515
+chzzk/models/channel.py,sha256=HB22tDUJlh2WzCM-vNCColSX2vg_TMSjoK8PEgtbdnY,1966
+chzzk/models/chat.py,sha256=S-8WgdSDX_3s6Pf-cgmp9bG3J4jG7_FEB-V5ndl1oDw,2049
+chzzk/models/common.py,sha256=6F8PaXZKTNsusCWTcPEy4JYTXpOmcxea5wcg4Ns0MS0,420
+chzzk/models/live.py,sha256=P4KCYZS5uJu9FeI_SjVS9KDaUPCJSqwc-uLtk_MpUWM,2573
+chzzk/models/restriction.py,sha256=ktScIZ4ja5HQRRAtcGO4gn5mecSks0-xsIaQxjdwWSM,550
+chzzk/models/session.py,sha256=_nBK74uen2jqtm6BKiid4XGRHa7q0-eQDS71OBTVeUk,4240
+chzzk/models/user.py,sha256=VMMsD--1lDFm07HRC7LOpFcBhDhlKWY-tmniRh5Dlqw,347
+chzzk/realtime/__init__.py,sha256=W9zCfP8M3bJ_kIcSiioXJ_Z9Lol1E0kn3oEKRVf1nBY,186
+chzzk/realtime/client.py,sha256=YyKUK3T2EpqaqQ-LqntOvvyNRhoebkzVyL2giL4FQGw,21663
+chzzk_python-0.1.0.dist-info/METADATA,sha256=QU5HF5wBPW6suSX-CfEPJ_SA76aLznTqVbEF2hXB2ww,9210
+chzzk_python-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+chzzk_python-0.1.0.dist-info/licenses/LICENSE,sha256=_v9Nf8gbo1wGWzG43mf3FR1afupceNnAmEH_4q742mE,1062
+chzzk_python-0.1.0.dist-info/RECORD,,

chzzk_python-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

chzzk_python-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 hypn4
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.