pyside-iconify 1.0.0__tar.gz

pyside_iconify-1.0.0/.gitignore

@@ -0,0 +1,23 @@
+__pycache__/
+*.py[cod]
+.venv/
+.venv-*/
+/build/
+/dist/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+/.cache/
+/.env
+/.env.*
+!/.env.example
+/.workbuddy/
+/outputs/
+.idea/
+.vscode/
+Thumbs.db
+.DS_Store
+.workbuddy/

pyside_iconify-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,88 @@
+# Contributing
+
+Thanks for your interest in contributing. This page covers setup, conventions,
+and the release checklist.
+
+## Development setup
+
+Requires [uv](https://docs.astral.sh/uv/) and Python 3.10–3.14.
+
+```powershell
+uv sync --extra pyside6 --group test
+$env:QT_QPA_PLATFORM = "offscreen"
+pytest -v
+```
+
+On macOS/Linux use `export QT_QPA_PLATFORM=offscreen` instead. The test suite
+runs fully offscreen — no desktop session needed.
+
+## Project layout
+
+See [docs/architecture.md](docs/architecture.md) for the layering rules
+(`widgets/ → rendering/ → core/`, no Qt in `core/`) and the reasoning behind
+each directory. The short version of "where does my change go":
+
+| Change touches                                 | Directory       |
+| ---------------------------------------------- | --------------- |
+| Icon names, JSON parsing, colors, sizes        | `core/`         |
+| QIcon/QPixmap rendering, caching, placeholders | `rendering/`    |
+| `IconWidget`, QSS, animation                   | `widgets/`      |
+| Downloads, disk cache                          | `network/`      |
+| Putting icons on existing widgets              | `integrations/` |
+| Public API surface, global config              | package root    |
+
+## Conventions
+
+- **Type hints everywhere**; the package ships `py.typed`.
+  No bare `Any` in public signatures.
+- **Errors are loud.** Unparseable input raises a specific exception
+  (`InvalidColorError`, `InvalidSizeError`, …) — never a silent fallback.
+- **Defaults are side-effect free.** Visual effects (hover, selection) are
+  explicit opt-in via parameters.
+- **Platform behavior is verified with probes before being designed against**
+  (offscreen platforms can differ from real ones; measure, then design).
+- Comments stay minimal — what/why, no debugging history.
+- No emoji in code, docs, or commit messages.
+
+## Testing expectations
+
+- Every bug fix ships with a regression test that fails without the fix.
+- Rendering changes: assert actual pixels (`pixmap.toImage().pixelColor(...)`)
+  or rendered output, not just that "no exception occurred".
+- Remember `update()` is an asynchronous repaint request — call `grab()` to
+  force synchronous rendering before asserting on cache keys or pixels.
+- Performance-relevant changes: run `uv run benchmarks/list_scroll.py`
+  before and after, and quote both numbers in the PR.
+
+## Translations
+
+The README ships in several languages under `docs/readme/`. English
+(`README.md`) is the source of truth; fixes to translations are welcome and
+are among the easiest first contributions.
+
+## Release checklist
+
+Maintainers only. All build/publish commands are run by a maintainer.
+
+1. Run the full suite: `pytest -v` (all green, including
+   `tests/test_render_cache.py`).
+2. Long-run memory soak: `uv run benchmarks/memory_soak.py` for at least
+   30 minutes; RSS must not grow without bound.
+3. Build: `uv build` — then audit the artifacts:
+    - no `__pycache__`, `.pytest_cache`, `.workbuddy`, or temp files inside
+    - no secrets, tokens, or local paths
+    - `py.typed` present in the wheel
+    - `LICENSE` and README present in the sdist
+4. Bump `__version__` in `src/pyside_iconify/__init__.py`, commit and push.
+5. Tag and push the tag; the publish workflow does the rest (build, wait for
+   approval of the `pypi-release` environment, upload to PyPI, then create
+   the GitHub Release with generated notes):
+
+    ```powershell
+    git tag v1.0.0
+    git push origin v1.0.0
+    ```
+
+   The tag must equal `v` + `__version__`, otherwise the build job fails.
+   To rehearse on TestPyPI, run the "Publish to PyPI" workflow manually and
+   choose `testpypi`.

pyside_iconify-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pyside-iconify contributors
+
+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.

pyside_iconify-1.0.0/PKG-INFO

@@ -0,0 +1,192 @@
+Metadata-Version: 2.5
+Name: pyside-iconify
+Version: 1.0.0
+Summary: An independent Iconify icon integration for PySide6, producing standard QIcon objects.
+Project-URL: Homepage, https://github.com/LingChen-tsjmdlc/pyside-iconify
+Project-URL: Source, https://github.com/LingChen-tsjmdlc/pyside-iconify
+Project-URL: Issues, https://github.com/LingChen-tsjmdlc/pyside-iconify/issues
+Author: jerrylu
+License-Expression: MIT
+License-File: LICENSE
+Keywords: iconify,icons,pyside,pyside6,qt,svg
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: MacOS X
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Environment :: X11 Applications :: Qt
+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.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: User Interfaces
+Classifier: Typing :: Typed
+Requires-Python: <3.15,>=3.10
+Provides-Extra: pyside2
+Requires-Dist: pyside2==5.15.2.1; (python_version < '3.11') and extra == 'pyside2'
+Provides-Extra: pyside6
+Requires-Dist: pyside6-essentials<7,>=6.11.2; (python_version >= '3.14') and extra == 'pyside6'
+Requires-Dist: pyside6-essentials<7,>=6.8.3; (python_version >= '3.10' and python_version < '3.14') and extra == 'pyside6'
+Description-Content-Type: text/markdown
+
+# pyside-iconify
+
+**Give `QIcon` a data source.**
+
+English | [中文](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/readme/README.zh-CN.md) | [日本語](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/readme/README.ja.md) | [한국어](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/readme/README.ko.md) | [Español](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/readme/README.es.md) | [Français](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/readme/README.fr.md) | [Deutsch](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/readme/README.de.md) | [Русский](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/readme/README.ru.md) | [Português (BR)](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/readme/README.pt-BR.md)
+
+```python
+IconWidget("mdi:home", color="red")
+```
+
+One line, one icon. No SVG or PNG files to manage — icons are fetched on demand
+from the [Iconify](https://iconify.design) ecosystem by name and cached
+automatically. Everything still ends up as a standard `QIcon`, so it works with
+any widget that accepts icons.
+
+> **Status**: under active development, not yet published to PyPI. The public
+> API may still change before the first release.
+>
+> This project is **not** affiliated with the Iconify project.
+
+## Why
+
+| Without                                   | With pyside-iconify                        |
+| ----------------------------------------- | ------------------------------------------ |
+| `QIcon("assets/home.svg")`                | `get_icon("mdi:home")`                     |
+| Managing SVG/PNG files and resource paths | Icons by name from the Iconify ecosystem   |
+| Multiple asset sets for colors and sizes  | `color`, `size`, `rotate` as parameters    |
+| Per-widget icon plumbing                  | Standard `QIcon`, works everywhere         |
+| Manual light/dark theme icon variants     | Follows the widget's palette automatically |
+
+## Quick start
+
+```powershell
+pip install "pyside-iconify[pyside6]"
+```
+
+```python
+from PySide6.QtWidgets import QApplication, QPushButton
+from pyside_iconify import IconWidget, get_icon
+
+app = QApplication([])
+
+# A standalone icon widget
+icon = IconWidget("mdi:home", size=24, color="red")
+
+# Or hand a standard QIcon to any widget
+button = QPushButton("Settings")
+button.setIcon(get_icon("mdi:cog", size=20))
+
+app.exec()
+```
+
+That is the whole API for the common case. Icons are downloaded on first use,
+cached on disk, and rendered locally afterwards.
+
+## Highlights
+
+- **Theme aware** — with no color set, icons follow the widget's text color and
+  switch automatically between light and dark themes; disabled icons fade
+  instead of turning gray (so multi-color icons fade correctly too)
+- **Full color control** — single color, `{original: replacement}` mapping for
+  multi-color icons, and per-theme overrides (`color_light_theme` /
+  `color_dark_theme`)
+- **Sizes the way you think** — numbers, `(w, h)`, `QSize`, `"24px"`, or
+  `"1.5em"` (follows the widget's font)
+- **HiDPI native** — sizes are logical pixels; physical pixels are rendered
+  per screen scale factor, no @2x/@3x asset sets
+- **Loading vs. missing are distinct** — loading shows blank, a confirmed miss
+  shows a built-in placeholder and emits `failed`; optional `fallback` icon
+- **QSS friendly** — `qss="toolbar primary"` tags for grouping, style with
+  native `setStyleSheet()`; priority: parameters → QSS → theme
+- **Typed and logged** — full type hints with `py.typed`, standard `logging`
+  (silent by default)
+
+## Parameters
+
+Shared by `IconWidget` and `get_icon`:
+
+```python
+get_icon(name, *, size=24, color=None, color_light_theme=None,
+         color_dark_theme=None, selected_color=None, opacity=1.0,
+         width=None, height=None, rotate=0, spin=False,
+         h_flip=False, v_flip=False)
+
+IconWidget(name, *, ..., hover_color=None, qss=None, parent=None)
+```
+
+| Parameter                                | Meaning                                                                |
+| ---------------------------------------- | ---------------------------------------------------------------------- |
+| `name`                                   | Icon name like `"mdi:home"`, or inline icon data                       |
+| `size`                                   | Number, `(w, h)`, `QSize`, `"24px"`, or `"1.5em"`                      |
+| `color`                                  | A color, or a `{original: replacement}` mapping                        |
+| `color_light_theme` / `color_dark_theme` | Per-theme overrides, win over `color`                                  |
+| `selected_color`                         | Color when the item is selected (item views)                           |
+| `hover_color`                            | IconWidget / `set_icon` hover color — explicit opt-in                  |
+| `opacity`                                | Overall opacity 0–1; multiplied with color alpha                       |
+| `width` / `height`                       | Non-square icons; win over `size`                                      |
+| `rotate`                                 | Any angle in degrees, auto-shrunk to avoid clipping                    |
+| `spin`                                   | Continuous rotation for loading indicators                             |
+| `h_flip` / `v_flip`                      | Horizontal / vertical flip                                             |
+| `qss`                                    | QSS grouping tags, `IconWidget[qss~="tag"]` selector (IconWidget only) |
+
+Colors accept CSS/SVG names, HEX 3/4/6/8 digit (`#RRGGBBAA` order),
+`rgb()/rgba()/hsl()/hsla()`, tuples, `QColor`, and `Qt.GlobalColor`.
+Unparseable colors raise instead of silently turning black.
+
+## Offline packaging
+
+For air-gapped machines or zero-external-dependency builds, pack icons at
+release time:
+
+```powershell
+python -m pyside_iconify.pack -o icons.json
+```
+
+```python
+from pyside_iconify import load_bundle
+
+load_bundle("icons.json")  # at app startup; works inside PyInstaller too
+```
+
+See `src/pyside_iconify/pack.py` and `tests/test_pack_integration.py` for the
+full CLI and API. Local data always takes priority over the network.
+
+## Performance
+
+Three-layer cache (icon data → SVG text → rendered bitmaps) with a memory
+budget, per-frame work kept to a cache lookup and one `drawPixmap`. A 1000-row
+`QListWidget` builds in ~270 ms and scrolls at native speed. For large grids
+use item views with `get_icon`; `IconWidget` is meant for standalone icon
+slots.
+
+## Support scope
+
+| Item         | Scope                             |
+| ------------ | --------------------------------- |
+| Python       | 3.10 – 3.14                       |
+| Qt binding   | PySide6                           |
+| OS           | Windows, macOS, Linux (CI on macOS) |
+| PySide2/PyQt | Not supported (PyQt6 maybe later) |
+
+## Development
+
+```powershell
+uv sync --extra pyside6 --group test
+$env:QT_QPA_PLATFORM = "offscreen"
+pytest -v
+```
+
+- Contributing guide and release checklist: [CONTRIBUTING.md](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/CONTRIBUTING.md)
+- Architecture and design decisions: [docs/architecture.md](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/architecture.md)
+- Roadmap: [docs/roadmap.md](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/roadmap.md)
+- Benchmark: `uv run benchmarks/list_scroll.py`
+
+## License
+
+[MIT](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/LICENSE). Icon collections are subject to their own licenses; Qt is
+licensed separately by its copyright holders.

pyside_iconify-1.0.0/README.md

@@ -0,0 +1,158 @@
+# pyside-iconify
+
+**Give `QIcon` a data source.**
+
+English | [中文](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/readme/README.zh-CN.md) | [日本語](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/readme/README.ja.md) | [한국어](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/readme/README.ko.md) | [Español](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/readme/README.es.md) | [Français](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/readme/README.fr.md) | [Deutsch](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/readme/README.de.md) | [Русский](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/readme/README.ru.md) | [Português (BR)](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/readme/README.pt-BR.md)
+
+```python
+IconWidget("mdi:home", color="red")
+```
+
+One line, one icon. No SVG or PNG files to manage — icons are fetched on demand
+from the [Iconify](https://iconify.design) ecosystem by name and cached
+automatically. Everything still ends up as a standard `QIcon`, so it works with
+any widget that accepts icons.
+
+> **Status**: under active development, not yet published to PyPI. The public
+> API may still change before the first release.
+>
+> This project is **not** affiliated with the Iconify project.
+
+## Why
+
+| Without                                   | With pyside-iconify                        |
+| ----------------------------------------- | ------------------------------------------ |
+| `QIcon("assets/home.svg")`                | `get_icon("mdi:home")`                     |
+| Managing SVG/PNG files and resource paths | Icons by name from the Iconify ecosystem   |
+| Multiple asset sets for colors and sizes  | `color`, `size`, `rotate` as parameters    |
+| Per-widget icon plumbing                  | Standard `QIcon`, works everywhere         |
+| Manual light/dark theme icon variants     | Follows the widget's palette automatically |
+
+## Quick start
+
+```powershell
+pip install "pyside-iconify[pyside6]"
+```
+
+```python
+from PySide6.QtWidgets import QApplication, QPushButton
+from pyside_iconify import IconWidget, get_icon
+
+app = QApplication([])
+
+# A standalone icon widget
+icon = IconWidget("mdi:home", size=24, color="red")
+
+# Or hand a standard QIcon to any widget
+button = QPushButton("Settings")
+button.setIcon(get_icon("mdi:cog", size=20))
+
+app.exec()
+```
+
+That is the whole API for the common case. Icons are downloaded on first use,
+cached on disk, and rendered locally afterwards.
+
+## Highlights
+
+- **Theme aware** — with no color set, icons follow the widget's text color and
+  switch automatically between light and dark themes; disabled icons fade
+  instead of turning gray (so multi-color icons fade correctly too)
+- **Full color control** — single color, `{original: replacement}` mapping for
+  multi-color icons, and per-theme overrides (`color_light_theme` /
+  `color_dark_theme`)
+- **Sizes the way you think** — numbers, `(w, h)`, `QSize`, `"24px"`, or
+  `"1.5em"` (follows the widget's font)
+- **HiDPI native** — sizes are logical pixels; physical pixels are rendered
+  per screen scale factor, no @2x/@3x asset sets
+- **Loading vs. missing are distinct** — loading shows blank, a confirmed miss
+  shows a built-in placeholder and emits `failed`; optional `fallback` icon
+- **QSS friendly** — `qss="toolbar primary"` tags for grouping, style with
+  native `setStyleSheet()`; priority: parameters → QSS → theme
+- **Typed and logged** — full type hints with `py.typed`, standard `logging`
+  (silent by default)
+
+## Parameters
+
+Shared by `IconWidget` and `get_icon`:
+
+```python
+get_icon(name, *, size=24, color=None, color_light_theme=None,
+         color_dark_theme=None, selected_color=None, opacity=1.0,
+         width=None, height=None, rotate=0, spin=False,
+         h_flip=False, v_flip=False)
+
+IconWidget(name, *, ..., hover_color=None, qss=None, parent=None)
+```
+
+| Parameter                                | Meaning                                                                |
+| ---------------------------------------- | ---------------------------------------------------------------------- |
+| `name`                                   | Icon name like `"mdi:home"`, or inline icon data                       |
+| `size`                                   | Number, `(w, h)`, `QSize`, `"24px"`, or `"1.5em"`                      |
+| `color`                                  | A color, or a `{original: replacement}` mapping                        |
+| `color_light_theme` / `color_dark_theme` | Per-theme overrides, win over `color`                                  |
+| `selected_color`                         | Color when the item is selected (item views)                           |
+| `hover_color`                            | IconWidget / `set_icon` hover color — explicit opt-in                  |
+| `opacity`                                | Overall opacity 0–1; multiplied with color alpha                       |
+| `width` / `height`                       | Non-square icons; win over `size`                                      |
+| `rotate`                                 | Any angle in degrees, auto-shrunk to avoid clipping                    |
+| `spin`                                   | Continuous rotation for loading indicators                             |
+| `h_flip` / `v_flip`                      | Horizontal / vertical flip                                             |
+| `qss`                                    | QSS grouping tags, `IconWidget[qss~="tag"]` selector (IconWidget only) |
+
+Colors accept CSS/SVG names, HEX 3/4/6/8 digit (`#RRGGBBAA` order),
+`rgb()/rgba()/hsl()/hsla()`, tuples, `QColor`, and `Qt.GlobalColor`.
+Unparseable colors raise instead of silently turning black.
+
+## Offline packaging
+
+For air-gapped machines or zero-external-dependency builds, pack icons at
+release time:
+
+```powershell
+python -m pyside_iconify.pack -o icons.json
+```
+
+```python
+from pyside_iconify import load_bundle
+
+load_bundle("icons.json")  # at app startup; works inside PyInstaller too
+```
+
+See `src/pyside_iconify/pack.py` and `tests/test_pack_integration.py` for the
+full CLI and API. Local data always takes priority over the network.
+
+## Performance
+
+Three-layer cache (icon data → SVG text → rendered bitmaps) with a memory
+budget, per-frame work kept to a cache lookup and one `drawPixmap`. A 1000-row
+`QListWidget` builds in ~270 ms and scrolls at native speed. For large grids
+use item views with `get_icon`; `IconWidget` is meant for standalone icon
+slots.
+
+## Support scope
+
+| Item         | Scope                             |
+| ------------ | --------------------------------- |
+| Python       | 3.10 – 3.14                       |
+| Qt binding   | PySide6                           |
+| OS           | Windows, macOS, Linux (CI on macOS) |
+| PySide2/PyQt | Not supported (PyQt6 maybe later) |
+
+## Development
+
+```powershell
+uv sync --extra pyside6 --group test
+$env:QT_QPA_PLATFORM = "offscreen"
+pytest -v
+```
+
+- Contributing guide and release checklist: [CONTRIBUTING.md](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/CONTRIBUTING.md)
+- Architecture and design decisions: [docs/architecture.md](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/architecture.md)
+- Roadmap: [docs/roadmap.md](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/docs/roadmap.md)
+- Benchmark: `uv run benchmarks/list_scroll.py`
+
+## License
+
+[MIT](https://github.com/LingChen-tsjmdlc/pyside-iconify/blob/main/LICENSE). Icon collections are subject to their own licenses; Qt is
+licensed separately by its copyright holders.

pyside_iconify-1.0.0/benchmarks/leak_probe.py

@@ -0,0 +1,54 @@
+"""Diagnose the soak leak: diff two tracemalloc snapshots across cycles."""
+
+from __future__ import annotations
+
+import gc
+import sys
+import tracemalloc
+
+sys.path.insert(0, "benchmarks")
+sys.path.insert(0, "src")
+
+from PySide6.QtCore import QEvent  # noqa: E402
+from PySide6.QtWidgets import QApplication, QTabWidget  # noqa: E402
+
+import memory_soak  # noqa: E402
+
+app = QApplication([])
+memory_soak.register_icons()
+
+window = QTabWidget()
+window.resize(800, 600)
+window.show()
+app.processEvents()
+
+tracemalloc.start(25)
+
+
+def run_cycles(n: int) -> None:
+    for _ in range(n):
+        lw, area = memory_soak.build_tabs()
+        while window.count():
+            page = window.widget(0)
+            window.removeTab(0)
+            page.deleteLater()
+        window.addTab(lw, "list")
+        window.addTab(area, "grid")
+        app.processEvents()
+        app.sendPostedEvents(None, QEvent.Type.DeferredDelete)
+        gc.collect()
+
+
+run_cycles(3)
+gc.collect()
+snap1 = tracemalloc.take_snapshot()
+
+run_cycles(10)
+gc.collect()
+snap2 = tracemalloc.take_snapshot()
+
+current, _ = tracemalloc.get_traced_memory()
+print(f"traced now: {current / 1e6:.1f} MB")
+print("=== top growth between snapshots ===")
+for stat in snap2.compare_to(snap1, "lineno")[:12]:
+    print(f"{stat.size_diff / 1e6:+8.2f} MB  {stat.count_diff:+6d}  {stat.traceback[0]}")