chzzk-python 0.12.0__tar.gz → 0.14.0__tar.gz

{chzzk_python-0.12.0 → chzzk_python-0.14.0}/.env.example

@@ -1,6 +1,14 @@
 # Chzzk CLI Configuration
 # Copy this file to .env and fill in your values
 
+# Timezone Configuration
+# Docker 컨테이너 시스템 시간대 (default: Asia/Seoul)
+TZ=Asia/Seoul
+
+# 채팅 타임스탬프 및 로그 파일명에 사용되는 시간대 (default: Asia/Seoul)
+# TZ와 별도로 설정 가능하며, 로그 출력에만 영향
+CHZZK_TIMEZONE=Asia/Seoul
+
 # Authentication (Naver Cookie)
 # 브라우저에서 네이버 로그인 후 개발자 도구에서 쿠키 확인
 # 1. 브라우저에서 chzzk.naver.com에 로그인
@@ -9,6 +17,16 @@
 CHZZK_NID_AUT=
 CHZZK_NID_SES=
 
+# Channel ID
+# 채팅을 모니터링할 채널 ID
+CHZZK_CHANNEL_ID=
+
+# Channel IDs (Docker Compose only)
+# Docker Compose 다중 채널 모니터링 전용 (chat-watch-1, chat-watch-2, chat-watch-3)
+CHZZK_CHANNEL_ID_1=
+CHZZK_CHANNEL_ID_2=
+CHZZK_CHANNEL_ID_3=
+
 # Logging Configuration
 # Log level: DEBUG, INFO, WARNING, ERROR
 CHZZK_LOG_LEVEL=WARNING

{chzzk_python-0.12.0 → chzzk_python-0.14.0}/.github/workflows/docker.yml

@@ -145,13 +145,16 @@ jobs:
           docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
             $(printf '${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}@sha256:%s ' *)
 
-      - name: Inspect image
+      - name: Get image digest
+        id: digest
         run: |
-          docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.meta.outputs.version }}
+          DIGEST=$(docker buildx imagetools inspect ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ steps.meta.outputs.version }} --format '{{json .Manifest.Digest}}' | tr -d '"')
+          echo "digest=$DIGEST" >> "$GITHUB_OUTPUT"
+          echo "Image digest: $DIGEST"
 
       - name: Generate artifact attestation
         uses: actions/attest-build-provenance@v2
         with:
           subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
-          subject-digest: ${{ steps.meta.outputs.version }}
+          subject-digest: ${{ steps.digest.outputs.digest }}
           push-to-registry: true

{chzzk_python-0.12.0 → chzzk_python-0.14.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: chzzk-python
-Version: 0.12.0
+Version: 0.14.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
@@ -90,6 +90,30 @@ docker run --rm -it \
 
 Available tags: `latest`, `X.Y.Z`, `X.Y`, `X`
 
+### Docker Compose
+
+```bash
+# Copy and configure environment variables
+cp .env.example .env
+# Edit .env with your credentials and channel ID
+
+# Run CLI commands
+docker compose run --rm chzzk --help
+docker compose run --rm chzzk live info CHANNEL_ID
+
+# Watch chat (background service with auto-restart)
+docker compose --profile chat up -d chat-watch
+
+# Interactive chat mode
+docker compose --profile interactive run --rm chat-interactive
+
+# View logs
+docker compose --profile chat logs -f chat-watch
+
+# Stop services
+docker compose --profile chat down
+```
+
 ## Quick Start
 
 ```python
@@ -552,6 +576,8 @@ chzzk chat send CHANNEL_ID -i --offline
 | `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) |
+| `CHZZK_TIMEZONE` | Timezone for chat timestamps and log filenames (default: Asia/Seoul) |
+| `TZ` | System timezone for Docker containers (default: Asia/Seoul) |
 
 ## Examples
 

{chzzk_python-0.12.0 → chzzk_python-0.14.0}/README.md

@@ -53,6 +53,30 @@ docker run --rm -it \
 
 Available tags: `latest`, `X.Y.Z`, `X.Y`, `X`
 
+### Docker Compose
+
+```bash
+# Copy and configure environment variables
+cp .env.example .env
+# Edit .env with your credentials and channel ID
+
+# Run CLI commands
+docker compose run --rm chzzk --help
+docker compose run --rm chzzk live info CHANNEL_ID
+
+# Watch chat (background service with auto-restart)
+docker compose --profile chat up -d chat-watch
+
+# Interactive chat mode
+docker compose --profile interactive run --rm chat-interactive
+
+# View logs
+docker compose --profile chat logs -f chat-watch
+
+# Stop services
+docker compose --profile chat down
+```
+
 ## Quick Start
 
 ```python
@@ -515,6 +539,8 @@ chzzk chat send CHANNEL_ID -i --offline
 | `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) |
+| `CHZZK_TIMEZONE` | Timezone for chat timestamps and log filenames (default: Asia/Seoul) |
+| `TZ` | System timezone for Docker containers (default: Asia/Seoul) |
 
 ## Examples
 

{chzzk_python-0.12.0 → chzzk_python-0.14.0}/README_KO.md

@@ -53,6 +53,30 @@ docker run --rm -it \
 
 사용 가능한 태그: `latest`, `X.Y.Z`, `X.Y`, `X`
 
+### Docker Compose
+
+```bash
+# 환경 변수 파일 복사 및 설정
+cp .env.example .env
+# .env 파일에 인증 정보와 채널 ID 입력
+
+# CLI 명령어 실행
+docker compose run --rm chzzk --help
+docker compose run --rm chzzk live info CHANNEL_ID
+
+# 채팅 모니터링 (백그라운드 서비스, 자동 재시작)
+docker compose --profile chat up -d chat-watch
+
+# 대화형 채팅 모드
+docker compose --profile interactive run --rm chat-interactive
+
+# 로그 확인
+docker compose --profile chat logs -f chat-watch
+
+# 서비스 종료
+docker compose --profile chat down
+```
+
 ## 빠른 시작
 
 ```python
@@ -515,6 +539,8 @@ chzzk chat send CHANNEL_ID -i --offline
 | `CHZZK_CHAT_OUTPUT_FORMAT` | 기본 채팅 출력 형식 (jsonl, txt) |
 | `CHZZK_POLL_INTERVAL` | 라이브 상태 폴링 간격 (초, 기본값: 10) |
 | `CHZZK_AUTO_RECONNECT` | 자동 재연결 활성화 (기본값: true, 비활성화: "false") |
+| `CHZZK_TIMEZONE` | 채팅 타임스탬프 및 로그 파일명 시간대 (기본값: Asia/Seoul) |
+| `TZ` | Docker 컨테이너 시스템 시간대 (기본값: Asia/Seoul) |
 
 ## 예제 코드
 

chzzk_python-0.14.0/docker-compose.yml

@@ -0,0 +1,140 @@
+# =============================================================================
+# chzzk-python Docker Compose
+# =============================================================================
+#
+# Setup:
+#   cp .env.example .env
+#   # Edit .env with your CHZZK_CHANNEL_ID_1, CHZZK_CHANNEL_ID_2, ...
+#
+# Usage:
+#   # QR 로그인으로 쿠키 저장 (최초 1회)
+#   mkdir -p .chzzk .logs && chmod 777 .chzzk .logs
+#   docker compose run --rm -v ./.chzzk:/home/chzzk/.chzzk chzzk auth qr
+#   # 또는 docker run 사용:
+#   docker run --rm -it -v ./.chzzk:/home/chzzk/.chzzk ghcr.io/hypn4/chzzk-python:latest auth qr
+#   # 또는 호스트 사용자 권한으로 실행:
+#   docker run --rm -it --user $(id -u):$(id -g) -v ./.chzzk:/home/chzzk/.chzzk ghcr.io/hypn4/chzzk-python:latest auth qr
+#
+#   # CLI 명령어 실행
+#   docker compose run --rm chzzk --help
+#   docker compose run --rm chzzk live info CHANNEL_ID
+#
+#   # 채팅 모니터링 (백그라운드)
+#   # .env에 CHZZK_CHANNEL_ID_1, CHZZK_CHANNEL_ID_2, ... 설정 후:
+#   docker compose --profile chat up -d
+#   docker compose --profile chat logs -f
+#   docker compose --profile chat down
+#   # 특정 채널만 실행:
+#   docker compose --profile chat up -d chat-watch-1
+#
+#   # 대화형 채팅
+#   docker compose --profile interactive run --rm chat-interactive
+#
+# =============================================================================
+
+# YAML Anchor: 채팅 모니터링 서비스 공통 설정
+x-chat-watch-base: &chat-watch-base
+  image: ghcr.io/hypn4/chzzk-python:latest
+  restart: unless-stopped
+  profiles:
+    - chat
+  environment:
+    - TZ=${TZ:-Asia/Seoul}
+    - CHZZK_TIMEZONE=${CHZZK_TIMEZONE:-Asia/Seoul}
+    - CHZZK_NID_AUT=${CHZZK_NID_AUT:-}
+    - CHZZK_NID_SES=${CHZZK_NID_SES:-}
+    - CHZZK_LOG_LEVEL=${CHZZK_LOG_LEVEL:-INFO}
+    - CHZZK_POLL_INTERVAL=${CHZZK_POLL_INTERVAL:-10}
+  volumes:
+    - ./.logs:/home/chzzk/logs
+    - ./.chzzk:/home/chzzk/.chzzk
+
+services:
+  chzzk:
+    image: ghcr.io/hypn4/chzzk-python:latest
+    container_name: chzzk
+    restart: "no"
+    stdin_open: true
+    tty: true
+    environment:
+      - TZ=${TZ:-Asia/Seoul}
+      - CHZZK_TIMEZONE=${CHZZK_TIMEZONE:-Asia/Seoul}
+      - CHZZK_NID_AUT=${CHZZK_NID_AUT:-}
+      - CHZZK_NID_SES=${CHZZK_NID_SES:-}
+      - CHZZK_LOG_LEVEL=${CHZZK_LOG_LEVEL:-INFO}
+      - CHZZK_POLL_INTERVAL=${CHZZK_POLL_INTERVAL:-10}
+      - CHZZK_AUTO_RECONNECT=${CHZZK_AUTO_RECONNECT:-true}
+    volumes:
+      - ./.logs:/home/chzzk/logs
+      # Uncomment to persist cookies (run: docker compose run --rm chzzk auth qr)
+      # - ./.chzzk:/home/chzzk/.chzzk
+    # Override command as needed:
+    # command: ["chat", "watch", "CHANNEL_ID"]
+    # command: ["chat", "watch", "CHANNEL_ID", "--output-dir", "/home/chzzk/logs"]
+    # command: ["live", "info", "CHANNEL_ID"]
+
+  # Multi-channel chat monitoring (uses x-chat-watch-base anchor)
+  # 각 서비스는 CHZZK_CHANNEL_ID_N 환경변수를 사용하여 채널 지정
+  chat-watch-1:
+    <<: *chat-watch-base
+    container_name: chzzk-chat-watch-1
+    command:
+      - chat
+      - watch
+      - ${CHZZK_CHANNEL_ID_1:-}
+      - --output-dir
+      - /home/chzzk/logs
+      - --offline
+      - --auto-reconnect
+
+  chat-watch-2:
+    <<: *chat-watch-base
+    container_name: chzzk-chat-watch-2
+    command:
+      - chat
+      - watch
+      - ${CHZZK_CHANNEL_ID_2:-}
+      - --output-dir
+      - /home/chzzk/logs
+      - --offline
+      - --auto-reconnect
+
+  chat-watch-3:
+    <<: *chat-watch-base
+    container_name: chzzk-chat-watch-3
+    command:
+      - chat
+      - watch
+      - ${CHZZK_CHANNEL_ID_3:-}
+      - --output-dir
+      - /home/chzzk/logs
+      - --offline
+      - --auto-reconnect
+
+  # Example: Interactive chat mode
+  chat-interactive:
+    image: ghcr.io/hypn4/chzzk-python:latest
+    container_name: chzzk-chat-interactive
+    restart: "no"
+    profiles:
+      - interactive
+    stdin_open: true
+    tty: true
+    environment:
+      - TZ=${TZ:-Asia/Seoul}
+      - CHZZK_TIMEZONE=${CHZZK_TIMEZONE:-Asia/Seoul}
+      - CHZZK_NID_AUT=${CHZZK_NID_AUT:-}
+      - CHZZK_NID_SES=${CHZZK_NID_SES:-}
+      - CHZZK_LOG_LEVEL=${CHZZK_LOG_LEVEL:-INFO}
+    volumes:
+      - ./.logs:/home/chzzk/logs
+      # - ./.chzzk:/home/chzzk/.chzzk
+    command:
+      - chat
+      - send
+      - ${CHZZK_CHANNEL_ID:-}
+      - --interactive
+      - --output-dir
+      - /home/chzzk/logs
+      - --offline
+      - --auto-reconnect

{chzzk_python-0.12.0 → chzzk_python-0.14.0}/pyproject.toml

@@ -54,14 +54,18 @@ Changelog = "https://github.com/hypn4/chzzk-python/blob/main/CHANGELOG.md"
 [dependency-groups]
 dev = [
     "flask>=3.1.2",
-    "mypy>=1.19.1",
+    "prompt-toolkit>=3.0.52",
     "pyinstaller>=6.18.0",
+    "pyright>=1.1.408",
     "pytest>=9.0.2",
     "pytest-asyncio>=1.3.0",
     "pytest-httpx>=0.35.0",
     "python-dotenv>=1.2.1",
     "pyzbar>=0.1.9",
+    "qrcode>=8.2",
+    "rich>=14.3.1",
     "ruff>=0.14.13",
+    "typer>=0.15.0",
 ]
 
 [build-system]
@@ -94,6 +98,10 @@ asyncio_mode = "auto"
 asyncio_default_fixture_loop_scope = "function"
 testpaths = ["tests"]
 
+[tool.pyright]
+pythonVersion = "3.12"
+typeCheckingMode = "standard"
+
 [tool.ruff]
 line-length = 100
 target-version = "py312"

{chzzk_python-0.12.0 → chzzk_python-0.14.0}/src/chzzk/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.12.0'
-__version_tuple__ = version_tuple = (0, 12, 0)
+__version__ = version = '0.14.0'
+__version_tuple__ = version_tuple = (0, 14, 0)
 
 __commit_id__ = commit_id = None

{chzzk_python-0.12.0 → chzzk_python-0.14.0}/src/chzzk/cli/commands/auth.py

@@ -297,7 +297,7 @@ def _generate_qr_ascii(session: str) -> str:
 
     qr = qrcode.QRCode(
         version=1,
-        error_correction=qrcode.constants.ERROR_CORRECT_L,
+        error_correction=qrcode.constants.ERROR_CORRECT_L,  # type: ignore[reportAttributeAccessIssue]
         box_size=1,
         border=1,
     )

{chzzk_python-0.12.0 → chzzk_python-0.14.0}/src/chzzk/cli/commands/chat.py

@@ -7,7 +7,6 @@ import contextlib
 import json
 import logging
 import signal
-from datetime import datetime
 from pathlib import Path
 from typing import Annotated
 
@@ -16,8 +15,15 @@ from prompt_toolkit import PromptSession
 from prompt_toolkit.patch_stdout import patch_stdout
 from rich.console import Console
 
+from chzzk.cli import timezone as tz
 from chzzk.cli.formatter import ChatFormatter, FormatConfig
-from chzzk.cli.writers import ChatWriter, OutputFormat, create_writer, generate_chat_log_filename
+from chzzk.cli.writers import (
+    ChatWriter,
+    OutputFormat,
+    create_writer,
+    generate_chat_log_filename,
+    rotate_writer,
+)
 from chzzk.constants import StatusText
 from chzzk.exceptions import ChatConnectionError, ChatNotLiveError
 from chzzk.unofficial import (
@@ -57,7 +63,7 @@ def format_chat_message_json(msg: ChatMessage) -> str:
     return json.dumps(
         {
             "type": "chat",
-            "timestamp": datetime.now().isoformat(),
+            "timestamp": tz.now().isoformat(),
             "user_id_hash": msg.user_id_hash,
             "nickname": msg.nickname,
             "content": msg.content,
@@ -71,7 +77,7 @@ def format_donation_message_json(msg: DonationMessage) -> str:
     return json.dumps(
         {
             "type": "donation",
-            "timestamp": datetime.now().isoformat(),
+            "timestamp": tz.now().isoformat(),
             "user_id_hash": msg.user_id_hash,
             "nickname": msg.nickname,
             "content": msg.content,
@@ -85,7 +91,7 @@ def format_sent_message_json(content: str) -> str:
     return json.dumps(
         {
             "type": "sent",
-            "timestamp": datetime.now().isoformat(),
+            "timestamp": tz.now().isoformat(),
             "content": content,
         }
     )
@@ -216,6 +222,7 @@ def _run_watch_console(
     formatter = ChatFormatter(format_config)
     # Track writer created from output_dir (needs to be closed on exit)
     output_dir_writer: ChatWriter | None = None
+    current_live_id: int | None = None
 
     async def run_chat() -> None:
         async with AsyncUnofficialChzzkClient(nid_aut=nid_aut, nid_ses=nid_ses) as client:
@@ -244,6 +251,49 @@ def _run_watch_console(
 
             @chat.on_live
             async def handle_live(event: StatusChangeEvent) -> None:
+                nonlocal writer, output_dir_writer, current_live_id
+
+                # Rotate log file when live_id changes in output_dir mode
+                if output_dir and event.live_id != current_live_id:
+                    try:
+                        open_date: str | None = None
+                        try:
+                            new_live_detail = await client.live.get_live_detail(channel_id)
+                            open_date = new_live_detail.open_date
+                        except Exception:
+                            logger.warning(
+                                "Failed to get live detail for log rotation, using local date"
+                            )
+
+                        new_writer, new_path = rotate_writer(
+                            old_writer=output_dir_writer,
+                            output_dir=output_dir,
+                            channel_id=channel_id,
+                            new_live_id=event.live_id,
+                            open_date=open_date,
+                            output_format=output_format,
+                        )
+                        output_dir_writer = new_writer
+                        writer = new_writer
+                        current_live_id = event.live_id
+
+                        if json_output:
+                            console.print(
+                                json.dumps(
+                                    {
+                                        "event": "log_rotated",
+                                        "new_file": str(new_path),
+                                        "live_id": event.live_id,
+                                    }
+                                )
+                            )
+                        else:
+                            console.print(f"[dim]Log rotated: {new_path}[/dim]")
+                    except OSError as e:
+                        logger.warning(f"Failed to rotate log file: {e}")
+                        if not json_output:
+                            console.print(f"[yellow]Warning:[/yellow] Log rotation failed: {e}")
+
                 if json_output:
                     console.print(
                         json.dumps(
@@ -316,7 +366,7 @@ def _run_watch_console(
                 raise typer.Exit(1) from None
 
             # Create writer from output_dir if specified (after getting live_detail)
-            nonlocal writer, output_dir_writer
+            nonlocal writer, output_dir_writer, current_live_id
             if output_dir and not writer:
                 try:
                     output_dir.mkdir(parents=True, exist_ok=True)
@@ -329,6 +379,7 @@ def _run_watch_console(
                     )
                     output_dir_writer = create_writer(output_path, output_format)
                     writer = output_dir_writer
+                    current_live_id = live_detail.live_id
                     if not json_output:
                         console.print(f"[dim]Saving chat to: {output_path}[/dim]")
                 except OSError as e:
@@ -652,6 +703,7 @@ def _run_interactive_chat_console(
     formatter = ChatFormatter(format_config)
     # Track writer created from output_dir (needs to be closed on exit)
     output_dir_writer: ChatWriter | None = None
+    current_live_id: int | None = None
 
     async def run_chat() -> None:
         async with AsyncUnofficialChzzkClient(nid_aut=nid_aut, nid_ses=nid_ses) as client:
@@ -680,6 +732,49 @@ def _run_interactive_chat_console(
 
             @chat.on_live
             async def handle_live(event: StatusChangeEvent) -> None:
+                nonlocal writer, output_dir_writer, current_live_id
+
+                # Rotate log file when live_id changes in output_dir mode
+                if output_dir and event.live_id != current_live_id:
+                    try:
+                        open_date: str | None = None
+                        try:
+                            new_live_detail = await client.live.get_live_detail(channel_id)
+                            open_date = new_live_detail.open_date
+                        except Exception:
+                            logger.warning(
+                                "Failed to get live detail for log rotation, using local date"
+                            )
+
+                        new_writer, new_path = rotate_writer(
+                            old_writer=output_dir_writer,
+                            output_dir=output_dir,
+                            channel_id=channel_id,
+                            new_live_id=event.live_id,
+                            open_date=open_date,
+                            output_format=output_format,
+                        )
+                        output_dir_writer = new_writer
+                        writer = new_writer
+                        current_live_id = event.live_id
+
+                        if json_output:
+                            console.print(
+                                json.dumps(
+                                    {
+                                        "event": "log_rotated",
+                                        "new_file": str(new_path),
+                                        "live_id": event.live_id,
+                                    }
+                                )
+                            )
+                        else:
+                            console.print(f"[dim]Log rotated: {new_path}[/dim]")
+                    except OSError as e:
+                        logger.warning(f"Failed to rotate log file: {e}")
+                        if not json_output:
+                            console.print(f"[yellow]Warning:[/yellow] Log rotation failed: {e}")
+
                 if json_output:
                     console.print(
                         json.dumps(
@@ -752,7 +847,7 @@ def _run_interactive_chat_console(
                 raise typer.Exit(1) from None
 
             # Create writer from output_dir if specified (after getting live_detail)
-            nonlocal writer, output_dir_writer
+            nonlocal writer, output_dir_writer, current_live_id
             if output_dir and not writer:
                 try:
                     output_dir.mkdir(parents=True, exist_ok=True)
@@ -765,6 +860,7 @@ def _run_interactive_chat_console(
                     )
                     output_dir_writer = create_writer(output_path, output_format)
                     writer = output_dir_writer
+                    current_live_id = live_detail.live_id
                     if not json_output:
                         console.print(f"[dim]Saving chat to: {output_path}[/dim]")
                 except OSError as e:

{chzzk_python-0.12.0 → chzzk_python-0.14.0}/src/chzzk/cli/formatter.py

@@ -3,11 +3,12 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
-from datetime import datetime
 from typing import TYPE_CHECKING, Any
 
 from rich.markup import escape
 
+from chzzk.cli import timezone as tz
+
 if TYPE_CHECKING:
     from chzzk.unofficial import ChatMessage, ChatProfile, DonationMessage
 
@@ -119,7 +120,7 @@ class ChatFormatter:
 
     def _get_timestamp(self) -> str:
         """Get formatted timestamp string."""
-        return datetime.now().strftime(self.config.time_format)
+        return tz.now().strftime(self.config.time_format)
 
     def _escape_markup(self, text: str) -> str:
         """Escape Rich markup characters in text.
@@ -214,7 +215,7 @@ class ChatFormatter:
         """
         if not message_time:
             return ""
-        dt = datetime.fromtimestamp(message_time / 1000)
+        dt = tz.from_timestamp(message_time / 1000)
         return dt.strftime(self.config.time_format)
 
     def _get_pay_type_str(self, pay_type: str | None) -> str:

chzzk_python-0.14.0/src/chzzk/cli/timezone.py

@@ -0,0 +1,49 @@
+"""Timezone utilities for CLI output.
+
+This module provides centralized timezone handling for consistent timestamp
+display across different environments (local, Docker, etc.).
+
+The timezone can be configured via the CHZZK_TIMEZONE environment variable.
+Default timezone is Asia/Seoul (KST).
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import datetime
+from zoneinfo import ZoneInfo
+
+DEFAULT_TIMEZONE = "Asia/Seoul"
+
+
+def get_timezone() -> ZoneInfo:
+    """Get the configured timezone.
+
+    Returns:
+        ZoneInfo object for the configured timezone.
+        Uses CHZZK_TIMEZONE environment variable if set,
+        otherwise defaults to Asia/Seoul.
+    """
+    tz_name = os.environ.get("CHZZK_TIMEZONE", DEFAULT_TIMEZONE)
+    return ZoneInfo(tz_name)
+
+
+def now() -> datetime:
+    """Get current datetime in the configured timezone.
+
+    Returns:
+        Current datetime with timezone info.
+    """
+    return datetime.now(get_timezone())
+
+
+def from_timestamp(timestamp: float) -> datetime:
+    """Convert Unix timestamp to datetime in the configured timezone.
+
+    Args:
+        timestamp: Unix timestamp (seconds since epoch).
+
+    Returns:
+        Datetime object in the configured timezone.
+    """
+    return datetime.fromtimestamp(timestamp, get_timezone())