CQL 教程/中文适配子包/图像与数据

图像与数据

掌握 CQPillow 图片处理、CQCrypto 加密哈希、CQData 数据校验与 CQOffice 文档处理四个子包的用法。

25.1CQPillow 图片处理

CQPillow 基于 Pillow 的中文适配,覆盖图片读写、几何变换、滤镜与绘制,可完成验证码生成、缩略图、水印等常见需求。

cql
从 cqpillow 导入 打开, 新建, 尺寸, 红色, 蓝色, 白色, 加载字体

# 新建一张 400x300 的白色画板并绘制
画板 = 新建("RGB", 尺寸(400, 300), 白色)
画布 = 画板.绘制()
画布.画矩形((20, 20, 120, 120), 填充=红色, 轮廓=蓝色, 宽度=3)
画布.画圆((250, 120), 60, 填充=蓝色)
字体 = 加载字体("C:/Windows/Fonts/msyh.ttc", 24)   # 微软雅黑
画布.写字((200, 200), "你好", 填充=红色, 字体=字体)
画板.保存("画板.png")

# 处理已有图片
图片 = 打开("照片.jpg")
图片.缩放(200, 200)               # 缩放
图片.裁剪(100, 50, 400, 300)      # 裁剪
图片.旋转(45)                     # 旋转
图片.转换模式("L")                # 转灰度
图片.模糊()                       # 高斯模糊
图片.轮廓()                       # 轮廓
图片.创建缩略图(150, 150)

模块级函数

打开(路径)新建(模式, 尺寸, 颜色)尺寸(宽, 高)加载字体(路径, 大小)默认字体(大小)

图片对象方法

中文 API说明
保存(路径, 格式=None, 质量=95) / 保存到字节(格式="PNG")保存,格式由扩展名推断
获取尺寸() / 宽度 / 高度 / 模式 / 格式基本信息
获取像素(位置)读取某点颜色
裁剪(左, 上, 右, 下) / 缩放(宽, 高=None, 保持比例=假) / 旋转(角度, 扩展=假, 填充色=None)几何变换,返回新图片
水平翻转() / 垂直翻转() / 旋转90()翻转
转换模式(模式) / 粘贴(图片, 位置)模式转换与合成
模糊() / 锐化() / 轮廓() / 边缘增强() / 浮雕()滤镜
亮度增强(系数) / 对比度增强 / 色彩增强 / 锐度增强增强
绘制()获取画布(就地绘制)
创建缩略图(宽, 高) / 复制()缩略图与复制

画布对象

画线画点画矩形画圆画椭圆画多边形写字写文本居中,公共参数 填充(内部颜色)/ 轮廓 / 宽度

颜色常量

白色、黑色、红色、绿色、蓝色、黄色、青色、洋红、橙色、紫色、灰色、银灰、深红、深绿、深蓝,另有模式常量 RGB、RGBA、灰度、位图、调色板、CMYK、YCbCr、HSV

注意:缩放 默认不保持比例,需要保持比例时传 保持比例=真 或只传宽度;绘制方法直接修改原图,如需保留原图先 复制();中文字体需指定支持中文的字体文件(Windows 常用 msyh.ttc 微软雅黑)。

25.2CQCrypto 加密与哈希

CQCrypto 基于 cryptography,提供 AES-GCM 对称加密、RSA 非对称加密与多种哈希算法,用于数据保密、完整性校验与签名。

cql
从 cqcrypto 导入 生成密钥, 对称加密, 对称解密, 哈希十六进制
从 cqcrypto 导入 生成RSA密钥对, 公钥加密, 私钥解密, 私钥签名, 公钥验证, 私钥转PEM

# 对称加密 AES-GCM
密钥 = 生成密钥(32)
密文 = 对称加密(密钥, "秘密消息")
明文 = 对称解密(密钥, 密文)          # b"秘密消息"

# 哈希
摘要 = 哈希十六进制("待签名数据")      # 64 位十六进制(sha256)

# RSA 非对称
私钥, 公钥 = 生成RSA密钥对(2048)
密文 = 公钥加密(公钥, "机密")
明文 = 私钥解密(私钥, 密文)
签名 = 私钥签名(私钥, "数据")
print(公钥验证(公钥, "数据", 签名))   # 真

# 密钥持久化
PEM = 私钥转PEM(私钥)

API 一览

中文 API说明
生成密钥(大小=32) / 随机字节(数量)生成安全随机字节
对称加密(密钥, 明文, 附加数据=None)AES-GCM 加密,返回 nonce+密文
对称解密(密钥, 数据, 附加数据=None)解密;密钥错误或篡改时抛异常
哈希(数据, 算法="sha256") / 哈希十六进制(数据, 算法)二进制摘要 / 十六进制摘要
计算文件哈希(路径, 算法)大文件分块哈希
生成RSA密钥对(大小=2048)返回 (私钥, 公钥)
公钥加密 / 私钥解密OAEP + SHA-256
私钥签名 / 公钥验证PSS + SHA-256
私钥转PEM / 公钥转PEM / 加载私钥 / 加载公钥密钥序列化与加载
编码 / 解码 / 转十六进制 / 从十六进制编码辅助

算法常量

SHA256、SHA1、SHA512、MD5、SHA3_256、SHA3_512

注意:对称加密的 附加数据 参与认证但不加密,加解密必须一致;RSA 加密仅适合小数据(密钥容量限制),大数据请用对称加密、RSA 加密密钥;密钥务必妥善保管,丢失即无法解密。

25.3CQData 数据校验

CQData 基于 Pydantic v2,通过声明式数据模型实现自动校验与类型转换,例如字符串 "25" 自动转为整数 25

cql
从 cqdata 导入 模型, 字段, 文本, 整数, 校验错误, 验证

类 用户(模型):
    姓名: 文本 = 字段(描述="用户姓名", 最小长度=1, 最大长度=20)
    年龄: 整数 = 字段(描述="年龄", 最小=0, 最大=150)

用户1 = 用户(姓名="小明", 年龄="25")    # "25" 字符串自动转为 25
print(用户1.转字典())                    # {'姓名': '小明', '年龄': 25}
print(用户1.转JSON())                    # JSON 字符串
用户2 = 用户1.复制(年龄=30)              # 复制并改字段

尝试:
    用户(姓名="", 年龄=200)              # 校验失败
捕获 校验错误 作为 e:
    print(e.中文信息())                  # 中文错误说明

# 函数式校验
用户3 = 验证(用户, 姓名="小红", 年龄=18)

API 一览

中文 API说明
模型中文模型基类,校验失败自动转中文 校验错误
字段(默认=None, 必填=假, 描述=..., 标题=..., 别名=..., 最小=..., 最大=..., 最小长度=..., 最大长度=..., 模式=..., 示例=...)字段声明
校验错误中文错误,含 中文信息() / 错误列表()
验证(模型类型, **数据)函数式校验
模型.转字典(排除空, 排除未设置) / 转JSON()序列化输出
模型.复制(**变更) / 获取(字段名)复制修改与取值

类型别名

文本、整数、浮点数、布尔、列表、字典、集合、元组、字节、任意、日期、日期时间、时间

注意:必填字段写法为 字段(必填=真),不要给默认值;底层依赖 Pydantic v2,旧版 Pydantic v1 的 API 不兼容。

25.4CQOffice 文档处理

CQOffice 基于 python-docx(Word)与 openpyxl(Excel),用中文 API 生成并修改办公文档。

Word 文档

cql
从 cqoffice 导入 新建文档, 居中, 红色

文档 = 新建文档()
文档.添加标题("会议纪要", 1)
段落 = 文档.添加段落("今天讨论了项目进度。", 对齐=居中)
段落.添加文本("尽快上线", 加粗=真, 颜色=红色, 大小=14)

表格 = 文档.添加表格(3, 2)
表格.设置单元格文本(0, 0, "事项")
表格.设置单元格文本(0, 1, "负责人")
表格.设置单元格文本(1, 0, "联调")
文档.保存("纪要.docx")
中文 API说明
新建文档() / 打开文档(路径)创建 / 打开 .docx
文档.添加标题(文本, 级别)标题(1~9 级)
文档.添加段落(文本, 对齐) / 段落们()段落
段落.添加文本(文本, 加粗, 斜体, 颜色, 大小, 字体名)追加带格式文本
段落.设置对齐(对齐) / 段落.设置样式(样式)段落格式
添加表格(行数, 列数, 样式) / 添加图片(路径, 宽, 高) / 添加分页()表格 / 图片 / 分页
表格.设置单元格文本(行, 列, 文本) / 表格.单元格(行, 列)表格读写
对齐常量 / 颜色左对齐、居中、右对齐、两端对齐红色、绿色、蓝色

Excel 工作簿

cql
从 cqoffice 导入 新建工作簿

工作簿 = 新建工作簿()
表 = 工作簿.获取活动表()
表.设置单元格(1, 1, "姓名")
表.设置单元格(1, 2, "年龄")
表.设置单元格名称("A2", "小明")
表.设置单元格名称("B2", 18)
表.设置列宽("A", 20)
print(表.全部数据())
工作簿.保存("名单.xlsx")
工作簿.关闭()
中文 API说明
新建工作簿() / 打开工作簿(路径)创建 / 打开 .xlsx
获取活动表() / 获取表(名称) / 新建表(名称) / 表名列表()工作表管理
设置单元格(行, 列, 值) / 获取单元格(行, 列)按行列读写(从 1 开始)
设置单元格名称("A1", 值) / 获取单元格名称("A1")按名称读写
设置标题(名称) / 设置列宽("A", 宽) / 设置行高(行, 高)格式设置
全部数据() / 清空()数据遍历与清空
工作簿.保存(路径) / 工作簿.关闭()保存与关闭
注意:Word 中文字体需通过 字体名 参数指定(如 "微软雅黑");Excel 行列从 1 开始计数;保存 后记得 关闭() 释放文件。