tkdeft 0.1.2__tar.gz → 0.2.0__tar.gz

tkdeft-0.2.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: tkdeft
+Version: 0.2.0
+Summary: 使用tkinter+tksvg开发的现代化界面库
+Author: XiangQinxi
+Author-email: xiangqinxi@outlook.com
+Requires-Python: >=3.7,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+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
+Provides-Extra: cairo
+Provides-Extra: raster
+Provides-Extra: skia
+Requires-Dist: easydict (>=1.13,<2.0)
+Requires-Dist: numpy
+Requires-Dist: pillow (>=10.2)
+Requires-Dist: pycairo (>=1.29,<2.0) ; extra == "cairo" or extra == "raster"
+Requires-Dist: skia-python (>=138.0,<139.0) ; extra == "skia" or extra == "raster"
+Requires-Dist: svgwrite (>=1.4.3,<2.0.0)
+Requires-Dist: tkextrafont (>=0.6.3,<0.7.0)
+Requires-Dist: tksvg (>=0.7.4,<0.8.0)
+Project-URL: Documentation, https://tkdeft.netlify.app
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# tkdeft
+
+</div>
+
+[![Netlify Status](https://api.netlify.com/api/v1/badges/c7626ce2-9556-4e4f-b28e-36dc0b513398/deploy-status)](https://app.netlify.com/sites/tkdeft/deploys)
+
+意为`灵巧`，灵活轻巧好用
+
+继`tkadw`之后的`tkinter`的现代化界面库
+
+> 开发中
+
+---
+## 注意
+> [!NOTE]
+> 这里呢，已经成为[tkfluent](https://pypi.org/project/tkfluent)的基础库了，不含[tkfluent](https://pypi.org/project/tkfluent)的组件。
+> 如果你想体验扩展界面库的效果，请去[tkfluent](https://pypi.org/project/tkfluent)查阅。
+
+
+## 原理
+先使用`svgwrite`进行矢量作图（默认会将其存储到临时文件夹中），再用`tksvg`打开图片，将图片利用`Canvas`或`Label`显示出来
+[index.md](docs/docs/index.md)
+> 这其中还是有些坑的，比如图片不显示等，导致我以前想做，却放弃了，现在知道错误所在了
+
+## 绘制引擎
+`tkdeft` 现在把"**画什么**"和"**用什么画**"分开了。组件只需要描述一个
+`RoundRectSpec`（尺寸、圆角、填充、描边……），具体由哪个引擎栅格化是可切换的。
+
+```python
+from tkdeft.engines import set_engine, list_engines, cache_stats
+
+print(list_engines())      # {'tksvg': True, 'wand': True, 'skia': True, 'pillow': True, 'cairo': True}
+set_engine("skia")         # 或 set_engine(2)
+print(cache_stats())       # 缓存命中率，便于诊断
+```
+
+| 引擎 | 类型 | 说明 | 额外依赖 |
+| --- | --- | --- | --- |
+| `tksvg` | SVG | 默认，保持既有行为 | 无 |
+| `wand` | SVG | 经 Wand(ImageMagick) 转 PNG | `Wand` |
+| `skia` | 栅格 | skia-python，进程内出图，画质与速度最好 | `pip install tkdeft[skia]` |
+| `pillow` | 栅格 | Pillow 超采样，**永远可用** | 无（Pillow 是硬依赖） |
+| `cairo` | 栅格 | pycairo | `pip install tkdeft[cairo]` |
+
+栅格引擎不写临时文件、不解析 SVG、不碰磁盘；渲染结果按规格缓存，
+**同尺寸同配色的一组控件共用同一张图片**。
+
+### 实测（120×32 圆角矩形，本机）
+
+| 场景 | 优化前 | 仅修基础设施 | + skia 引擎 |
+| --- | --- | --- | --- |
+| 圆角矩形（尺寸各异） | 13.81 ms | 4.94 ms | **1.26 ms** |
+| 圆角矩形（参数相同） | 10.80 ms | 4.33 ms | **0.02 ms** |
+| 按钮重绘 | 5.95 ms | 2.86 ms | **0.15 ms** |
+| 按钮 hover 往返 | 13.65 ms | 6.08 ms | **0.26 ms** |
+| 20 个按钮批量重绘 | 139.9 ms | 110.4 ms | **2.93 ms** |
+
+复现：`python benchmarks/run_all.py`
+
+## 已修复的缺陷
+这一轮审查中定位并修掉的真实问题（都不是"风格问题"）：
+
+| 问题 | 影响 |
+| --- | --- |
+| `DSvgDraw.temppath()` 每次调用都 `mkstemp()` 且**从不关闭返回的 fd** | 每绘制一帧泄漏一个句柄，并在临时目录留下一个残留文件 |
+| `DDrawWidget.__init__` 一次性 `mkstemp()` 四个临时文件 | 每个控件创建即泄漏 4 个句柄（20 个按钮 = 80 个） |
+| `DCanvas.create_round_rectangle` 只把图片存进 `self._img` / `self._tkimg` | 同一画布上多张图片时，除最后一张外都会被 GC，**画布 item 变空白** |
+| `RenderManager._render_all` 调用 `widget.winfo_zorder()` | `tkinter` **没有**这个方法，只要有脏控件就抛 `AttributeError` |
+| `RenderManager._schedule_render` 里 `tk._default_root or list(...)[0]` | 两者都不可用时 `IndexError` |
+| `_draw` 结尾又 `mark_dirty(self)` | 集中式调度下同一控件被重绘两遍 |
+| svgwrite 生成的矩形用 `translate(0.5,0.5)` + 整宽整高 | 描边中心线压在画布边界上，**下边框和右边框被完全裁掉** |
+| `create_svg_image` 对 `way` 未做兜底 | 回退路径遇到非 0/1 的渲染器编号会直接失败 |
+
+## 计划
+未来我打算先制作出`SunValley`设计的库然后就去做别的项目，[tkfluent](https://pypi.org/project/tkfluent)
+
+至于完整文档，我后面会加紧制作的。
+
+
+设计来源： https://pixso.cn/community/file/ItC5JH1TOwj15EeOPcY7LQ?from_share
+
+### 为什么不像tkadw一样做跟易用的主题？
+因为`svg`能实现很多漂亮的组件，而我套的模板可能不对其它设计其太大的作用
+
+所以我将这个设计库放在这里当做模板，供其它设计者参考使用。
+
+
+## 更新日志
+### 2024-01-22
+发布`0.0.1`版本，模板组件包括`DButton`
+
+### 2023-01-23
+发布`0.0.2`版本，补充模板组件`DEntry`、`DFrame`、`DText`, `DBadge`
+
+### 2023-01-25
+发布`0.0.3` `0.0.4`版本，粗心了，两次补充依赖
+发布`0.0.5`版本，模板组件主题由`theme(mode=..., style=...)`设置，不再使用如`DDarkButton`这样的，添加`DWindow.wincustom`自定义窗口（仅限Windows）
+发布`0.0.6`版本，模板组件`DBadge`补充样式`style=accent`，并对自定义窗口进行稍微调整
+
+### 2023-01-26
+发布`0.0.7`版本，模板库`Fluent`已移至`tkfluent`库
+
+### 2024-09-16
+发布`0.0.9`版本，一些小修改
+
+### 2025-06-26
+发布`0.1.0`版本，完善功能
+
+### 2026-09-12
+发布`0.2.0`版本：
+
+* 新增 `tkdeft.engines` 绘制引擎层，可插拔切换 `tksvg` / `wand` / `skia` / `pillow` / `cairo`
+* 新增进程内栅格引擎（skia-python / Pillow / pycairo），完全不落盘
+* 新增按规格缓存的图片缓存，参数相同的绘制结果直接复用
+* 新增 SVG 形状助手 `tkdeft.svg`，统一并修正圆角矩形几何
+* 修复临时文件 / fd 泄漏、`PhotoImage` 被 GC 导致画面空白、
+  `RenderManager` 的 `winfo_zorder` 崩溃等问题
+* 详细缺陷清单与性能数据见 [benchmarks/](benchmarks/)

tkdeft-0.2.0/README.md

@@ -0,0 +1,120 @@
+<div align="center">
+
+# tkdeft
+
+</div>
+
+[![Netlify Status](https://api.netlify.com/api/v1/badges/c7626ce2-9556-4e4f-b28e-36dc0b513398/deploy-status)](https://app.netlify.com/sites/tkdeft/deploys)
+
+意为`灵巧`，灵活轻巧好用
+
+继`tkadw`之后的`tkinter`的现代化界面库
+
+> 开发中
+
+---
+## 注意
+> [!NOTE]
+> 这里呢，已经成为[tkfluent](https://pypi.org/project/tkfluent)的基础库了，不含[tkfluent](https://pypi.org/project/tkfluent)的组件。
+> 如果你想体验扩展界面库的效果，请去[tkfluent](https://pypi.org/project/tkfluent)查阅。
+
+
+## 原理
+先使用`svgwrite`进行矢量作图（默认会将其存储到临时文件夹中），再用`tksvg`打开图片，将图片利用`Canvas`或`Label`显示出来
+[index.md](docs/docs/index.md)
+> 这其中还是有些坑的，比如图片不显示等，导致我以前想做，却放弃了，现在知道错误所在了
+
+## 绘制引擎
+`tkdeft` 现在把"**画什么**"和"**用什么画**"分开了。组件只需要描述一个
+`RoundRectSpec`（尺寸、圆角、填充、描边……），具体由哪个引擎栅格化是可切换的。
+
+```python
+from tkdeft.engines import set_engine, list_engines, cache_stats
+
+print(list_engines())      # {'tksvg': True, 'wand': True, 'skia': True, 'pillow': True, 'cairo': True}
+set_engine("skia")         # 或 set_engine(2)
+print(cache_stats())       # 缓存命中率，便于诊断
+```
+
+| 引擎 | 类型 | 说明 | 额外依赖 |
+| --- | --- | --- | --- |
+| `tksvg` | SVG | 默认，保持既有行为 | 无 |
+| `wand` | SVG | 经 Wand(ImageMagick) 转 PNG | `Wand` |
+| `skia` | 栅格 | skia-python，进程内出图，画质与速度最好 | `pip install tkdeft[skia]` |
+| `pillow` | 栅格 | Pillow 超采样，**永远可用** | 无（Pillow 是硬依赖） |
+| `cairo` | 栅格 | pycairo | `pip install tkdeft[cairo]` |
+
+栅格引擎不写临时文件、不解析 SVG、不碰磁盘；渲染结果按规格缓存，
+**同尺寸同配色的一组控件共用同一张图片**。
+
+### 实测（120×32 圆角矩形，本机）
+
+| 场景 | 优化前 | 仅修基础设施 | + skia 引擎 |
+| --- | --- | --- | --- |
+| 圆角矩形（尺寸各异） | 13.81 ms | 4.94 ms | **1.26 ms** |
+| 圆角矩形（参数相同） | 10.80 ms | 4.33 ms | **0.02 ms** |
+| 按钮重绘 | 5.95 ms | 2.86 ms | **0.15 ms** |
+| 按钮 hover 往返 | 13.65 ms | 6.08 ms | **0.26 ms** |
+| 20 个按钮批量重绘 | 139.9 ms | 110.4 ms | **2.93 ms** |
+
+复现：`python benchmarks/run_all.py`
+
+## 已修复的缺陷
+这一轮审查中定位并修掉的真实问题（都不是"风格问题"）：
+
+| 问题 | 影响 |
+| --- | --- |
+| `DSvgDraw.temppath()` 每次调用都 `mkstemp()` 且**从不关闭返回的 fd** | 每绘制一帧泄漏一个句柄，并在临时目录留下一个残留文件 |
+| `DDrawWidget.__init__` 一次性 `mkstemp()` 四个临时文件 | 每个控件创建即泄漏 4 个句柄（20 个按钮 = 80 个） |
+| `DCanvas.create_round_rectangle` 只把图片存进 `self._img` / `self._tkimg` | 同一画布上多张图片时，除最后一张外都会被 GC，**画布 item 变空白** |
+| `RenderManager._render_all` 调用 `widget.winfo_zorder()` | `tkinter` **没有**这个方法，只要有脏控件就抛 `AttributeError` |
+| `RenderManager._schedule_render` 里 `tk._default_root or list(...)[0]` | 两者都不可用时 `IndexError` |
+| `_draw` 结尾又 `mark_dirty(self)` | 集中式调度下同一控件被重绘两遍 |
+| svgwrite 生成的矩形用 `translate(0.5,0.5)` + 整宽整高 | 描边中心线压在画布边界上，**下边框和右边框被完全裁掉** |
+| `create_svg_image` 对 `way` 未做兜底 | 回退路径遇到非 0/1 的渲染器编号会直接失败 |
+
+## 计划
+未来我打算先制作出`SunValley`设计的库然后就去做别的项目，[tkfluent](https://pypi.org/project/tkfluent)
+
+至于完整文档，我后面会加紧制作的。
+
+
+设计来源： https://pixso.cn/community/file/ItC5JH1TOwj15EeOPcY7LQ?from_share
+
+### 为什么不像tkadw一样做跟易用的主题？
+因为`svg`能实现很多漂亮的组件，而我套的模板可能不对其它设计其太大的作用
+
+所以我将这个设计库放在这里当做模板，供其它设计者参考使用。
+
+
+## 更新日志
+### 2024-01-22
+发布`0.0.1`版本，模板组件包括`DButton`
+
+### 2023-01-23
+发布`0.0.2`版本，补充模板组件`DEntry`、`DFrame`、`DText`, `DBadge`
+
+### 2023-01-25
+发布`0.0.3` `0.0.4`版本，粗心了，两次补充依赖
+发布`0.0.5`版本，模板组件主题由`theme(mode=..., style=...)`设置，不再使用如`DDarkButton`这样的，添加`DWindow.wincustom`自定义窗口（仅限Windows）
+发布`0.0.6`版本，模板组件`DBadge`补充样式`style=accent`，并对自定义窗口进行稍微调整
+
+### 2023-01-26
+发布`0.0.7`版本，模板库`Fluent`已移至`tkfluent`库
+
+### 2024-09-16
+发布`0.0.9`版本，一些小修改
+
+### 2025-06-26
+发布`0.1.0`版本，完善功能
+
+### 2026-09-12
+发布`0.2.0`版本：
+
+* 新增 `tkdeft.engines` 绘制引擎层，可插拔切换 `tksvg` / `wand` / `skia` / `pillow` / `cairo`
+* 新增进程内栅格引擎（skia-python / Pillow / pycairo），完全不落盘
+* 新增按规格缓存的图片缓存，参数相同的绘制结果直接复用
+* 新增 SVG 形状助手 `tkdeft.svg`，统一并修正圆角矩形几何
+* 修复临时文件 / fd 泄漏、`PhotoImage` 被 GC 导致画面空白、
+  `RenderManager` 的 `winfo_zorder` 崩溃等问题
+* 详细缺陷清单与性能数据见 [benchmarks/](benchmarks/)

tkdeft-0.2.0/pyproject.toml

@@ -0,0 +1,33 @@
+[tool.poetry]
+name = "tkdeft"
+version = "0.2.0"
+description = "使用tkinter+tksvg开发的现代化界面库"
+authors = ["XiangQinxi <xiangqinxi@outlook.com>"]
+readme = "README.md"
+documentation = "https://tkdeft.netlify.app"
+
+[tool.poetry.dependencies]
+easydict = "^1.13"
+python = "^3.7"
+tksvg = "^0.7.4"
+tkextrafont = "^0.6.3"
+svgwrite = "^1.4.3"
+# 不设上界：Pillow 10 / 11 / 12 都实测可用（^10.2.0 会逼 pip 把已经装好的
+# 新版 Pillow 降级，影响同一环境里的其它项目）。用到的最低特性是
+# ImageDraw.rounded_rectangle（Pillow 8.2 引入）。
+pillow = ">=10.2"
+numpy = "*"
+
+# 可选的进程内栅格绘制引擎。不装也能用（会退回 tksvg 或 Pillow 引擎）。
+skia-python = { version = "^138.0", optional = true }
+pycairo = { version = "^1.29", optional = true }
+
+[tool.poetry.extras]
+# 画质与速度最好的一组后端，推荐安装
+skia = ["skia-python"]
+cairo = ["pycairo"]
+raster = ["skia-python", "pycairo"]
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

tkdeft-0.2.0/tkdeft/__init__.py

@@ -0,0 +1,32 @@
+"""tkdeft —— 把矢量绘图变成 Tkinter 组件的底座。
+
+本包不提供具体组件，只提供零件：
+
+* :mod:`tkdeft.engines` —— 可插拔的绘制引擎（tksvg / wand / skia / pillow / cairo）
+* :mod:`tkdeft.svg` —— SVG 形状助手（统一的圆角矩形几何）
+* :mod:`tkdeft.windows` —— ``DCanvas`` / ``DDraw`` / ``DDrawWidget``
+* :mod:`tkdeft.object` —— ``DObject`` 配置容器
+
+快速上手::
+
+    from tkdeft.engines import RoundRectSpec, render_roundrect, set_engine
+
+    set_engine("skia")
+    photo = render_roundrect(
+        RoundRectSpec(width=120, height=32, rx=6, fill="#ffffff"),
+        master=my_canvas,
+    )
+"""
+
+from . import engines
+from .utility import *
+from .windows import *
+from .object import DObject
+
+#: 版本号。tkfluent 会据此判断环境里的 tkdeft 是否够新。
+#: 注意：需要与 pyproject.toml 里的 version 保持一致。
+__version__ = "0.2.0"
+
+#: 是否提供绘制引擎层（tkfluent >= 0.2.0 依赖它）。
+#: 旧版本没有这个子包，用它做能力探测比解析版本号更直接。
+HAS_ENGINES = True

tkdeft-0.2.0/tkdeft/engines/__init__.py

@@ -0,0 +1,168 @@
+"""tkdeft 绘制引擎层。
+
+对外主要接口
+------------
+::
+
+    from tkdeft.engines import set_engine, get_engine, render_roundrect, cache_stats
+
+    set_engine("skia")          # 或 set_engine(2)
+    photo = render_roundrect(spec, master=canvas)   # -> PhotoImage | None
+
+``render_*`` 返回 ``None`` 表示"当前引擎不参与这条路径"，调用方应回退到
+既有的 svgwrite + tksvg 实现。这样 SVG 引擎与栅格引擎可以共存于同一套组件代码。
+
+内置引擎
+--------
+====== ========== ==================================================
+名字    类型        说明
+====== ========== ==================================================
+tksvg  SVG（文件） 默认，保持既有行为完全不变
+wand   SVG（文件） 经 Wand 转 PNG，兼容旧 ``renderer=1``
+skia   栅格        skia-python，质量与速度最好
+pillow 栅格        Pillow 超采样，零额外依赖，永远可用
+cairo  栅格        pycairo
+====== ========== ==================================================
+"""
+
+from __future__ import annotations
+
+import warnings
+from typing import Optional
+
+from .base import (
+    DrawEngine,
+    RoundRectSpec,
+    SvgEngine,
+    ThumbSpec,
+    TrackSpec,
+    get_engine,
+    get_engine_name,
+    list_engines,
+    register_engine,
+    set_engine,
+)
+from .cache import (
+    cache_stats,
+    clear_cache,
+    get_cache,
+    set_cache_budget,
+)
+from .cairo_engine import CairoEngine
+from .colors import parse_color, parse_opacity
+from .pillow_engine import PillowEngine
+from .skia_engine import SkiaEngine
+
+__all__ = [
+    "DrawEngine",
+    "RoundRectSpec",
+    "TrackSpec",
+    "ThumbSpec",
+    "SvgEngine",
+    "register_engine",
+    "get_engine",
+    "get_engine_name",
+    "set_engine",
+    "list_engines",
+    "render_roundrect",
+    "render_track",
+    "render_thumb",
+    "to_photoimage",
+    "clear_cache",
+    "cache_stats",
+    "set_cache_budget",
+    "parse_color",
+    "parse_opacity",
+    "engine_error",
+]
+
+# --------------------------------------------------------------------------
+# 引擎注册
+# --------------------------------------------------------------------------
+class TksvgEngine(SvgEngine):
+    name = "tksvg"
+    requires = ("tksvg",)
+    description = "svgwrite + tksvg（默认，保持既有行为）"
+
+
+class WandEngine(SvgEngine):
+    name = "wand"
+    requires = ("wand",)
+    description = "svgwrite + Wand（ImageMagick）"
+
+
+#: 与历史 ``set_renderer(int)`` API 的对应关系
+RENDERER_INDEX = {0: "tksvg", 1: "wand", 2: "skia", 3: "pillow", 4: "cairo"}
+
+register_engine(TksvgEngine(), aliases=("0", "svg", "default"), default=True)
+register_engine(WandEngine(), aliases=("1", "1.0"))
+register_engine(SkiaEngine(), aliases=("2",))
+register_engine(PillowEngine(), aliases=("3", "pil"))
+register_engine(CairoEngine(), aliases=("4", "pycairo"))
+
+#: 最近一次栅格化失败的原因，便于诊断（``None`` 表示正常）
+engine_error: Optional[str] = None
+
+_WARNED: "set[str]" = set()
+
+
+def _warn_once(engine_name: str, exc: BaseException) -> None:
+    global engine_error
+    engine_error = f"{engine_name}: {type(exc).__name__}: {exc}"
+    if engine_name in _WARNED:
+        return
+    _WARNED.add(engine_name)
+    warnings.warn(
+        f"绘制引擎 {engine_name!r} 渲染失败，已回退到 SVG 路径。"
+        f"原始错误：{engine_error}",
+        RuntimeWarning,
+        stacklevel=3,
+    )
+
+
+def to_photoimage(image, master):
+    """``PIL.Image`` → ``tkinter`` 的 ``PhotoImage``。"""
+    from PIL import ImageTk
+
+    return ImageTk.PhotoImage(image, master=master)
+
+
+def _render(kind: str, spec, master):
+    """三种图元共用的"查缓存 → 渲染 → 转 PhotoImage → 回填缓存"流程。"""
+    engine = get_engine()
+    if not engine.is_raster:
+        return None
+
+    key = (engine.name, kind, spec)
+    cache = get_cache(master)
+    cached = cache.get(key)
+    if cached is not None:
+        return cached
+
+    try:
+        image = getattr(engine, f"render_{kind}")(spec)
+    except Exception as exc:  # 单个引擎出错不应让整个界面挂掉
+        _warn_once(engine.name, exc)
+        return None
+
+    if image is None:
+        return None
+
+    photo = to_photoimage(image, master)
+    cache.put(key, photo, max(1, int(spec.width) * int(spec.height)))
+    return photo
+
+
+def render_roundrect(spec: RoundRectSpec, master):
+    """渲染圆角矩形；当前引擎不支持时返回 ``None``。"""
+    return _render("roundrect", spec, master)
+
+
+def render_track(spec: TrackSpec, master):
+    """渲染滑块进度条槽；当前引擎不支持时返回 ``None``。"""
+    return _render("track", spec, master)
+
+
+def render_thumb(spec: ThumbSpec, master):
+    """渲染滑块把手；当前引擎不支持时返回 ``None``。"""
+    return _render("thumb", spec, master)