lantool 0.1.0__tar.gz

lantool-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Python 构建产物
+__pycache__/
+*.py[cod]
+*$py.class
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# 虚拟环境
+.venv/
+venv/
+env/
+
+# 测试与覆盖率
+.pytest_cache/
+.coverage
+coverage.xml
+htmlcov/
+
+# Lint 缓存
+.ruff_cache/
+.mypy_cache/
+
+# 日志文件
+logs/
+*.log
+
+# IDE
+.idea/
+.vscode/
+*.swp
+
+# 操作系统
+.DS_Store
+Thumbs.db
+
+# Claude 本地配置
+.claude/

lantool-0.1.0/CHANGELOG.md

@@ -0,0 +1,147 @@
+# Changelog
+
+本文件记录 lantool 的所有重要变更。格式基于 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，
+版本遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
+
+## [Unreleased]
+
+### Security
+
+- `curl` 生成命令中 URL/method/timeout 未转义的 shell 注入面（现全参数 POSIX 单引号转义，
+  method 白名单校验、timeout 类型校验、json/data 互斥）
+
+### Fixed
+
+- `python -m lantool` 在管道/重定向场景下按系统区域编码（如中文 Windows 的 GBK）写出，
+  UTF-8 终端与文件中出现中文乱码；现仅对非交互流统一为 UTF-8（交互终端保持原编码，
+  作为库函数调用 `main()` 时不对进程标准流做任何改动）
+
+- `dir(lantool)` 保留 `__file__`/`__path__` 等标准模块属性，同时提供全部懒加载导出名
+- `ascii_table` 的 NUL 字符改用可见 `\x00` 表示，与其他不可打印字符保持一致
+- `hash_file` 对 `chunk_size < 1` 静默产出空数据哈希，现显式抛 `ValidationError`
+- `compact_xml` 丢弃混合内容文本（词间空格及纯内联元素间换行等可见文本被压缩掉）；
+  现仅删除可识别的缩进空白与叶节点首尾空白，无法确定用途的混合内容空白原样保留；
+  深层格式化/压缩的递归异常统一为 `ParseError`
+- Cron 星期域区间含 7（`0-7`/`5-7` 等）违反 crontab(5) 语义的解析错误；拒绝空步长，
+  闰日可跨越多年寻找下次运行时间，无法匹配时的错误说明改为 datetime 可表示范围
+- 校验器锚定接受尾随换行（`is_email`/`is_phone_cn`）、非 str 输入静默通过或泄漏裸异常
+  （`is_ipv4`/`is_ipv6`/`is_url`/`is_id_card_cn`，畸形 IPv6 URL 现返回 False）；
+  URL 拒绝原始控制空白与非法端口，手机号/身份证仅接受 ASCII 数字
+- `to_timestamp`/`str_to_timestamp` 负时间戳向零截断（应向下取整）；平台时间转换异常统一为
+  `ParseError`；`human_duration` 非法输入泄漏裸 `ValueError`
+- `to_bool` 对 float 与 int 不对称；`to_bool(NaN/inf)` 静默转 True（现返回 default）；
+  `to_datetime` 不支持含毫秒/时区的 ISO 8601 字符串；超大整数在 `to_float`/`to_datetime`
+  中不再绕过失败回退约定
+- `get_env` 的默认值现在与环境值一样经过类型转换，转换失败（含数值溢出）统一抛
+  `ValidationError`，不再返回未经转换的对象
+- `retry` 正抖动可能突破 `max_delay`；`rate_limit` 时间戳读取移入窗口锁内，避免并发入队
+  乱序导致错误限流
+- `curl(params=...)` 在 URL 含 fragment 时把查询参数拼到 `#` 后，现仅更新 query 部分
+- `convert_base` 静默接受下划线分隔与全角数字（`int()` 解析怪癖泄漏）
+- `timing`/`suppress_errors` 未适配 async 函数（计时错误/异常抑制静默失效）
+- YAML 解析错误（`YAMLError`）、条形码数据非法、JWT 签发/校验参数错误、
+  DES/3DES 短密文、RSA 非 UTF-8 明文等泄漏原生异常，统一纳入 `LanToolError` 体系
+- 日志滚动：归档目录存在杂散文件时 `doRollover` 崩溃丢日志；跨午夜归档改按内容所属日命名；
+  严格识别完整归档文件名，过期与同天限额清理不再删除同前缀手工备份或受其序号干扰
+- 图片水印定位未补偿 textbbox 偏移（贴边）；原地压缩（dst == src）统计失真；
+  截断图片的延迟解码错误统一为 `ValidationError`，非方形源图生成完整方形 ICO 档位，
+  透明图片转 JPEG 先按白底合成，数值参数统一校验
+- PDF 文字水印不再以不透明白图遮挡原页面，按每页尺寸生成透明水印；页树延迟解析、
+  零页文档、页码与字号等非法输入统一纳入 `ValidationError`
+- 二维码超容量、条形码 SVG 非法 XML 控制字符及 PNG 缺少 Pillow 时的原生异常，
+  现转为明确的校验或可选依赖异常
+- `format_number`/`format_currency` 的十进制字符串与 `format_percent` 的大整数不再经
+  float 或受限 Decimal context 丢精度；`convert_size` 避免中间乘法把有限结果溢出为 inf；
+  `human_size` 小数科学计数法往返断裂
+- JSON 拒绝 RFC 非法的 `NaN`/`Infinity`（显式 `allow_nan=True` 也不能重新启用），
+  深层输入的递归异常统一为解析/校验错误；`validate` 在超出解析深度时返回 False
+- `java_fields` 拒绝 Java 关键字、字面量与单下划线；`natural_sort` 不再对上标数字泄漏
+  `ValueError`；`count_chars` 统一 CR/LF 换行语义；diff 行列表不再注入伪空行
+- BMI 极端有限数值的算术溢出/下溢统一为 `ValidationError`
+- `hashing` 全入口标注 `usedforsecurity=False`（FIPS 环境下 md5/sha1 非安全用途可用）
+- 原子写在 POSIX 下覆盖文件后权限收窄为 0600；异常清理始终独占 fd 所有权并统一关闭，
+  避免误关其他线程已复用的文件描述符
+- `format_number`/`format_currency`/`format_percent` 对 NaN/Infinity（含 Decimal 实例与
+  数字字符串）静默输出伪结果，现统一抛 `ValidationError`
+- `get_env_float` 接受 `nan`/`inf` 等非有限值、`get_env_json` 接受 `NaN`/`Infinity`
+  非标准 JSON，现在分别回退默认值与按非法 JSON 处理
+- `get_logger("")` 返回并配置 root logger（违背库不触碰 root logger 的承诺），现抛
+  `ValidationError`；名称按 Windows 可移植文件名规则校验（路径分隔符、盘符相对路径、
+  NUL 等控制字符、保留设备名、首尾空白），避免写出 `log_dir` 或每次 emit 静默丢日志；
+  滚动参数补齐整数类型校验（浮点值会在滚动清理阶段触发被 logging 吞掉的 `TypeError`）
+- `cron_next_run` 在 `base=datetime.max` 等起点越界场景泄漏原生 `OverflowError`，
+  现统一为 `ParseError`
+- `compress_image`/水印函数改用 Pillow 扩展名注册表解析输出格式：未知扩展名与
+  只读格式（如 `.psd`/`.xpm`，不在 `Image.SAVE` 中）不再泄漏 `KeyError`/`ValueError`，
+  目标无扩展名时沿用源图格式，水印保存统一显式指定格式
+- `pdf_merge` 空文件列表静默生成 0 页 PDF，现抛 `ValidationError`；
+  `images_to_pdf` 中途读取失败时关闭已打开的帧，避免资源泄漏
+- `base64_decode_bytes` 非文本输入泄漏原生 `TypeError`，现统一为 `EncodeError`
+- `convert_size`/`human_size` 接受布尔值及 NaN/Infinity，现显式校验为 `ValidationError`
+- `natural_sort` 的数字段先规范化为 ASCII 数字串（支持全角/阿拉伯-印度等 Unicode 数字），
+  再按“长度 + 去前导零数字串”比较：既保持数值序，也不再触发 Python 的整数字符串转换
+  位数上限
+- `to_timestamp` 字符串入参未容忍首尾空白（与 `str_to_timestamp` 不一致）；现在先按 fmt
+  原样解析，失败后再去空白重试，保留 fmt 自带字面空白的用法
+- `curl(params=...)` 序列值未按重复键展开，现与常见 HTTP 客户端编码一致
+- `rsa_decrypt` 的 `UnicodeDecodeError` 分支被前置的 `ValueError` 吞掉，
+  现按子类优先捕获并给出准确的错误说明
+- `is_url` 接受未编码反斜杠（浏览器会将其归一为斜杠，存在主机混淆/校验绕过面），现拒绝
+- 日志文件名安全校验覆盖 Windows 盘符相对路径（如 `D:evil`）、控制字符与保留设备名，
+  避免绕过路径分隔符检查仍写出 `log_dir` 或在 emit 阶段静默失败
+- `bcrypt_hash` 的 `rounds`、`rsa_generate_keys` 的 `bits` 非整数时泄漏原生 `TypeError`，
+  现统一为 `ValidationError`
+- `human_size`/`convert_size` 对超出浮点可表示范围的整数泄漏原生 `OverflowError`，
+  现统一为 `ValidationError`
+- Cron 字段与步长接受 `int()` 的宽松写法（下划线、正号、全角数字等），
+  如 `1_0` 被静默解析为 10；现仅接受 ASCII 十进制数字，超长数字 token 统一为 `ParseError`
+- `format_number` 与 `jsonx.loads`/`validate` 在超长整数触发 Python 位数上限时
+  泄漏原生 `ValueError`，现分别统一为 `ValidationError` 与 `ParseError`；
+  `loads` 另拒绝 `1e400` 等超出 float 范围的指数值，不再解析为 `inf`
+- `parse_user_agent` 补充 iOS 平台的 CriOS/FxiOS/OPiOS 浏览器标识识别
+- `format_percent` 的有限浮点/超大指数 Decimal 输入乘以 100 后溢出（输出
+  "inf%"/"Infinity%"）或抛出原生 `decimal.Overflow`，现统一抛 `ValidationError`；
+  `convert_size` 的有限浮点换算结果溢出为 inf 时同样显式失败
+- `format_percent` 对经 Decimal 路径的超大数值（如 `1E+999995`，乘 100 未超 Decimal
+  范围）增加输出位数上限（4300 位，与 `sys.get_int_max_str_digits` 默认值对齐），
+  不再静默生成 KB~MB 级输出；`format_number` 的 `separator` 非字符串输入从原生
+  `TypeError` 收紧为 `ValidationError`（不分组请传空字符串）
+- `imagex`/`pdfx` 图片读取对 Pillow 的解压炸弹异常（`DecompressionBombError`）
+  统一转为 `ValidationError`
+- 日志名称校验补充孤立代理项与 UTF-8/UTF-16 长度上限：避免配置成功后每次 emit
+  因编码或文件系统长度限制静默丢日志
+- `imagex` 保存阶段把编码器不支持当前图像模式的原生 `ValueError` 统一为
+  `ValidationError`（如 RGBA 保存为 EPS）
+- Emoji“手势”与“自然”分类内的重复条目已去重（避免随机取值概率偏斜）
+
+### Added
+
+- PyPI 发布完整指南（docs/publish.md）：Trusted Publisher / twine / uv 三种方式、
+  TestPyPI 演练、发布后验证与常见问题排查
+
+### Changed
+
+- 入门示例改用 POST 请求体提交密码，Django 上传示例处理缺失文件，并澄清异常与随机源约定
+- `java_fields` 类型推断改按分词整词匹配（修正 message/image/paid/grid/validate 等误判；
+  全小写复合词如 `userid` 不再推断为 Long，建议使用驼峰或下划线命名）
+- `json_to_yaml` 智能类型转换与 `jsonx` 对称（datetime/set/Decimal/UUID/bytes 等含子类），
+  YAML 原生时间戳改输出 ISO 字符串
+- `compress_image` 的 `quality` 按文档收紧为 1~95（此前越界值静默透传 Pillow）
+- `mask` 校验 `mask_char` 须为单字符；`validate_xml` 非 str 输入返回 False
+- `retry`/`rate_limit`/`human_duration` 等参数校验显式化（非法类型与非有限数值抛统一异常）
+- README 时间 API 措辞修正（本地时间函数返回 naive datetime，aware 场景用 `now_utc`）
+- `convert_size`/`human_size` 数值入参类型标注改为 `int | float`；日志 handler 构建逻辑
+  按主/分类职责拆分，`get_logger` 保持单一入口
+- Ruff 规则集扩展 `C4`/`PERF`/`PIE`（现有代码零违规）
+- 修正文档中的 Emoji 数量描述（实际约 600 个）
+
+## [0.1.0] - 2026-11-07
+
+### Added
+
+- 零依赖核心（纯标准库）23 个模块：encoding/hashing/times/text/jsonx/xmlix/diffx/formatx/webdata/chardata/bytesize/ids/password/validator/convert/collx/retryx/cronx/misc/decorators/files/env/log
+- 可选依赖模块 7 个：security/jwtx/yamlix/imagex/qrcodex/barcodex/pdfx（按需 `pip install lantool[security]` 等启用）
+- PEP 562 懒加载统一导出（`from lantool import xxx` 一行调用）
+- `python -m lantool` 环境自检命令
+- 日志工厂：总/级别/分类多文件、按天 + 100MB 双条件滚动、gzip 压缩、366 天保留
+- PEP 561 类型标记（py.typed）、PEP 621 元数据、uv/pip 双兼容开发依赖

lantool-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LanTool Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

lantool-0.1.0/PKG-INFO

@@ -0,0 +1,252 @@
+Metadata-Version: 2.5
+Name: lantool
+Version: 0.1.0
+Summary: 轻量实用的 Python 通用工具库：零依赖核心 + 按需扩展（编解码/哈希/加解密/时间/文本/日志等）
+Project-URL: Homepage, https://gitee.com/lancelan6/lantool
+Project-URL: Repository, https://gitee.com/lancelan6/lantool
+Project-URL: Issues, https://gitee.com/lancelan6/lantool/issues
+Project-URL: Changelog, https://gitee.com/lancelan6/lantool/blob/master/CHANGELOG.md
+Author: LanTool Contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: common,crypto,encoding,hashing,jwt,toolkit,utility,utils
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Provides-Extra: all
+Requires-Dist: bcrypt>=4.2; extra == 'all'
+Requires-Dist: cryptography>=43.0; extra == 'all'
+Requires-Dist: pillow>=10.4; extra == 'all'
+Requires-Dist: pyjwt>=2.9; extra == 'all'
+Requires-Dist: pypdf>=4.3; extra == 'all'
+Requires-Dist: python-barcode>=0.15; extra == 'all'
+Requires-Dist: pyyaml>=6.0.2; extra == 'all'
+Requires-Dist: qrcode>=7.4; extra == 'all'
+Provides-Extra: barcode
+Requires-Dist: pillow>=10.4; extra == 'barcode'
+Requires-Dist: python-barcode>=0.15; extra == 'barcode'
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Provides-Extra: image
+Requires-Dist: pillow>=10.4; extra == 'image'
+Provides-Extra: jwt
+Requires-Dist: pyjwt>=2.9; extra == 'jwt'
+Provides-Extra: pdf
+Requires-Dist: pillow>=10.4; extra == 'pdf'
+Requires-Dist: pypdf>=4.3; extra == 'pdf'
+Provides-Extra: qr
+Requires-Dist: pillow>=10.4; extra == 'qr'
+Requires-Dist: qrcode>=7.4; extra == 'qr'
+Provides-Extra: security
+Requires-Dist: bcrypt>=4.2; extra == 'security'
+Requires-Dist: cryptography>=43.0; extra == 'security'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0.2; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# lantool
+
+[![PyPI](https://img.shields.io/pypi/v/lantool.svg)](https://pypi.org/project/lantool/)
+[![Python](https://img.shields.io/pypi/pyversions/lantool.svg)](https://pypi.org/project/lantool/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+轻量实用的 Python 通用工具库：**零依赖核心 + 按需扩展**。
+
+- **开箱即用**：`pip install lantool` 后 `from lantool import sha256, base64_encode` 一行调用，无需实例化、无需配置；
+- **零依赖核心**：约七成功能（编解码/哈希/时间/文本/JSON/日志/校验/Cron 等 23 个模块）纯标准库实现，完全离线可用；
+- **按需扩展**：加解密、JWT、图片、PDF 等通过 extras 按需安装，缺失时给出清晰的安装提示；
+- **源码即拷即用**：整包 `src/lantool` 拷入任意工程（FastAPI / Flask / Django / 脚本）同样直接 `import lantool` 使用；
+- **Python 3.11+**：时间 API 避开 3.12+ 废弃接口（如 `utcnow`），提供 timezone-aware 的 `now_utc`；PEP 561 类型标记，IDE 补全友好。
+
+## 安装
+
+```bash
+# pip
+pip install lantool                  # 零依赖核心
+pip install "lantool[security]"      # 加解密（AES/RSA/Bcrypt）
+pip install "lantool[all]"           # 全功能一键安装
+
+# uv
+uv pip install lantool
+uv add "lantool[all]"                # 在 uv 管理的项目中添加依赖
+```
+
+### 可选功能（extras）
+
+| extras | 功能 | 依赖 |
+| --- | --- | --- |
+| （无） | 核心 23 模块（纯标准库） | 无 |
+| `security` | AES/DES/3DES/RSA/Bcrypt | `cryptography`、`bcrypt` |
+| `jwt` | JWT 签发与校验 | `PyJWT` |
+| `yaml` | JSON/YAML 互转 | `PyYAML` |
+| `image` | 图片压缩/水印/favicon | `Pillow` |
+| `qr` | 二维码生成（PNG/SVG） | `qrcode`、`Pillow` |
+| `barcode` | 条形码生成 | `python-barcode`、`Pillow` |
+| `pdf` | PDF 拆分/合并/水印/图片转 PDF | `pypdf`、`Pillow` |
+| `all` | 以上全部 | — |
+
+未安装对应依赖时调用可选功能，会得到明确提示：
+
+```
+OptionalDependencyError: 缺少可选依赖 cryptography，请先安装: pip install "lantool[security]" 或 uv pip install "lantool[security]"
+```
+
+## 快速开始
+
+### 编解码与哈希
+
+```python
+from lantool import base64_encode, base64_decode, sha256, url_encode, convert_base
+
+base64_encode("你好 lantool")          # '5L2g5aW9IGxhbnRvb2w='
+base64_decode("5L2g5aW9IGxhbnRvb2w=")  # '你好 lantool'
+sha256("abc")                          # 'ba7816bf8f01cfea...'
+url_encode("a b/c")                    # 'a%20b%2Fc'
+convert_base("hello", 36, 10)          # '29234652'（支持 2~36 任意进制）
+```
+
+### 时间与时间戳
+
+```python
+from lantool import now_str, timestamp, from_timestamp, human_duration
+
+now_str()                     # '2026-11-07 15:30:00'（默认格式 YYYY-MM-DD HH:MM:SS）
+timestamp()                   # 1780000000（秒级）
+timestamp(seconds=False)      # 1780000000123（毫秒级）
+from_timestamp(1700000000)    # datetime（13 位毫秒自动识别）
+human_duration(90061)         # '1天1小时1分1秒'
+```
+
+### 文本与 JSON
+
+```python
+from lantool import to_snake, to_camel, java_fields, pretty, compact, dumps
+from datetime import datetime
+
+to_snake("HTTPServer")        # 'http_server'
+to_camel("user_login_count")  # 'userLoginCount'
+java_fields("id\nuserName\nprice\ncreateTime\nisVip")
+#     private Long id;
+#     private String userName;
+#     private BigDecimal price;
+#     private LocalDateTime createTime;
+#     private Boolean isVip;
+
+dumps({"at": datetime.now()})  # datetime 自动 ISO 序列化
+compact('{"a": 1}')            # '{"a":1}'
+pretty({"list": [1, 2]})       # 格式化缩进，中文原样输出
+```
+
+### 加解密与 JWT（需 extras）
+
+```python
+from lantool import aes_encrypt, aes_decrypt, jwt_encode, jwt_decode, bcrypt_hash, bcrypt_verify
+
+token = aes_encrypt("机密数据", "your-key")        # AES-256-GCM，默认推荐
+aes_decrypt(token, "your-key")                    # '机密数据'
+
+jwt = jwt_encode({"sub": "user-1"}, "32-byte-secret...!!", expires_in=3600)
+jwt_decode(jwt, "32-byte-secret...!!")            # {'sub': 'user-1', 'iat': ..., 'exp': ...}
+
+hashed = bcrypt_hash("my-password")               # 口令存储推荐
+bcrypt_verify("my-password", hashed)              # True
+```
+
+### 日志（总 + 级别 + 分类，双条件滚动）
+
+```python
+from lantool import get_logger
+
+log = get_logger("app")            # logs/app.log（总）+ app_error.log + app_warning.log
+access = get_logger("app.access")  # 分类：logs/app_access.log，同时汇入总日志与控制台
+
+log.info("服务启动")
+access.info("GET /api/users 200")
+log.error("数据库连接失败")
+```
+
+单文件超 100MB 或跨天自动滚动，旧日志 gzip 压缩，默认保留 366 天（全部可配置）。
+
+### 更多示例
+
+- **[从零开始完整指南](docs/getting-started.md)** —— 安装部署、自检、快速上手、FastAPI/Flask/Django 集成实战、日志部署、故障排查
+- **[使用指南](docs/usage.md)** —— 全部 API 说明与示例
+
+自检本机环境：
+
+```bash
+python -m lantool   # 输出版本、Python 环境与各 extras 可用性
+```
+
+## 功能矩阵
+
+| 领域 | 模块 | 主要能力 |
+| --- | --- | --- |
+| 编解码 | `encoding` | Base64 / URL / Hex / Unicode 中文互转 / 摩斯密码 / 2~36 进制 / 图片转 Base64 |
+| 哈希 | `hashing` | MD5 / SHA1 / SHA224-512 / HMAC / 文件哈希 / CRC32 |
+| 时间 | `times` | 时间戳（秒/毫秒互转）/ 多格式当前时间 / 人性化时长 |
+| 文本 | `text` | 驼峰互转 / 大小写 / 字数统计 / 自然排序 / 脱敏 / Java 字段生成 |
+| 数据格式 | `jsonx` `xmlix` `diffx` | JSON 智能序列化与格式化 / XML 格式化 / 文本差异对比 |
+| 数字格式 | `formatx` `bytesize` | 千分位 / 货币 / 百分比 / bit~EB 字节单位换算 |
+| 校验 | `validator` | 邮箱 / 大陆手机号 / IPv4-6 / URL / 18 位身份证（含校验码） |
+| 标识 | `ids` `password` | UUIDv1/3/4/5/**7** / 短 ID / NanoID / 随机密码与强度评估 |
+| 容错 | `retryx` `decorators` | 重试（指数退避）/ 计时 / 抑制异常 / 单机限流 / 模块分隔块 |
+| 定时 | `cronx` | Cron 解析 / 下次运行时间 / 中文描述 |
+| 数据表 | `webdata` `chardata` | HTTP 状态码 / Content-Type / UA 列表与解析 / ASCII / HTML 实体 / Emoji 大全 |
+| 文件 | `files` `env` | 安全读写（原子写）/ 文件信息 / MIME / 环境变量类型安全读取 |
+| 日志 | `log` | 多文件日志工厂：总/级别/分类，双条件滚动 + 压缩 + 保留策略 |
+| 加解密 | `security` `jwtx` | AES-GCM/CBC、DES/3DES、RSA、Bcrypt、JWT（可选依赖） |
+| 媒体 | `imagex` `qrcodex` `barcodex` `pdfx` | 图片压缩/水印/favicon、二维码、条形码、PDF 处理（可选依赖） |
+| 集合 | `collx` `convert` | 深度合并 / 分块 / 扁平化 / 去重 / 类型安全转换 |
+
+## FAQ
+
+**Q: 为什么还有 MD5？** 兼容遗留系统与缓存键等非安全场景而保留；`md5()` 的文档与本文均标注其不适用于安全用途，本库一切默认算法均为 SHA256。
+
+**Q: 能离线使用吗？** 能。核心零依赖；可选功能在安装好对应依赖后同样完全离线运行，不发起任何网络请求。
+
+**Q: 会影响我的应用日志吗？** 不会。lantool 作为库自身不配置任何 logger、不触碰 root logger；`get_logger` 仅在你显式调用时才创建独立的日志体系（`propagate=False`，与应用日志隔离）。
+
+**Q: `convert.to_int` 与 `bytesize.convert_size` 什么区别？** 前者是类型转换域（str→int 等宽松转换），后者是存储单位换算域（KB→MB 等），分属不同模块以保持单一职责。
+
+**Q: 如何发布到 PyPI？** 详见 **[发布到 PyPI 完整指南](docs/publish.md)**（Trusted Publisher / twine / uv 三种方式、TestPyPI 演练、常见问题排查）。本仓库托管于 [Gitee](https://gitee.com/lancelan6/lantool)（Gitee 不支持 Trusted Publisher），可本地 `python -m build && twine upload dist/*` 直接发布，或镜像到 GitHub 后使用 CI 中预留的 Trusted Publisher 自动发布。
+
+## 路线图
+
+以下功能刻意未实现（保持轻量），如有需要欢迎提 issue：
+
+- 联网类：汇率查询、HTTP 客户端封装（本库定位离线工具集）
+- 重依赖类：OCR 文字识别、二维码/条形码解析、PDF 转图片渲染
+- 分布式限流（需 Redis 等外部状态存储）
+
+## 开发
+
+```bash
+# 推荐 uv（自动读取 [dependency-groups]）
+uv sync                  # 安装开发依赖
+uv sync --all-extras     # 含全部可选依赖
+uv run pytest            # 运行测试
+uv run ruff check src tests && uv run ruff format --check src tests
+
+# 亦可用 pip
+pip install -e ".[dev]"
+pip install -e ".[all]"
+```
+
+发布：打 `v*` 标签推送即可触发 CI 构建，并通过 Trusted Publisher 自动发布到 PyPI。
+
+## 许可证
+
+[MIT](LICENSE)

lantool-0.1.0/README.md

@@ -0,0 +1,194 @@
+# lantool
+
+[![PyPI](https://img.shields.io/pypi/v/lantool.svg)](https://pypi.org/project/lantool/)
+[![Python](https://img.shields.io/pypi/pyversions/lantool.svg)](https://pypi.org/project/lantool/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+轻量实用的 Python 通用工具库：**零依赖核心 + 按需扩展**。
+
+- **开箱即用**：`pip install lantool` 后 `from lantool import sha256, base64_encode` 一行调用，无需实例化、无需配置；
+- **零依赖核心**：约七成功能（编解码/哈希/时间/文本/JSON/日志/校验/Cron 等 23 个模块）纯标准库实现，完全离线可用；
+- **按需扩展**：加解密、JWT、图片、PDF 等通过 extras 按需安装，缺失时给出清晰的安装提示；
+- **源码即拷即用**：整包 `src/lantool` 拷入任意工程（FastAPI / Flask / Django / 脚本）同样直接 `import lantool` 使用；
+- **Python 3.11+**：时间 API 避开 3.12+ 废弃接口（如 `utcnow`），提供 timezone-aware 的 `now_utc`；PEP 561 类型标记，IDE 补全友好。
+
+## 安装
+
+```bash
+# pip
+pip install lantool                  # 零依赖核心
+pip install "lantool[security]"      # 加解密（AES/RSA/Bcrypt）
+pip install "lantool[all]"           # 全功能一键安装
+
+# uv
+uv pip install lantool
+uv add "lantool[all]"                # 在 uv 管理的项目中添加依赖
+```
+
+### 可选功能（extras）
+
+| extras | 功能 | 依赖 |
+| --- | --- | --- |
+| （无） | 核心 23 模块（纯标准库） | 无 |
+| `security` | AES/DES/3DES/RSA/Bcrypt | `cryptography`、`bcrypt` |
+| `jwt` | JWT 签发与校验 | `PyJWT` |
+| `yaml` | JSON/YAML 互转 | `PyYAML` |
+| `image` | 图片压缩/水印/favicon | `Pillow` |
+| `qr` | 二维码生成（PNG/SVG） | `qrcode`、`Pillow` |
+| `barcode` | 条形码生成 | `python-barcode`、`Pillow` |
+| `pdf` | PDF 拆分/合并/水印/图片转 PDF | `pypdf`、`Pillow` |
+| `all` | 以上全部 | — |
+
+未安装对应依赖时调用可选功能，会得到明确提示：
+
+```
+OptionalDependencyError: 缺少可选依赖 cryptography，请先安装: pip install "lantool[security]" 或 uv pip install "lantool[security]"
+```
+
+## 快速开始
+
+### 编解码与哈希
+
+```python
+from lantool import base64_encode, base64_decode, sha256, url_encode, convert_base
+
+base64_encode("你好 lantool")          # '5L2g5aW9IGxhbnRvb2w='
+base64_decode("5L2g5aW9IGxhbnRvb2w=")  # '你好 lantool'
+sha256("abc")                          # 'ba7816bf8f01cfea...'
+url_encode("a b/c")                    # 'a%20b%2Fc'
+convert_base("hello", 36, 10)          # '29234652'（支持 2~36 任意进制）
+```
+
+### 时间与时间戳
+
+```python
+from lantool import now_str, timestamp, from_timestamp, human_duration
+
+now_str()                     # '2026-11-07 15:30:00'（默认格式 YYYY-MM-DD HH:MM:SS）
+timestamp()                   # 1780000000（秒级）
+timestamp(seconds=False)      # 1780000000123（毫秒级）
+from_timestamp(1700000000)    # datetime（13 位毫秒自动识别）
+human_duration(90061)         # '1天1小时1分1秒'
+```
+
+### 文本与 JSON
+
+```python
+from lantool import to_snake, to_camel, java_fields, pretty, compact, dumps
+from datetime import datetime
+
+to_snake("HTTPServer")        # 'http_server'
+to_camel("user_login_count")  # 'userLoginCount'
+java_fields("id\nuserName\nprice\ncreateTime\nisVip")
+#     private Long id;
+#     private String userName;
+#     private BigDecimal price;
+#     private LocalDateTime createTime;
+#     private Boolean isVip;
+
+dumps({"at": datetime.now()})  # datetime 自动 ISO 序列化
+compact('{"a": 1}')            # '{"a":1}'
+pretty({"list": [1, 2]})       # 格式化缩进，中文原样输出
+```
+
+### 加解密与 JWT（需 extras）
+
+```python
+from lantool import aes_encrypt, aes_decrypt, jwt_encode, jwt_decode, bcrypt_hash, bcrypt_verify
+
+token = aes_encrypt("机密数据", "your-key")        # AES-256-GCM，默认推荐
+aes_decrypt(token, "your-key")                    # '机密数据'
+
+jwt = jwt_encode({"sub": "user-1"}, "32-byte-secret...!!", expires_in=3600)
+jwt_decode(jwt, "32-byte-secret...!!")            # {'sub': 'user-1', 'iat': ..., 'exp': ...}
+
+hashed = bcrypt_hash("my-password")               # 口令存储推荐
+bcrypt_verify("my-password", hashed)              # True
+```
+
+### 日志（总 + 级别 + 分类，双条件滚动）
+
+```python
+from lantool import get_logger
+
+log = get_logger("app")            # logs/app.log（总）+ app_error.log + app_warning.log
+access = get_logger("app.access")  # 分类：logs/app_access.log，同时汇入总日志与控制台
+
+log.info("服务启动")
+access.info("GET /api/users 200")
+log.error("数据库连接失败")
+```
+
+单文件超 100MB 或跨天自动滚动，旧日志 gzip 压缩，默认保留 366 天（全部可配置）。
+
+### 更多示例
+
+- **[从零开始完整指南](docs/getting-started.md)** —— 安装部署、自检、快速上手、FastAPI/Flask/Django 集成实战、日志部署、故障排查
+- **[使用指南](docs/usage.md)** —— 全部 API 说明与示例
+
+自检本机环境：
+
+```bash
+python -m lantool   # 输出版本、Python 环境与各 extras 可用性
+```
+
+## 功能矩阵
+
+| 领域 | 模块 | 主要能力 |
+| --- | --- | --- |
+| 编解码 | `encoding` | Base64 / URL / Hex / Unicode 中文互转 / 摩斯密码 / 2~36 进制 / 图片转 Base64 |
+| 哈希 | `hashing` | MD5 / SHA1 / SHA224-512 / HMAC / 文件哈希 / CRC32 |
+| 时间 | `times` | 时间戳（秒/毫秒互转）/ 多格式当前时间 / 人性化时长 |
+| 文本 | `text` | 驼峰互转 / 大小写 / 字数统计 / 自然排序 / 脱敏 / Java 字段生成 |
+| 数据格式 | `jsonx` `xmlix` `diffx` | JSON 智能序列化与格式化 / XML 格式化 / 文本差异对比 |
+| 数字格式 | `formatx` `bytesize` | 千分位 / 货币 / 百分比 / bit~EB 字节单位换算 |
+| 校验 | `validator` | 邮箱 / 大陆手机号 / IPv4-6 / URL / 18 位身份证（含校验码） |
+| 标识 | `ids` `password` | UUIDv1/3/4/5/**7** / 短 ID / NanoID / 随机密码与强度评估 |
+| 容错 | `retryx` `decorators` | 重试（指数退避）/ 计时 / 抑制异常 / 单机限流 / 模块分隔块 |
+| 定时 | `cronx` | Cron 解析 / 下次运行时间 / 中文描述 |
+| 数据表 | `webdata` `chardata` | HTTP 状态码 / Content-Type / UA 列表与解析 / ASCII / HTML 实体 / Emoji 大全 |
+| 文件 | `files` `env` | 安全读写（原子写）/ 文件信息 / MIME / 环境变量类型安全读取 |
+| 日志 | `log` | 多文件日志工厂：总/级别/分类，双条件滚动 + 压缩 + 保留策略 |
+| 加解密 | `security` `jwtx` | AES-GCM/CBC、DES/3DES、RSA、Bcrypt、JWT（可选依赖） |
+| 媒体 | `imagex` `qrcodex` `barcodex` `pdfx` | 图片压缩/水印/favicon、二维码、条形码、PDF 处理（可选依赖） |
+| 集合 | `collx` `convert` | 深度合并 / 分块 / 扁平化 / 去重 / 类型安全转换 |
+
+## FAQ
+
+**Q: 为什么还有 MD5？** 兼容遗留系统与缓存键等非安全场景而保留；`md5()` 的文档与本文均标注其不适用于安全用途，本库一切默认算法均为 SHA256。
+
+**Q: 能离线使用吗？** 能。核心零依赖；可选功能在安装好对应依赖后同样完全离线运行，不发起任何网络请求。
+
+**Q: 会影响我的应用日志吗？** 不会。lantool 作为库自身不配置任何 logger、不触碰 root logger；`get_logger` 仅在你显式调用时才创建独立的日志体系（`propagate=False`，与应用日志隔离）。
+
+**Q: `convert.to_int` 与 `bytesize.convert_size` 什么区别？** 前者是类型转换域（str→int 等宽松转换），后者是存储单位换算域（KB→MB 等），分属不同模块以保持单一职责。
+
+**Q: 如何发布到 PyPI？** 详见 **[发布到 PyPI 完整指南](docs/publish.md)**（Trusted Publisher / twine / uv 三种方式、TestPyPI 演练、常见问题排查）。本仓库托管于 [Gitee](https://gitee.com/lancelan6/lantool)（Gitee 不支持 Trusted Publisher），可本地 `python -m build && twine upload dist/*` 直接发布，或镜像到 GitHub 后使用 CI 中预留的 Trusted Publisher 自动发布。
+
+## 路线图
+
+以下功能刻意未实现（保持轻量），如有需要欢迎提 issue：
+
+- 联网类：汇率查询、HTTP 客户端封装（本库定位离线工具集）
+- 重依赖类：OCR 文字识别、二维码/条形码解析、PDF 转图片渲染
+- 分布式限流（需 Redis 等外部状态存储）
+
+## 开发
+
+```bash
+# 推荐 uv（自动读取 [dependency-groups]）
+uv sync                  # 安装开发依赖
+uv sync --all-extras     # 含全部可选依赖
+uv run pytest            # 运行测试
+uv run ruff check src tests && uv run ruff format --check src tests
+
+# 亦可用 pip
+pip install -e ".[dev]"
+pip install -e ".[all]"
+```
+
+发布：打 `v*` 标签推送即可触发 CI 构建，并通过 Trusted Publisher 自动发布到 PyPI。
+
+## 许可证
+
+[MIT](LICENSE)