chzzk-python 0.9.3__tar.gz → 0.11.0__tar.gz

{chzzk_python-0.9.3 → chzzk_python-0.11.0}/.env.example

@@ -49,3 +49,11 @@ CHZZK_CHAT_OUTPUT_DIR=
 
 # Output format: jsonl, txt (default: jsonl)
 CHZZK_CHAT_OUTPUT_FORMAT=
+
+# Chat Monitoring Configuration
+# Interval for polling live status in seconds (default: 10)
+CHZZK_POLL_INTERVAL=
+
+# Enable automatic reconnection when stream restarts (default: true)
+# Set to "false" or "0" to disable
+CHZZK_AUTO_RECONNECT=

{chzzk_python-0.9.3 → chzzk_python-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chzzk-python
-Version: 0.9.3
+Version: 0.11.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
@@ -30,6 +30,7 @@ Requires-Dist: websocket-client>=1.9.0
 Requires-Dist: websockets>=12.0
 Provides-Extra: cli
 Requires-Dist: prompt-toolkit>=3.0.52; extra == 'cli'
+Requires-Dist: qrcode>=8.2; extra == 'cli'
 Requires-Dist: rich>=14.3.1; extra == 'cli'
 Requires-Dist: typer>=0.15.0; extra == 'cli'
 Description-Content-Type: text/markdown
@@ -356,6 +357,56 @@ async with AsyncUnofficialChatClient(
     await chat.run_forever()
 ```
 
+### Auto-Reconnection & Monitoring Options
+
+The unofficial chat client automatically reconnects when the stream restarts or the chat channel changes. You can customize this behavior:
+
+```python
+from chzzk.unofficial import AsyncUnofficialChatClient
+
+chat = AsyncUnofficialChatClient(
+    nid_aut="...",
+    nid_ses="...",
+    # Auto-reconnect settings
+    auto_reconnect=True,              # Enable auto-reconnection (default: True)
+    poll_interval=10.0,               # Status polling interval in seconds (default: 10)
+    max_reconnect_attempts=5,         # Max reconnection attempts (default: 5)
+    reconnect_backoff_base=1.0,       # Backoff base delay in seconds (default: 1)
+    reconnect_backoff_max=30.0,       # Max backoff delay in seconds (default: 30)
+    reconnect_wait_timeout=None,      # Reconnection wait timeout (None = infinite)
+)
+
+# Event handlers for connection status
+@chat.on_live
+async def on_live(event):
+    print(f"Stream started: {event.live_title}")
+
+@chat.on_offline
+async def on_offline(event):
+    print("Stream ended, waiting for restart...")
+
+@chat.on_reconnect
+async def on_reconnect(event):
+    print(f"Reconnected! (attempt {event.attempt})")
+
+@chat.on_reconnect_error
+async def on_reconnect_error(error):
+    print(f"Reconnection failed: {error}")
+```
+
+For long-running monitoring applications, you can configure infinite retry behavior:
+
+```python
+from chzzk.unofficial.chat.monitor import MonitorConfig
+
+# Create a custom monitor config
+config = MonitorConfig(
+    poll_interval_seconds=10.0,       # Poll every 10 seconds
+    max_consecutive_failures=10,      # Trigger error callback after 10 failures
+    infinite_retry=True,              # Continue monitoring even after failures
+)
+```
+
 ### How to Get Naver Cookies
 
 1. Log in to Naver
@@ -382,7 +433,13 @@ A CLI is available for quick access to the unofficial API features.
 ### Authentication
 
 ```bash
-# Save your Naver cookies (interactive)
+# Login via Naver QR code (recommended)
+chzzk auth qr
+
+# Login via Naver QR code with custom timeout
+chzzk auth qr --timeout 60
+
+# Save your Naver cookies manually (interactive)
 chzzk auth login
 
 # Check authentication status
@@ -424,6 +481,12 @@ chzzk chat watch CHANNEL_ID --output chat.txt --output-format txt
 # Creates: {channel_id}_{live_id}_{YYYYMMDD}.jsonl
 chzzk chat watch CHANNEL_ID --output-dir ./logs
 
+# Disable auto-reconnection
+chzzk chat watch CHANNEL_ID --no-auto-reconnect
+
+# Custom poll interval (seconds)
+chzzk chat watch CHANNEL_ID --poll-interval 5
+
 # Send a single message (requires authentication)
 chzzk chat send CHANNEL_ID "Hello!"
 
@@ -461,6 +524,8 @@ chzzk chat send CHANNEL_ID -i --offline
 | `CHZZK_CHAT_OUTPUT` | Default chat output file path |
 | `CHZZK_CHAT_OUTPUT_DIR` | Default chat output directory (auto-generates filename) |
 | `CHZZK_CHAT_OUTPUT_FORMAT` | Default chat output format (jsonl, txt) |
+| `CHZZK_POLL_INTERVAL` | Live status polling interval in seconds (default: 10) |
+| `CHZZK_AUTO_RECONNECT` | Enable auto-reconnection (default: true, set "false" to disable) |
 
 ## Examples
 

{chzzk_python-0.9.3 → chzzk_python-0.11.0}/README.md

@@ -320,6 +320,56 @@ async with AsyncUnofficialChatClient(
     await chat.run_forever()
 ```
 
+### Auto-Reconnection & Monitoring Options
+
+The unofficial chat client automatically reconnects when the stream restarts or the chat channel changes. You can customize this behavior:
+
+```python
+from chzzk.unofficial import AsyncUnofficialChatClient
+
+chat = AsyncUnofficialChatClient(
+    nid_aut="...",
+    nid_ses="...",
+    # Auto-reconnect settings
+    auto_reconnect=True,              # Enable auto-reconnection (default: True)
+    poll_interval=10.0,               # Status polling interval in seconds (default: 10)
+    max_reconnect_attempts=5,         # Max reconnection attempts (default: 5)
+    reconnect_backoff_base=1.0,       # Backoff base delay in seconds (default: 1)
+    reconnect_backoff_max=30.0,       # Max backoff delay in seconds (default: 30)
+    reconnect_wait_timeout=None,      # Reconnection wait timeout (None = infinite)
+)
+
+# Event handlers for connection status
+@chat.on_live
+async def on_live(event):
+    print(f"Stream started: {event.live_title}")
+
+@chat.on_offline
+async def on_offline(event):
+    print("Stream ended, waiting for restart...")
+
+@chat.on_reconnect
+async def on_reconnect(event):
+    print(f"Reconnected! (attempt {event.attempt})")
+
+@chat.on_reconnect_error
+async def on_reconnect_error(error):
+    print(f"Reconnection failed: {error}")
+```
+
+For long-running monitoring applications, you can configure infinite retry behavior:
+
+```python
+from chzzk.unofficial.chat.monitor import MonitorConfig
+
+# Create a custom monitor config
+config = MonitorConfig(
+    poll_interval_seconds=10.0,       # Poll every 10 seconds
+    max_consecutive_failures=10,      # Trigger error callback after 10 failures
+    infinite_retry=True,              # Continue monitoring even after failures
+)
+```
+
 ### How to Get Naver Cookies
 
 1. Log in to Naver
@@ -346,7 +396,13 @@ A CLI is available for quick access to the unofficial API features.
 ### Authentication
 
 ```bash
-# Save your Naver cookies (interactive)
+# Login via Naver QR code (recommended)
+chzzk auth qr
+
+# Login via Naver QR code with custom timeout
+chzzk auth qr --timeout 60
+
+# Save your Naver cookies manually (interactive)
 chzzk auth login
 
 # Check authentication status
@@ -388,6 +444,12 @@ chzzk chat watch CHANNEL_ID --output chat.txt --output-format txt
 # Creates: {channel_id}_{live_id}_{YYYYMMDD}.jsonl
 chzzk chat watch CHANNEL_ID --output-dir ./logs
 
+# Disable auto-reconnection
+chzzk chat watch CHANNEL_ID --no-auto-reconnect
+
+# Custom poll interval (seconds)
+chzzk chat watch CHANNEL_ID --poll-interval 5
+
 # Send a single message (requires authentication)
 chzzk chat send CHANNEL_ID "Hello!"
 
@@ -425,6 +487,8 @@ chzzk chat send CHANNEL_ID -i --offline
 | `CHZZK_CHAT_OUTPUT` | Default chat output file path |
 | `CHZZK_CHAT_OUTPUT_DIR` | Default chat output directory (auto-generates filename) |
 | `CHZZK_CHAT_OUTPUT_FORMAT` | Default chat output format (jsonl, txt) |
+| `CHZZK_POLL_INTERVAL` | Live status polling interval in seconds (default: 10) |
+| `CHZZK_AUTO_RECONNECT` | Enable auto-reconnection (default: true, set "false" to disable) |
 
 ## Examples
 

{chzzk_python-0.9.3 → chzzk_python-0.11.0}/README_KO.md

@@ -320,6 +320,56 @@ async with AsyncUnofficialChatClient(
     await chat.run_forever()
 ```
 
+### 자동 재연결 및 모니터링 옵션
+
+비공식 채팅 클라이언트는 방송이 재시작되거나 채팅 채널이 변경될 때 자동으로 재연결됩니다. 이 동작을 커스터마이즈할 수 있습니다:
+
+```python
+from chzzk.unofficial import AsyncUnofficialChatClient
+
+chat = AsyncUnofficialChatClient(
+    nid_aut="...",
+    nid_ses="...",
+    # 자동 재연결 설정
+    auto_reconnect=True,              # 자동 재연결 활성화 (기본값: True)
+    poll_interval=10.0,               # 상태 폴링 간격 (초, 기본값: 10)
+    max_reconnect_attempts=5,         # 최대 재연결 시도 횟수 (기본값: 5)
+    reconnect_backoff_base=1.0,       # 백오프 기본 딜레이 (초, 기본값: 1)
+    reconnect_backoff_max=30.0,       # 최대 백오프 딜레이 (초, 기본값: 30)
+    reconnect_wait_timeout=None,      # 재연결 대기 타임아웃 (None = 무한 대기)
+)
+
+# 연결 상태 이벤트 핸들러
+@chat.on_live
+async def on_live(event):
+    print(f"방송 시작: {event.live_title}")
+
+@chat.on_offline
+async def on_offline(event):
+    print("방송 종료, 재시작 대기 중...")
+
+@chat.on_reconnect
+async def on_reconnect(event):
+    print(f"재연결 성공! (시도 {event.attempt}회)")
+
+@chat.on_reconnect_error
+async def on_reconnect_error(error):
+    print(f"재연결 실패: {error}")
+```
+
+장시간 모니터링 애플리케이션의 경우 무한 재시도 동작을 설정할 수 있습니다:
+
+```python
+from chzzk.unofficial.chat.monitor import MonitorConfig
+
+# 커스텀 모니터 설정 생성
+config = MonitorConfig(
+    poll_interval_seconds=10.0,       # 10초마다 폴링
+    max_consecutive_failures=10,      # 10회 연속 실패 후 에러 콜백 호출
+    infinite_retry=True,              # 실패 후에도 계속 모니터링
+)
+```
+
 ### 네이버 쿠키 획득 방법
 
 1. 네이버에 로그인
@@ -346,7 +396,13 @@ except ChatConnectionError as e:
 ### 인증
 
 ```bash
-# 네이버 쿠키 저장 (대화형)
+# 네이버 QR 코드로 로그인 (권장)
+chzzk auth qr
+
+# 타임아웃 설정과 함께 QR 코드 로그인
+chzzk auth qr --timeout 60
+
+# 네이버 쿠키 수동 저장 (대화형)
 chzzk auth login
 
 # 인증 상태 확인
@@ -388,6 +444,12 @@ chzzk chat watch CHANNEL_ID --output chat.txt --output-format txt
 # 생성 형식: {channel_id}_{live_id}_{YYYYMMDD}.jsonl
 chzzk chat watch CHANNEL_ID --output-dir ./logs
 
+# 자동 재연결 비활성화
+chzzk chat watch CHANNEL_ID --no-auto-reconnect
+
+# 커스텀 폴링 간격 (초)
+chzzk chat watch CHANNEL_ID --poll-interval 5
+
 # 단일 메시지 전송 (인증 필요)
 chzzk chat send CHANNEL_ID "안녕하세요!"
 
@@ -425,6 +487,8 @@ chzzk chat send CHANNEL_ID -i --offline
 | `CHZZK_CHAT_OUTPUT` | 기본 채팅 출력 파일 경로 |
 | `CHZZK_CHAT_OUTPUT_DIR` | 기본 채팅 출력 디렉토리 (파일명 자동 생성) |
 | `CHZZK_CHAT_OUTPUT_FORMAT` | 기본 채팅 출력 형식 (jsonl, txt) |
+| `CHZZK_POLL_INTERVAL` | 라이브 상태 폴링 간격 (초, 기본값: 10) |
+| `CHZZK_AUTO_RECONNECT` | 자동 재연결 활성화 (기본값: true, 비활성화: "false") |
 
 ## 예제 코드
 

{chzzk_python-0.9.3 → chzzk_python-0.11.0}/examples/.env.example

@@ -18,3 +18,11 @@ CHZZK_NID_SES=your-nid-ses-cookie
 # 시청할 채널 ID (선택사항, 명령행에서도 지정 가능)
 # 채널 ID는 https://chzzk.naver.com/채널ID 형식의 URL에서 확인 가능
 CHZZK_CHANNEL_ID=
+
+# Chat Monitoring Configuration
+# Interval for polling live status in seconds (default: 10)
+CHZZK_POLL_INTERVAL=
+
+# Enable automatic reconnection when stream restarts (default: true)
+# Set to "false" or "0" to disable
+CHZZK_AUTO_RECONNECT=

{chzzk_python-0.9.3 → chzzk_python-0.11.0}/pyproject.toml

@@ -38,6 +38,7 @@ cli = [
     "typer>=0.15.0",
     "rich>=14.3.1",
     "prompt-toolkit>=3.0.52",
+    "qrcode>=8.2",
 ]
 
 [project.scripts]
@@ -59,6 +60,7 @@ dev = [
     "pytest-asyncio>=1.3.0",
     "pytest-httpx>=0.35.0",
     "python-dotenv>=1.2.1",
+    "pyzbar>=0.1.9",
     "ruff>=0.14.13",
 ]
 

{chzzk_python-0.9.3 → chzzk_python-0.11.0}/src/chzzk/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.9.3'
-__version_tuple__ = version_tuple = (0, 9, 3)
+__version__ = version = '0.11.0'
+__version_tuple__ = version_tuple = (0, 11, 0)
 
 __commit_id__ = commit_id = None