{"id":30614184,"url":"https://github.com/scottlz0310/qt-theme-manager","last_synced_at":"2026-01-20T17:02:36.175Z","repository":{"id":304685911,"uuid":"1019538170","full_name":"scottlz0310/Qt-Theme-Manager","owner":"scottlz0310","description":"A comprehensive theme management library for PyQt5/PyQt6/PySide6 applications","archived":false,"fork":false,"pushed_at":"2025-08-12T01:27:44.000Z","size":544,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-08-12T16:40:56.556Z","etag":null,"topics":["gui","pyqt","pyside","qt","styling","theme"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/qt-theme-manager/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/scottlz0310.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-14T13:33:54.000Z","updated_at":"2025-08-12T01:26:26.000Z","dependencies_parsed_at":"2025-08-05T13:13:20.851Z","dependency_job_id":"854c10cc-1a91-4d73-9833-6ee6e5be761d","html_url":"https://github.com/scottlz0310/Qt-Theme-Manager","commit_stats":null,"previous_names":["scottlz0310/theme-manager","scottlz0310/qt-theme-manager"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/scottlz0310/Qt-Theme-Manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottlz0310%2FQt-Theme-Manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottlz0310%2FQt-Theme-Manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottlz0310%2FQt-Theme-Manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottlz0310%2FQt-Theme-Manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/scottlz0310","download_url":"https://codeload.github.com/scottlz0310/Qt-Theme-Manager/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/scottlz0310%2FQt-Theme-Manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272815841,"owners_count":24997662,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-30T02:00:09.474Z","response_time":77,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gui","pyqt","pyside","qt","styling","theme"],"created_at":"2025-08-30T07:01:36.039Z","updated_at":"2026-01-20T17:02:36.168Z","avatar_url":"https://github.com/scottlz0310.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Qt-Theme-Manager for PyQt5/PyQt6/PySide6\n\n[![CI](https://github.com/scottlz0310/Qt-Theme-Manager/actions/workflows/ci.yml/badge.svg)](https://github.com/scottlz0310/Qt-Theme-Manager/actions/workflows/ci.yml)\n[![Security](https://github.com/scottlz0310/Qt-Theme-Manager/actions/workflows/security.yml/badge.svg)](https://github.com/scottlz0310/Qt-Theme-Manager/actions/workflows/security.yml)\n[![PyPI version](https://badge.fury.io/py/qt-theme-manager.svg)](https://badge.fury.io/py/qt-theme-manager)\n[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/qt-theme-manager)](https://pypi.org/project/qt-theme-manager/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA **pure theme management library** for PyQt5/PyQt6/PySide6 applications with automatic Qt framework detection, providing dynamic theme switching and 16+ built-in themes. **v1.0.1 - Production Ready!**\n\n## 🎯 ライブラリ分離思想\n\n### 背景と目的\n\nQt-Theme-Managerは、**純粋なライブラリ**として設計されており、テーマ管理の核となる機能に特化しています。この設計思想は、以下の原則に基づいています：\n\n#### 関心の分離による保守性向上\n- **ライブラリコア**: テーマ管理、スタイルシート生成、Qt統合機能\n- **GUIツール**: テーマエディタ、プレビューアプリケーション（別リポジトリ: qt-theme-studio）\n- **明確な責任分界**: 各コンポーネントが独立した責任を持つ\n\n#### 外部開発者の貢献促進\n- **シンプルなAPI**: 最小限の依存関係で使いやすいインターフェース\n- **モジュラー設計**: 機能ごとに独立したモジュール構造\n- **拡張性**: カスタムテーマやプラグインの開発が容易\n\n#### 長期的な持続可能性\n- **独立したリリースサイクル**: ライブラリとGUIツールの個別更新\n- **軽量な配布**: 必要最小限のファイルサイズ\n- **後方互換性**: 既存APIの安定性保証\n\n### 利点\n\n1. **開発効率の向上**: 関心の分離により、各部分の開発・テスト・保守が独立して行える\n2. **コードの再利用性**: ライブラリ機能を他のプロジェクトで簡単に利用可能\n3. **品質の向上**: 焦点を絞った開発により、より高品質なコードを実現\n4. **コミュニティの拡大**: シンプルな構造により、外部開発者の参加が促進される\n\n### アーキテクチャ\n\n```\nqt-theme-manager (ライブラリ)\n├── qt_theme_manager/          # コアライブラリパッケージ\n│   ├── qt/                    # Qt統合モジュール\n│   ├── cli/                   # コマンドライン機能\n│   └── config/                # 設定管理\n└── 最小限の依存関係\n\nqt-theme-studio (GUIツール - 別リポジトリ)\n├── テーマエディタ\n├── プレビューアプリケーション\n├── 高度な編集機能\n└── GUI固有の依存関係\n```\n\nこの分離により、ライブラリユーザーは軽量で高性能なテーマ管理機能を利用でき、GUI機能が必要な場合は別途qt-theme-studioを使用できます。\n\n## ✨ ライブラリ機能\n\n### 🎯 コア機能\n- **動的テーマ切り替え**: 実行時のテーマ変更とスタイル適用\n- **Qt自動検出**: PySide6 → PyQt6 → PyQt5の自動選択\n- **スタイルシート生成**: テーマ設定からQSSの自動生成\n- **設定管理**: テーマ設定の永続化と管理\n- **CLI機能**: コマンドライン経由でのテーマ操作\n\n### 🔧 技術的特徴\n- **軽量設計**: 最小限の依存関係で高性能\n- **クロスプラットフォーム**: Windows/macOS/Linux対応\n- **マルチフレームワーク**: PyQt5/PyQt6/PySide6サポート\n- **後方互換性**: 既存APIの安定性保証\n- **Python 3.9+**: モダンなPython環境に最適化\n\n### ♿ アクセシビリティ\n- **WCAG準拠**: 科学的な色彩計算による最適なコントラスト\n- **縞模様最適化**: 6%明度コントラストによる読みやすさ向上\n- **目の疲労軽減**: 長時間使用に配慮した色彩設計\n\n## Features\n\n- 🎨 **16+ Built-in Themes**: Light, Dark, High Contrast, and colorful themes\n- 🔄 **Dynamic Theme Switching**: Change themes at runtime without restarting\n- 💾 **Persistent Settings**: Theme preferences are automatically saved\n- 🎯 **Easy Integration**: Simple API for applying themes to widgets/applications\n- ⚡ **QSS Generation**: Automatic stylesheet generation from theme configurations\n- 📟 **CLI Support**: Command-line theme management\n- ♿ **Accessibility Features**: WCAG-compliant color calculations and contrast optimization\n- 🔧 **Qt Auto-Detection**: Automatic framework detection (PySide6/PyQt6/PyQt5)\n- 📦 **Lightweight**: Minimal dependencies for optimal performance\n\n## 🚀 30秒クイックスタート\n\n**3行のコードでQt アプリに美しいテーマを追加:**\n\n```python\nfrom qt_theme_manager import apply_theme_to_widget\n\n# ウィジェットに現在のテーマを適用\napply_theme_to_widget(your_widget)\n```\n\n**動的なテーマ切り替え:**\n\n```python\nfrom qt_theme_manager import ThemeController\n\ncontroller = ThemeController()\ncontroller.set_theme(\"dark\")  # \"light\", \"blue\", \"cyberpunk\"など\ncontroller.apply_theme_to_application()\n```\n\n**CLIでのテーマ管理:**\n\n```bash\n# インストール\npip install qt-theme-manager[pyqt6]\n\n# テーマ一覧表示\nqt-theme-manager list\n\n# テーマ切り替え\nqt-theme-manager set dark\n```\n\n**16の美しいテーマが利用可能:** `dark`, `light`, `blue`, `green`, `cyberpunk`, `ocean`など\n\n### GUIツールについて\nテーマエディタやプレビューアプリケーションは、別リポジトリ（**qt-theme-studio**）に移行されました。\nライブラリとしての機能に集中することで、より軽量で高性能なテーマ管理を実現しています。\n\n---\n\n## Installation\n\n### Option 1: Install from PyPI (recommended)\n\n```bash\n# Basic installation\npip install qt-theme-manager\n\n# Install with your preferred Qt framework\npip install qt-theme-manager[pyqt6]    # For PyQt6 (recommended)\npip install qt-theme-manager[pyqt5]    # For PyQt5\npip install qt-theme-manager[pyside6]  # For PySide6\n\n# Install with all Qt frameworks\npip install qt-theme-manager[all]\n```\n\n\n\n### Option 2: Install from source (for developers)\n\n```bash\ngit clone https://github.com/scottlz0310/Qt-Theme-Manager.git\ncd Qt-Theme-Manager\n\n# Create virtual environment (recommended)\npython -m venv venv\nsource venv/bin/activate  # Linux/Mac\n# or: venv\\Scripts\\activate  # Windows\n\n# Install with your preferred Qt framework\npip install -e .[pyqt6]    # For PyQt6\n# pip install -e .[pyqt5]  # For PyQt5\n# pip install -e .[pyside6] # For PySide6\n```\n\n### Requirements\n\n- Python 3.9+\n- PyQt5, PyQt6, or PySide6 (for GUI functionality)\n\n## Quick Start\n\n### Basic Usage\n\n```python\nfrom qt_theme_manager.qt.controller import apply_theme_to_widget\nfrom PyQt5.QtWidgets import QApplication, QMainWindow\n\napp = QApplication([])\nwindow = QMainWindow()\n\n# Apply current theme to widget\napply_theme_to_widget(window)\n\nwindow.show()\napp.exec_()\n```\n\n### Using ThemeController\n\n```python\nfrom qt_theme_manager.qt.controller import ThemeController\n\n# Initialize theme controller\ncontroller = ThemeController()\n\n# Get available themes\nthemes = controller.get_available_themes()\nprint(\"Available themes:\", list(themes.keys()))\n\n# Switch theme\ncontroller.set_theme(\"dark\")\n\n# Apply to application\ncontroller.apply_theme_to_application()\n```\n\n## Command Line Interface\n\n### 🖥️ CLI機能\n\nQt-Theme-Managerは、コマンドライン経由でのテーマ管理をサポートしています：\n\n```bash\n# 利用可能なテーマ一覧を表示\nqt-theme-manager list\n\n# 現在のテーマを表示\nqt-theme-manager current\n\n# テーマを設定\nqt-theme-manager set dark\n\n# テーマをQSSファイルにエクスポート\nqt-theme-manager export dark dark_theme.qss\n\n# ヘルプを表示\nqt-theme-manager --help\n```\n\n### 🎨 GUIツールについて（移行済み）\n\nテーマエディタやプレビューアプリケーションなどのGUIツールは、**qt-theme-studio**リポジトリに移行されました：\n\n- **テーマエディタ**: 高度なテーマ作成・編集機能\n- **プレビューアプリケーション**: リアルタイムテーマプレビュー\n- **Zebraパターンエディタ**: アクセシビリティ対応の縞模様生成\n\nこれらのツールを使用する場合は、qt-theme-studioリポジトリをご利用ください。\n\n### ♿ アクセシビリティ機能\n\nライブラリには以下のアクセシビリティ機能が組み込まれています：\n\n```python\n# 縞模様の自動最適化\nlist_widget.setAlternatingRowColors(True)\ncontroller.apply_theme_to_widget(list_widget)\n# WCAG準拠の色彩が自動適用されます\n```\n\n### レガシーCLIメソッド\n\n高度なユーザーやスクリプト用：\n\n```bash\n# 推奨方法\nqt-theme-manager list\nqt-theme-manager set dark\nqt-theme-manager export dark dark_theme.qss\nqt-theme-manager current\n\n# レガシーメソッド\npython -m qt_theme_manager.cli.main list\npython -m qt_theme_manager.cli.main set dark\npython -m qt_theme_manager.main current\n```\n\n## Available Themes\n\nThe library includes 16 built-in themes:\n\n### Core Themes\n- **light** - Light mode with bright background\n- **dark** - Dark mode with low-strain colors\n- **high_contrast** - High contrast for accessibility\n\n### Color Themes\n- **blue** - Professional blue-based theme\n- **green** - Natural green-based theme\n- **purple** - Elegant purple-based theme\n- **orange** - Warm orange-based theme\n- **pink** - Playful pink-based theme\n- **red** - Bold red-based theme\n- **teal** - Calm teal-based theme\n- **yellow** - Bright yellow-based theme\n- **gray** - Simple gray-based theme\n- **sepia** - Eye-friendly sepia theme\n- **cyberpunk** - Neon cyberpunk theme\n- **forest** - Natural forest theme\n- **ocean** - Deep ocean blue theme\n\n## Configuration\n\nThemes are defined in `config/theme_settings.json`. Each theme includes:\n\n- **Basic Colors**: background, text, primary, accent\n- **Component Styles**: buttons, inputs, panels, toolbars\n- **Text Variants**: primary, secondary, muted, success, warning, error\n\n### Example Theme Configuration\n\n```json\n{\n  \"dark\": {\n    \"name\": \"dark\",\n    \"display_name\": \"ダークモード\",\n    \"description\": \"暗い背景の低負荷テーマ\",\n    \"backgroundColor\": \"#1a1a1a\",\n    \"textColor\": \"#eeeeee\",\n    \"primaryColor\": \"#222831\",\n    \"accentColor\": \"#00adb5\",\n    \"button\": {\n      \"background\": \"#4a5568\",\n      \"text\": \"#ffffff\",\n      \"hover\": \"#00adb5\"\n    }\n  }\n}\n```\n\n## Advanced Usage\n\n### Custom Theme Configuration\n\n```python\nfrom qt_theme_manager.qt.controller import ThemeController\n\n# Use custom config file\ncontroller = ThemeController(\"/path/to/custom/config.json\")\n```\n\n### Theme Preview Window\n\n```python\nfrom qt_theme_manager.qt.preview import show_preview\n\n# Show interactive preview window\npreview_window = show_preview()\n```\n\n### Manual QSS Generation\n\n```python\nfrom qt_theme_manager.qt.stylesheet import StylesheetGenerator\n\ntheme_config = {...}  # Your theme configuration\ngenerator = StylesheetGenerator(theme_config)\n\n# Generate complete stylesheet\nqss = generator.generate_qss()\n\n# Generate specific widget styles\nbutton_qss = generator.generate_widget_qss('button')\n```\n\n## Project Structure\n\n```\nqt_theme_manager/               # ライブラリコアパッケージ\n├── __init__.py                 # パブリックAPI\n├── main.py                     # CLIエントリーポイント\n├── config/\n│   └── theme_settings.json     # テーマ定義\n├── qt/                         # Qt統合モジュール\n│   ├── __init__.py\n│   ├── detection.py            # Qt自動検出\n│   ├── loader.py               # 設定ファイル読み込み\n│   ├── stylesheet.py           # QSS生成\n│   ├── advanced_stylesheet.py  # 高度なスタイル機能\n│   └── controller.py           # テーマ管理\n└── cli/                        # CLI機能\n    ├── __init__.py\n    └── themectl.py             # CLIインターフェース\n```\n\n### 移行されたGUIツール\n以下のGUIツールは**qt-theme-studio**リポジトリに移行されました：\n- テーマエディタ\n- プレビューアプリケーション\n- Zebraパターンエディタ\n- 各種起動スクリプト\n\n## Testing\n\nRun the test suite to verify functionality:\n\n```bash\npython test_qt_theme_manager.py\n```\n\nThis will test:\n- Theme loading and configuration\n- Stylesheet generation\n- Theme switching\n- CLI functionality\n- QSS export\n\n## API Reference\n\n### ThemeController\n\nMain class for theme management.\n\n#### Methods\n\n- `get_available_themes()` - Get all available themes\n- `get_current_theme_name()` - Get current active theme\n- `set_theme(theme_name, save_settings=True)` - Switch to specified theme\n- `apply_theme_to_widget(widget)` - Apply theme to specific widget\n- `apply_theme_to_application(app=None)` - Apply theme to entire application\n- `export_qss(output_path, theme_name=None)` - Export QSS to file\n\n### ThemeLoader\n\nHandles loading and saving theme configurations.\n\n#### Methods\n\n- `load_settings()` - Load theme configuration from file\n- `get_available_themes()` - Get available themes dict\n- `get_current_theme()` - Get current theme name\n- `update_current_theme(theme_name)` - Update and save current theme\n\n### StylesheetGenerator\n\nGenerates QSS stylesheets from theme configurations.\n\n#### Methods\n\n- `generate_qss()` - Generate complete QSS stylesheet\n- `generate_widget_qss(widget_type)` - Generate QSS for specific widget type\n- `validate_theme_config(theme_config)` - Validate theme configuration\n\n## License\n\n[Add your license information here]\n\n## Contributing\n\n[Add contribution guidelines here]\n\n## Changelog\n\n### Version 0.0.1 (Initial Release)\n- Basic theme management functionality\n- 16 built-in themes\n- CLI interface\n- GUI preview window\n- QSS export functionality\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscottlz0310%2Fqt-theme-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscottlz0310%2Fqt-theme-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscottlz0310%2Fqt-theme-manager/lists"}