tkdeft 0.1.2__tar.gz → 0.3.0__tar.gz

tkdeft-0.3.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: tkdeft
+Version: 0.3.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)
+
+意为`灵巧`，灵活轻巧好用
+
+一句话：**把矢量绘图变成 Tkinter 控件的底座。**
+
+> 开发中
+
+---
+
+## 注意
+
+> [!NOTE]
+> 这里呢，已经成为[tkfluent](https://pypi.org/project/tkfluent)的基础库了，不含[tkfluent](https://pypi.org/project/tkfluent)的组件。
+> 如果你想体验扩展界面库的效果，请去[tkfluent](https://pypi.org/project/tkfluent)查阅。
+
+用这套零件搭出来的组件库长这样（[tkfluent](https://pypi.org/project/tkfluent)）：
+
+| 浅色 | 深色 |
+| --- | --- |
+| ![浅色](docs/docs/assets/gallery-light.png) | ![深色](docs/docs/assets/gallery-dark.png) |
+
+## 原理
+
+一句话：**先用矢量绘图生成图片，再交给 `Canvas` / `Label` 显示出来。**
+
+具体走哪条路是可切换的：
+
+| 方式 | 过程 |
+| --- | --- |
+| SVG 引擎（默认 `tksvg`） | `svgwrite` 生成 SVG → 写临时文件 → `tksvg` 读回来栅格化 |
+| 栅格引擎（`skia` / `pillow` / `cairo`） | 进程内直接画到位图，**完全不碰磁盘** |
+
+> 这其中还是有些坑的（比如图片不显示——那其实是 `PhotoImage` 被垃圾回收导致的），
+> 完整清单见文档站的[常见问题与排查](docs/docs/usage/faq.md)。
+
+## 快速上手
+
+```bash
+pip install -U tkdeft
+```
+
+```python
+import tkinter
+
+from tkdeft.windows.canvas import DCanvas
+
+root = tkinter.Tk()
+canvas = DCanvas(root, width=240, height=120, background="#f3f3f3")
+canvas.pack()
+
+# 一行画图元：栅格引擎走进程内快速路径，否则自动回退 SVG
+canvas.draw_roundrect(20, 20, 200, 76, 8,
+                      fill="#ffffff", outline="#000000", outline_opacity=0.25)
+
+root.mainloop()
+```
+
+完整文档（安装 / 快速上手 / 概念与架构 / 指南 / API）：
+<https://tkdeft.netlify.app>
+
+## 绘制引擎
+
+`tkdeft` 把"**画什么**"和"**用什么画**"分开了。组件只需要描述一个
+`RoundRectSpec`（尺寸、圆角、填充、描边……），具体由哪个引擎栅格化是可切换的。
+
+同一份规格交给 5 个引擎：
+
+![engine compare](docs/docs/assets/engines-compare.png)
+
+```python
+from tkdeft.engines import set_engine, list_engines, describe_engines, cache_stats
+
+print(list_engines())      # {'tksvg': True, 'wand': True, 'skia': True, ...}
+set_engine("skia")         # 或 set_engine(2)
+print(cache_stats())       # 缓存命中率，便于诊断
+```
+
+| 编号 | 引擎 | 类型 | 说明 | 额外依赖 |
+| --- | --- | --- | --- | --- |
+| 0 | `tksvg` | SVG | 默认，保持既有行为 | 无 |
+| 1 | `wand` | SVG | 经 Wand(ImageMagick) 转 PNG | `Wand` |
+| 2 | `skia` | 栅格 | skia-python，进程内出图，画质与速度最好 | `pip install tkdeft[skia]` |
+| 3 | `pillow` | 栅格 | Pillow 超采样，**永远可用** | 无（Pillow 是硬依赖） |
+| 4 | `cairo` | 栅格 | pycairo | `pip install tkdeft[cairo]` |
+
+栅格引擎不写临时文件、不解析 SVG、不碰磁盘；渲染结果按规格缓存，
+**同尺寸同配色的一组控件共用同一张图片**。
+
+### 实测（120×32 圆角矩形，本机）
+
+![perf](docs/docs/assets/perf-bars.png)
+
+| 场景 | 优化前 | 仅修基础设施 | + 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`（9 项回归 + 性能基准，详见
+[回归与性能](docs/docs/usage/benchmarks.md)）
+
+## 已修复的缺陷
+
+这一轮审查中定位并修掉的真实问题（都不是"风格问题"）：
+
+| 问题 | 影响 |
+| --- | --- |
+| `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 的渲染器编号会直接失败 |
+| `tkdeft.svg` 把 `None` / `"transparent"` 直接交给 svgwrite | 栅格引擎认这两者，svgwrite 只认 `"none"` → 同一份规格换了引擎就 `TypeError` |
+
+## 计划
+
+未来我打算先制作出`SunValley`设计的库然后就去做别的项目，[tkfluent](https://pypi.org/project/tkfluent)
+
+至于完整文档，我后面会加紧制作的。
+
+设计来源： https://pixso.cn/community/file/ItC5JH1TOwj15EeOPcY7LQ?from_share
+
+### 为什么不像tkadw一样做跟易用的主题？
+
+因为`svg`能实现很多漂亮的组件，而我套的模板可能不对其它设计起太大的作用
+
+所以我将这个设计库放在这里当做模板，供其它设计者参考使用。
+
+## 更新日志
+
+版本变更统一记录在文档站的[更新日志](https://tkdeft.netlify.app/blog/)里
+（源文件在 `docs/docs/blog/posts/`），按时间倒序排列：
+
+| 版本 | 一句话 | 发布说明 |
+| --- | --- | --- |
+| `0.3.0` | 把对外接口补齐：统一绘制入口、引擎查询、`DObject` 补全 | [2026-09-13](docs/docs/blog/posts/2026-09-13.md) |
+| `0.2.0` | 可插拔绘制引擎层 + 进程内栅格引擎 + 规格缓存 | [2026-09-12](docs/docs/blog/posts/2026-09-12.md) |
+| `0.1.0` | 完善功能 | [2025-06-26](docs/docs/blog/posts/2025-06-26.md) |
+| 更早 | `0.0.1` – `0.0.9` 的起步阶段 | [回顾](docs/docs/blog/posts/2024-01-26.md) |

tkdeft-0.3.0/README.md

@@ -0,0 +1,151 @@
+<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)
+
+意为`灵巧`，灵活轻巧好用
+
+一句话：**把矢量绘图变成 Tkinter 控件的底座。**
+
+> 开发中
+
+---
+
+## 注意
+
+> [!NOTE]
+> 这里呢，已经成为[tkfluent](https://pypi.org/project/tkfluent)的基础库了，不含[tkfluent](https://pypi.org/project/tkfluent)的组件。
+> 如果你想体验扩展界面库的效果，请去[tkfluent](https://pypi.org/project/tkfluent)查阅。
+
+用这套零件搭出来的组件库长这样（[tkfluent](https://pypi.org/project/tkfluent)）：
+
+| 浅色 | 深色 |
+| --- | --- |
+| ![浅色](docs/docs/assets/gallery-light.png) | ![深色](docs/docs/assets/gallery-dark.png) |
+
+## 原理
+
+一句话：**先用矢量绘图生成图片，再交给 `Canvas` / `Label` 显示出来。**
+
+具体走哪条路是可切换的：
+
+| 方式 | 过程 |
+| --- | --- |
+| SVG 引擎（默认 `tksvg`） | `svgwrite` 生成 SVG → 写临时文件 → `tksvg` 读回来栅格化 |
+| 栅格引擎（`skia` / `pillow` / `cairo`） | 进程内直接画到位图，**完全不碰磁盘** |
+
+> 这其中还是有些坑的（比如图片不显示——那其实是 `PhotoImage` 被垃圾回收导致的），
+> 完整清单见文档站的[常见问题与排查](docs/docs/usage/faq.md)。
+
+## 快速上手
+
+```bash
+pip install -U tkdeft
+```
+
+```python
+import tkinter
+
+from tkdeft.windows.canvas import DCanvas
+
+root = tkinter.Tk()
+canvas = DCanvas(root, width=240, height=120, background="#f3f3f3")
+canvas.pack()
+
+# 一行画图元：栅格引擎走进程内快速路径，否则自动回退 SVG
+canvas.draw_roundrect(20, 20, 200, 76, 8,
+                      fill="#ffffff", outline="#000000", outline_opacity=0.25)
+
+root.mainloop()
+```
+
+完整文档（安装 / 快速上手 / 概念与架构 / 指南 / API）：
+<https://tkdeft.netlify.app>
+
+## 绘制引擎
+
+`tkdeft` 把"**画什么**"和"**用什么画**"分开了。组件只需要描述一个
+`RoundRectSpec`（尺寸、圆角、填充、描边……），具体由哪个引擎栅格化是可切换的。
+
+同一份规格交给 5 个引擎：
+
+![engine compare](docs/docs/assets/engines-compare.png)
+
+```python
+from tkdeft.engines import set_engine, list_engines, describe_engines, cache_stats
+
+print(list_engines())      # {'tksvg': True, 'wand': True, 'skia': True, ...}
+set_engine("skia")         # 或 set_engine(2)
+print(cache_stats())       # 缓存命中率，便于诊断
+```
+
+| 编号 | 引擎 | 类型 | 说明 | 额外依赖 |
+| --- | --- | --- | --- | --- |
+| 0 | `tksvg` | SVG | 默认，保持既有行为 | 无 |
+| 1 | `wand` | SVG | 经 Wand(ImageMagick) 转 PNG | `Wand` |
+| 2 | `skia` | 栅格 | skia-python，进程内出图，画质与速度最好 | `pip install tkdeft[skia]` |
+| 3 | `pillow` | 栅格 | Pillow 超采样，**永远可用** | 无（Pillow 是硬依赖） |
+| 4 | `cairo` | 栅格 | pycairo | `pip install tkdeft[cairo]` |
+
+栅格引擎不写临时文件、不解析 SVG、不碰磁盘；渲染结果按规格缓存，
+**同尺寸同配色的一组控件共用同一张图片**。
+
+### 实测（120×32 圆角矩形，本机）
+
+![perf](docs/docs/assets/perf-bars.png)
+
+| 场景 | 优化前 | 仅修基础设施 | + 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`（9 项回归 + 性能基准，详见
+[回归与性能](docs/docs/usage/benchmarks.md)）
+
+## 已修复的缺陷
+
+这一轮审查中定位并修掉的真实问题（都不是"风格问题"）：
+
+| 问题 | 影响 |
+| --- | --- |
+| `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 的渲染器编号会直接失败 |
+| `tkdeft.svg` 把 `None` / `"transparent"` 直接交给 svgwrite | 栅格引擎认这两者，svgwrite 只认 `"none"` → 同一份规格换了引擎就 `TypeError` |
+
+## 计划
+
+未来我打算先制作出`SunValley`设计的库然后就去做别的项目，[tkfluent](https://pypi.org/project/tkfluent)
+
+至于完整文档，我后面会加紧制作的。
+
+设计来源： https://pixso.cn/community/file/ItC5JH1TOwj15EeOPcY7LQ?from_share
+
+### 为什么不像tkadw一样做跟易用的主题？
+
+因为`svg`能实现很多漂亮的组件，而我套的模板可能不对其它设计起太大的作用
+
+所以我将这个设计库放在这里当做模板，供其它设计者参考使用。
+
+## 更新日志
+
+版本变更统一记录在文档站的[更新日志](https://tkdeft.netlify.app/blog/)里
+（源文件在 `docs/docs/blog/posts/`），按时间倒序排列：
+
+| 版本 | 一句话 | 发布说明 |
+| --- | --- | --- |
+| `0.3.0` | 把对外接口补齐：统一绘制入口、引擎查询、`DObject` 补全 | [2026-09-13](docs/docs/blog/posts/2026-09-13.md) |
+| `0.2.0` | 可插拔绘制引擎层 + 进程内栅格引擎 + 规格缓存 | [2026-09-12](docs/docs/blog/posts/2026-09-12.md) |
+| `0.1.0` | 完善功能 | [2025-06-26](docs/docs/blog/posts/2025-06-26.md) |
+| 更早 | `0.0.1` – `0.0.9` 的起步阶段 | [回顾](docs/docs/blog/posts/2024-01-26.md) |

tkdeft-0.3.0/pyproject.toml

@@ -0,0 +1,33 @@
+[tool.poetry]
+name = "tkdeft"
+version = "0.3.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.3.0/tkdeft/__init__.py

@@ -0,0 +1,150 @@
+"""tkdeft —— 把矢量绘图变成 Tkinter 控件的底座。
+
+本包不提供具体组件，只提供零件：
+
+* :mod:`tkdeft.engines` —— 可插拔的绘制引擎（tksvg / wand / skia / pillow / cairo）
+* :mod:`tkdeft.svg` —— SVG 形状助手（统一的圆角矩形几何）
+* :mod:`tkdeft.windows` —— ``DCanvas`` / ``DDraw`` / ``DSvgDraw`` / ``DDrawWidget``
+* :mod:`tkdeft.object` —— ``DObject`` 配置容器
+* :mod:`tkdeft.utility` —— 字体等零碎工具
+
+最常用的东西都从顶层再导出一份，所以下面两种写法等价::
+
+    from tkdeft.engines import RoundRectSpec, set_engine, render_roundrect
+    from tkdeft import RoundRectSpec, set_engine, render_roundrect
+
+快速上手
+--------
+::
+
+    import tkinter
+    from tkdeft import DCanvas, RoundRectSpec, set_engine
+
+    set_engine("skia")                     # 换成进程内栅格引擎（可选）
+
+    root = tkinter.Tk()
+    canvas = DCanvas(root, width=200, height=100)
+    canvas.pack()
+    canvas.draw_roundrect(0, 0, 120, 32, 6, fill="#ffffff", outline="#000000")
+    root.mainloop()
+
+想直接要一张图片（不起窗口）::
+
+    photo = render_roundrect(
+        RoundRectSpec(width=120, height=32, rx=6, fill="#ffffff"),
+        master=canvas,
+    )
+
+能力探测
+--------
+旧版本没有 :mod:`tkdeft.engines` 子包，因此依赖方用 :data:`HAS_ENGINES`
+做能力探测，比解析版本号更直接::
+
+    import tkdeft
+
+    if getattr(tkdeft, "HAS_ENGINES", False):
+        from tkdeft.engines import set_engine
+"""
+
+from . import engines, svg, utility, windows
+from .engines import (
+    DEFAULT_ENGINE_NAME,
+    RENDERER_INDEX,
+    DrawEngine,
+    RoundRectSpec,
+    SvgEngine,
+    ThumbSpec,
+    TrackSpec,
+    UnknownEngineError,
+    available_engines,
+    cache_stats,
+    clear_cache,
+    describe_engines,
+    get_cache,
+    get_engine,
+    get_engine_name,
+    list_engines,
+    register_engine,
+    render,
+    render_roundrect,
+    render_thumb,
+    render_track,
+    reset_engine,
+    set_cache_budget,
+    set_engine,
+)
+from .object import DObject
+from .svg import add_roundrect, roundrect_geometry
+from .utility import SEGOE_FONT_FILE, SegoeFont, segoe_font, segue_font_file
+from .windows import (
+    DCanvas,
+    DDraw,
+    DDrawWidget,
+    DDrawWidgetCanvas,
+    DDrawWidgetDraw,
+    DSvgDraw,
+)
+
+#: 版本号。tkfluent 会据此判断环境里的 tkdeft 是否够新。
+#: 注意：需要与 pyproject.toml 里的 version 保持一致。
+__version__ = "0.3.0"
+
+#: :data:`__version__` 的数字形式，便于比较：``(0, 3, 0)``
+__version_info__ = tuple(int(part) for part in __version__.split(".") if part.isdigit())
+
+#: 是否提供绘制引擎层（tkfluent >= 0.2.0 依赖它）。
+#: 旧版本没有这个子包，用它做能力探测比解析版本号更直接。
+HAS_ENGINES = True
+
+__all__ = [
+    # 子包
+    "engines",
+    "svg",
+    "utility",
+    "windows",
+    # 版本与能力探测
+    "__version__",
+    "__version_info__",
+    "HAS_ENGINES",
+    # 基础
+    "DObject",
+    # 画布与绘制后端
+    "DCanvas",
+    "DDraw",
+    "DSvgDraw",
+    "DDrawWidget",
+    "DDrawWidgetCanvas",
+    "DDrawWidgetDraw",
+    "add_roundrect",
+    "roundrect_geometry",
+    # 字体
+    "SegoeFont",
+    "segue_font_file",
+    "SEGOE_FONT_FILE",
+    "segoe_font",
+    # 绘制引擎
+    "DrawEngine",
+    "SvgEngine",
+    "RoundRectSpec",
+    "TrackSpec",
+    "ThumbSpec",
+    "UnknownEngineError",
+    "RENDERER_INDEX",
+    "DEFAULT_ENGINE_NAME",
+    "register_engine",
+    "get_engine",
+    "get_engine_name",
+    "set_engine",
+    "reset_engine",
+    "list_engines",
+    "available_engines",
+    "describe_engines",
+    "render",
+    "render_roundrect",
+    "render_track",
+    "render_thumb",
+    "get_cache",
+    "clear_cache",
+    "cache_stats",
+    "set_cache_budget",
+]