tkdeft 0.2.0__tar.gz → 0.3.0__tar.gz

{tkdeft-0.2.0 → tkdeft-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tkdeft
-Version: 0.2.0
+Version: 0.3.0
 Summary: 使用tkinter+tksvg开发的现代化界面库
 Author: XiangQinxi
 Author-email: xiangqinxi@outlook.com
@@ -38,47 +38,95 @@ Description-Content-Type: text/markdown
 
 意为`灵巧`，灵活轻巧好用
 
-继`tkadw`之后的`tkinter`的现代化界面库
+一句话：**把矢量绘图变成 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) |
 
 ## 原理
-先使用`svgwrite`进行矢量作图（默认会将其存储到临时文件夹中），再用`tksvg`打开图片，将图片利用`Canvas`或`Label`显示出来
-[index.md](docs/docs/index.md)
-> 这其中还是有些坑的，比如图片不显示等，导致我以前想做，却放弃了，现在知道错误所在了
+
+一句话：**先用矢量绘图生成图片，再交给 `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` 现在把"**画什么**"和"**用什么画**"分开了。组件只需要描述一个
+
+`tkdeft` 把"**画什么**"和"**用什么画**"分开了。组件只需要描述一个
 `RoundRectSpec`（尺寸、圆角、填充、描边……），具体由哪个引擎栅格化是可切换的。
 
+同一份规格交给 5 个引擎：
+
+![engine compare](docs/docs/assets/engines-compare.png)
+
 ```python
-from tkdeft.engines import set_engine, list_engines, cache_stats
+from tkdeft.engines import set_engine, list_engines, describe_engines, cache_stats
 
-print(list_engines())      # {'tksvg': True, 'wand': True, 'skia': True, 'pillow': True, 'cairo': True}
+print(list_engines())      # {'tksvg': True, 'wand': True, 'skia': 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]` |
+| 编号 | 引擎 | 类型 | 说明 | 额外依赖 |
+| --- | --- | --- | --- | --- |
+| 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** |
@@ -87,9 +135,11 @@ print(cache_stats())       # 缓存命中率，便于诊断
 | 按钮 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`
+复现：`python benchmarks/run_all.py`（9 项回归 + 性能基准，详见
+[回归与性能](docs/docs/usage/benchmarks.md)）
 
 ## 已修复的缺陷
+
 这一轮审查中定位并修掉的真实问题（都不是"风格问题"）：
 
 | 问题 | 影响 |
@@ -100,51 +150,32 @@ print(cache_stats())       # 缓存命中率，便于诊断
 | `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)` + 整宽整高 | 描边中心线压在画布边界上，**下边框和右边框被完全裁掉** |
+| 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`能实现很多漂亮的组件，而我套的模板可能不对其它设计其太大的作用
 
-所以我将这个设计库放在这里当做模板，供其它设计者参考使用。
+因为`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`版本：
+版本变更统一记录在文档站的[更新日志](https://tkdeft.netlify.app/blog/)里
+（源文件在 `docs/docs/blog/posts/`），按时间倒序排列：
 
-* 新增 `tkdeft.engines` 绘制引擎层，可插拔切换 `tksvg` / `wand` / `skia` / `pillow` / `cairo`
-* 新增进程内栅格引擎（skia-python / Pillow / pycairo），完全不落盘
-* 新增按规格缓存的图片缓存，参数相同的绘制结果直接复用
-* 新增 SVG 形状助手 `tkdeft.svg`，统一并修正圆角矩形几何
-* 修复临时文件 / fd 泄漏、`PhotoImage` 被 GC 导致画面空白、
-  `RenderManager` 的 `winfo_zorder` 崩溃等问题
-* 详细缺陷清单与性能数据见 [benchmarks/](benchmarks/)
+| 版本 | 一句话 | 发布说明 |
+| --- | --- | --- |
+| `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.2.0 → tkdeft-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "tkdeft"
-version = "0.2.0"
+version = "0.3.0"
 description = "使用tkinter+tksvg开发的现代化界面库"
 authors = ["XiangQinxi <xiangqinxi@outlook.com>"]
 readme = "README.md"

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",
+]