kk_codeimg
🌟【Python卡皮巴拉】—— 你的Python修炼秘籍,代码界的"神兽"驾到!🌟
🌟 [Python Capybara] — Your Python cultivation manual; the coding realm's "mythical beast" has arrived! 🌟
PyPI · MIT License · Python 3.8+
安装
pip install kk_codeimg
快速开始
from kk_codeimg import code_generator
code_generator(code, 'python', output='out.png')
不传 output 时返回 PIL.Image.Image,可自行 .save() 或做后处理。
特点
- 12 套主题 —— 全部通过 WCAG AA 对比度校验,不是"看着差不多"
- 16 种预设风格 —— 一行代码切换整套视觉配置
- 窗口标题 —— 显示文件名,支持中文,字体与代码自动统一
- 中英文混排 —— 等宽字体没有中文字形?自动回退到系统 CJK 字体
- 对比度达标 —— 按 WCAG 标准实算,注释不再"灰到看不见"
- 纯离线 —— 不联网、不开浏览器,CI 里也能跑
- 零重型依赖 —— 只用
Pillow+Pygments - 主题可扩展 —— 加一套主题只需往
palette.py里加一组色值
效果预览
生成全套样图:
python scripts/make_samples.py # 在仓库根目录执行
输出到 out/。
预设风格
不想逐个记参数就用 style,一次套用一整套视觉配置:
code_generator(code, 'python', style='tokyo', output='out.png')
| 风格 | 说明 |
|---|---|
default |
深色经典:One Dark 主题 + 柔和渐变 |
carbon |
极简纯色底、无窗口控制点、方正小圆角 |
dracula |
Dracula 紫调 + 极光渐变 |
tokyo |
Tokyo Night 夜色 + 深海渐变 |
github |
GitHub 浅色 + 淡雅渐变(不透明底,可读性最佳) |
light-frosted |
浅色磨砂:保留渐变氛围但垫白底,深字清晰 |
frosted |
深色磨砂玻璃:大圆角,背景隐约透出 |
minimal |
极简:无行号、无控制点、大留白 |
neon |
霓虹酷炫:Cool Glow + 大圆角 |
share |
社交分享:大字号、大圆角、宽留白 |
print |
打印友好:白底黑字、无干扰 |
ocean |
深海蓝:冷色调、克制圆角 |
sunset |
日落暖橙:亮色系、适合长代码 |
forest |
森林绿:护眼低饱和 |
grid |
网格纸:零圆角、细边框控制点、代码排版感 |
sticker |
贴纸风:浅色、夸张圆角、紧凑 |
还有一批顺手加的别名,记不住名字也能用:
dark / light / plain / classic / night / big / rounded / sharp / matrix / frost
code_generator(code, 'python', style='dark') # 等同 default
code_generator(code, 'python', style='plain') # 等同 minimal
显式传入的参数优先级高于 style:
# style 提供预设,再用 theme 覆盖其中一项
code_generator(code, 'python', style='minimal', theme='dracula')
常用参数
| 参数 | 默认 | 说明 |
|---|---|---|
code |
必填 | 代码文本 |
language |
'python' |
Pygments 语言名:python / javascript / sql / java / go… |
output |
None |
PNG 路径;None 则只返回 Image |
style |
None |
预设风格名,见上表 |
theme |
随 style | 12 套主题,见下表 |
background |
随 style | 渐变名 / single / transparent / 任意 #hex |
font |
None |
字体名或 .ttf 路径;None 自动探测 |
font_size |
15 |
字号(逻辑像素) |
border_radius |
9 |
编辑器圆角 |
window_controls |
'color' |
color / gray / gray-light / outline / none |
line_height |
1.45 |
行高倍数 |
padding |
64 |
图片四周留白 |
line_numbers |
True |
是否显示行号 |
transparent_editor |
False |
编辑器区域透明 |
scrim_alpha |
None |
透明模式下的底色不透明度 0~1;None 时按主题明暗自动决定 |
title |
None |
窗口标题,显示在窗口栏居中,支持中文 |
title_alpha |
0.72 |
标题不透明度,调低可让标题退居次要 |
title_size |
None |
标题字号。None/'same' = 与代码同字号;传数字则单独指定 |
scale |
2 |
渲染倍率,2 适合高清分享 |
传了 output 时返回 RenderResult,带 .image、.path、.editor_box、.code_box。
窗口标题
title 显示在窗口栏居中位置:
code_generator(code, 'python', title='point.py', output='out.png')
code_generator(code, 'python', title='几何工具 · 坐标计算', output='out.png') # 支持中文
字体始终与代码一致,只有字号可以不同:
# 标题与代码同字号同字体(默认)
code_generator(code, 'python', title='main.py')
# 标题小一号
code_generator(code, 'python', title='main.py', font_size=20, title_size=13)
# 换个字体,标题自动跟随
code_generator(code, 'python', title='main.py', font='consolas')
细节:
- 字体统一是硬约束——代码用什么字体,标题就用同一个字体文件 (同字号时直接复用同一个字体对象);中文回退字体同样统一
title_size超过窗口栏容量(40px 栏高,约 48.6px 上限)会自动钳制, 不会出现标题盖住代码的情况;0/ 负数 / 非数字会抛ValueError- 超长标题自动截断加省略号,不溢出窗口
window_controls='none'时标题仍然显示(标题独立于控制点)- 配色用主题前景色而非行号色——实测行号色在部分主题上对比度仅 2.76:1, 前景色全部 ≥ 6.10:1
- 标题在整个编辑器宽度上居中
主题(12 套)
one-dark(默认)、dracula、vscode、ayu-light、github-light、
github-dark、tokyo-night、xcode-dark、xcode-light、amy、aura、cool-glow
code_generator(code, 'python', output='a.png', theme='dracula', background='aurora')
背景
10 套渐变:mystic(默认)、aruba、jungle、tropical、aurora、candy、
peach、bananas、leaf、ocean
外加 single(单色)、transparent(透明)、以及任意 #hex 值:
code_generator(code, 'python', output='a.png', background='#1d976c')
完整示例
from kk_codeimg import code_generator
code = '''def greet(name: str) -> str:
# 生成问候语
return f"Hello, {name}!"
'''
# 默认风格
code_generator(code, 'python', output='out.png')
# 换主题与背景
code_generator(code, 'python', output='dracula.png',
theme='dracula', background='ocean')
# 带窗口标题
code_generator(code, 'python', output='titled.png', title='greet.py')
# 浅色主题 + 无行号
code_generator(code, 'python', output='light.png',
theme='github-light', background='leaf', line_numbers=False)
# 不落盘,直接拿 Image 做后处理
img = code_generator(code, 'python', font_size=18)
设计说明
对比度是算出来的,不是看出来的。 早期直接采用现成配色,实测发现一批槽位 达不到 WCAG AA 标准(4.5:1),实际观感问题例如:
- 某浅色主题的
number仅 1.85:1 —— 白底上几乎看不见 - 某深色主题的
comment仅 2.25:1 —— 注释难以辨认
修正方式是保持色相与饱和度、只调整明度,直到达到 4.5:1,观感不跑偏。
现 12 套主题全部达标(最差 4.50:1,最好 6.74:1)。kk_codeimg/contrast.py
提供 WCAG 计算与评估工具,test_all_themes_meet_wcag_aa_on_own_bg 做回归守卫。
原主题未定义的槽位(如 Xcode 系列的数字/运算符)按其编辑器默认配色补齐,
并配 _FALLBACK 语义回退链,避免整片 token 退化成前景色。
透明模式下的可读性:浅色主题(深色文字)若抽掉底色直接压到饱和背景上,
文字会糊掉——实测某组合仅 1.24:1。因此透明模式下浅色主题会自动垫一层
不透明底色(磨砂效果,背景氛围仍在)。深色主题文字本身够亮,保持全透明。
手动控制用 scrim_alpha(0~1)。
中英文混排:等宽字体普遍无中文字形,_TextPen 会按字符切分,
CJK 交给系统 CJK 字体(微软雅黑 / Noto Sans SC 等)绘制并按全角宽度计算 advance。
字体:默认按 Cascadia Mono(SIL OFL 1.1)→ JetBrains Mono(OFL 1.1)→
DejaVu Sans Mono(Bitstream Vera)顺序探测,均为免费商用字体。
圆角:编辑器圆角通过 alpha 遮罩真实生效(不是只改描边),可用
border_radius 自由调整,0 即直角。
测试
python -m pytest scripts/test_kk_codeimg.py -q
47 项测试,覆盖缩进保留、中文出字、12 主题 / 12 背景 / 16 风格 / 10 别名渲染、 WCAG 对比度守卫、透明模式垫底、圆角生效、槽位退化防护、参数覆盖优先级、 窗口标题(中文/截断/无控制点/透明度/字号独立/字体统一/居中)、多语言、异常输入等。
已知限制
- 超长单行不自动换行(长代码建议调大
font_size或分屏) - 粗体/斜体未实现,部分主题原设计里关键字是加粗的
- 透明模式 + 浅色主题时,背景渐变基本透不出来(实测需 100% 不透明才达 AA),
想要通透感建议用深色主题配
style='frosted'
许可证
MIT © 2026 Python卡皮巴拉
Metadata
Release files for kk-codeimg 0.0.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| kk_codeimg-0.0.1.tar.gz | 34.3 kB | Without provenance | Details for kk_codeimg-0.0.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| kk_codeimg-0.0.1-py3-none-any.whl | Python 3 | none | any | Details for kk_codeimg-0.0.1-py3-none-any.whl |
Total release size: 63.0 kB
Release files / kk_codeimg-0.0.1.tar.gz
| Download URL | kk_codeimg-0.0.1.tar.gz |
|---|---|
| Size | 34.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a918e8b30c850a2b0ef8c1221922ed843622e528bc353a02243d3810fe68bb13
|
|
BLAKE2b-256 checksum How to use checksums |
c616c64e988a4d33a2c76a989424dfb8ed0e640a6737f9e1d4cad1dc1bf46647
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Release files / kk_codeimg-0.0.1-py3-none-any.whl
| Download URL | kk_codeimg-0.0.1-py3-none-any.whl |
|---|---|
| Size | 28.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cf5530a45653525b8f34c8d8f87bf21781c8105e746f957dffff1a6f1a1c3b92
|
|
BLAKE2b-256 checksum How to use checksums |
cb17bb5813d991a0bcf17556e6879392a3d5ba3b6b8082fb3492981c129fa2f5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Security for kk-codeimg 0.0.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.