abtbb 0.0.1__tar.gz

abtbb-0.0.1/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# 工具缓存
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# 本地配置（含密钥，绝不入库）
+.env
+.env.*
+!.env.example
+
+# IDE
+.idea/
+.vscode/
+.DS_Store

abtbb-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 yayo
+
+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.

abtbb-0.0.1/PKG-INFO

@@ -0,0 +1,111 @@
+Metadata-Version: 2.5
+Name: abtbb
+Version: 0.0.1
+Summary: abt：一个自己也能读懂、自己也能维护的 Python 底层工具包
+Project-URL: Homepage, https://github.com/yanyue/abt
+Author: yayo
+License: MIT
+License-File: LICENSE
+Keywords: library,toolkit,utility
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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
+Requires-Python: >=3.7
+Requires-Dist: typing-extensions<4.8,>=4.0; python_version < '3.8'
+Requires-Dist: typing-extensions>=4.0; python_version >= '3.8'
+Description-Content-Type: text/markdown
+
+# abt
+
+> 一个自己也能读懂、自己也能维护的 Python 底层工具包。
+
+## 这是什么
+
+`abt` 是对既有工具包 `apiboot` 的**从零重写**。
+
+`apiboot` 的功能是 OK 的，但它几乎全部由 AI 生成：代码量涨得很快，却没有一个字是「自己先想清楚再落笔」的。结果是大量冗余封装、过度抽象，作者本人也读不懂——下游项目一旦出问题，除了「再问一次 AI」没有第二条路。
+
+`abt` 重写它，**验收标准不是功能跑通，而是作者本人能在不询问任何 AI 的情况下，读懂并定位任意一个函数的实现与问题。**
+
+## 两条硬规则
+
+1. **不包装 stdlib**。`pathlib` / `datetime` / `json` 能直接用就直接用，只在语义上做了收敛或增强时才封装。
+2. **一次只做一个模块**。每个函数要能一句话说清，docstring 写「为什么」和「不变量」，不写「做了什么」。
+
+## 特色：第三方依赖全部懒加载
+
+`abt` 的**运行时第三方依赖为零**。
+
+```bash
+pip install abt   # 不会顺带装 requests / sqlalchemy / redis
+```
+
+- `import abt` 和 `import abt.<任意子模块>` **绝不会**因为环境里缺某个第三方包而报错。
+- 只有真正**调用到**用到它的那个函数时才会失败，报错信息里会写清楚缺哪个包、为什么要装它、`pip install` 命令是什么。
+
+换句话说，装了不炸；缺依赖在调用点才暴露，而不是在 import 阶段就让整个服务起不来。
+
+## 运行环境
+
+- **Python 3.7+**（最低 3.7；开发环境 3.11）
+- 3.7 的语法下限由 `vermin` 把关：`uv run vermin --target=3.7- --violations abt/` 必须始终通过
+
+## 设计文档
+
+完整的出发点、验收标准、`apiboot` 模块构成、已知坑位清单、重写路线图，都在 [CLAUDE.md](CLAUDE.md) 里。
+
+## 安装
+
+```bash
+uv add abtbb
+```
+
+```python
+from abt import logger
+```
+
+> **发布名 ≠ import 名。** PyPI 上的 `abt` 已被他人占用，所以发布名用 `abtbb`；但 import 名仍是 `abt`——它由包目录名决定，跟发布名无关。
+> （`pip install pillow` → `import PIL` 同理。）
+
+本地开发：
+
+```bash
+uv sync          # 装依赖（含 dev group：pytest / mypy / ruff / vermin）
+uv run pytest    # 跑测试
+uv run mypy abt  # 静态检查
+uv run ruff check .
+uv run vermin --target=3.7- --violations abt/   # Python 3.7 语法下限闸门
+```
+
+## 命令行
+
+```bash
+abtrun --help
+```
+
+> 命令名用 `abtrun` 而非 `abt`——`abt` 已被 `apiboot` 的 CLI 占用，两个包共存时会互相覆盖 PATH。
+
+## 发布到 PyPI
+
+```bash
+uv sync                                          # 装齐工具链(含 twine)
+python scripts/upload_pypi.py                    # 构建 + 输入 token + 确认上传
+python scripts/upload_pypi.py --dry-run          # 只构建, 不上传, 不用输 token
+python scripts/upload_pypi.py --repository testpypi   # 先发测试仓库试水
+```
+
+流程：清理旧 `dist/` → 重新构建 sdist + wheel → 预检版本号是否已存在 → 提示输入 PyPI API Token（输入不回显，不落盘不进 shell history）→ 询问 `y/n` 确认 → 上传。
+
+Token 申请：<https://pypi.org/manage/account/token/>，用户名固定 `__token__`。
+
+> 同一版本号不能重复发布，报错前请把 `pyproject.toml` 里的 `version` 改大一位。
+
+## License
+
+MIT

abtbb-0.0.1/README.md

@@ -0,0 +1,88 @@
+# abt
+
+> 一个自己也能读懂、自己也能维护的 Python 底层工具包。
+
+## 这是什么
+
+`abt` 是对既有工具包 `apiboot` 的**从零重写**。
+
+`apiboot` 的功能是 OK 的，但它几乎全部由 AI 生成：代码量涨得很快，却没有一个字是「自己先想清楚再落笔」的。结果是大量冗余封装、过度抽象，作者本人也读不懂——下游项目一旦出问题，除了「再问一次 AI」没有第二条路。
+
+`abt` 重写它，**验收标准不是功能跑通，而是作者本人能在不询问任何 AI 的情况下，读懂并定位任意一个函数的实现与问题。**
+
+## 两条硬规则
+
+1. **不包装 stdlib**。`pathlib` / `datetime` / `json` 能直接用就直接用，只在语义上做了收敛或增强时才封装。
+2. **一次只做一个模块**。每个函数要能一句话说清，docstring 写「为什么」和「不变量」，不写「做了什么」。
+
+## 特色：第三方依赖全部懒加载
+
+`abt` 的**运行时第三方依赖为零**。
+
+```bash
+pip install abt   # 不会顺带装 requests / sqlalchemy / redis
+```
+
+- `import abt` 和 `import abt.<任意子模块>` **绝不会**因为环境里缺某个第三方包而报错。
+- 只有真正**调用到**用到它的那个函数时才会失败，报错信息里会写清楚缺哪个包、为什么要装它、`pip install` 命令是什么。
+
+换句话说，装了不炸；缺依赖在调用点才暴露，而不是在 import 阶段就让整个服务起不来。
+
+## 运行环境
+
+- **Python 3.7+**（最低 3.7；开发环境 3.11）
+- 3.7 的语法下限由 `vermin` 把关：`uv run vermin --target=3.7- --violations abt/` 必须始终通过
+
+## 设计文档
+
+完整的出发点、验收标准、`apiboot` 模块构成、已知坑位清单、重写路线图，都在 [CLAUDE.md](CLAUDE.md) 里。
+
+## 安装
+
+```bash
+uv add abtbb
+```
+
+```python
+from abt import logger
+```
+
+> **发布名 ≠ import 名。** PyPI 上的 `abt` 已被他人占用，所以发布名用 `abtbb`；但 import 名仍是 `abt`——它由包目录名决定，跟发布名无关。
+> （`pip install pillow` → `import PIL` 同理。）
+
+本地开发：
+
+```bash
+uv sync          # 装依赖（含 dev group：pytest / mypy / ruff / vermin）
+uv run pytest    # 跑测试
+uv run mypy abt  # 静态检查
+uv run ruff check .
+uv run vermin --target=3.7- --violations abt/   # Python 3.7 语法下限闸门
+```
+
+## 命令行
+
+```bash
+abtrun --help
+```
+
+> 命令名用 `abtrun` 而非 `abt`——`abt` 已被 `apiboot` 的 CLI 占用，两个包共存时会互相覆盖 PATH。
+
+## 发布到 PyPI
+
+```bash
+uv sync                                          # 装齐工具链(含 twine)
+python scripts/upload_pypi.py                    # 构建 + 输入 token + 确认上传
+python scripts/upload_pypi.py --dry-run          # 只构建, 不上传, 不用输 token
+python scripts/upload_pypi.py --repository testpypi   # 先发测试仓库试水
+```
+
+流程：清理旧 `dist/` → 重新构建 sdist + wheel → 预检版本号是否已存在 → 提示输入 PyPI API Token（输入不回显，不落盘不进 shell history）→ 询问 `y/n` 确认 → 上传。
+
+Token 申请：<https://pypi.org/manage/account/token/>，用户名固定 `__token__`。
+
+> 同一版本号不能重复发布，报错前请把 `pyproject.toml` 里的 `version` 改大一位。
+
+## License
+
+MIT

abtbb-0.0.1/abt/__init__.py

@@ -0,0 +1 @@
+# -*- coding:UTF-8 -*-

abtbb-0.0.1/abt/utils/__init__.py

@@ -0,0 +1 @@
+# -*- coding:UTF-8 -*-

abtbb-0.0.1/pyproject.toml

@@ -0,0 +1,160 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+# ⚠️ 这是【PyPI 发布名】, 不是 import 名。
+#    发布名用 `abtbb` —— PyPI 上的 `abt` 已被他人注册, 不能再用, 否则下游
+#    `pip install abt` 会装到别人的包(供应链安全问题)。
+#
+#    发布名与 import 名是两套独立命名空间, 标准做法是二者不同:
+#        pip install abtbb  →  import abt
+#    import 名由下面 [tool.hatch.build.targets.wheel].packages 指定的
+#    目录名决定, 与本字段无关。改发布名只需改本字段一行。
+#
+#    注意 PyPI 名称归一化: abtbb / abt-bb / abt_bb 是同一个项目。
+#    发布前请先确认目标名未被占用:
+#        curl -s -o /dev/null -w "%{http_code}\n" https://pypi.org/pypi/<name>/json
+name = "abtbb"
+version = "0.0.1"
+description = "abt：一个自己也能读懂、自己也能维护的 Python 底层工具包"
+readme = "README.md"
+requires-python = ">=3.7"
+license = { text = "MIT" }
+authors = [{ name = "yayo" }]
+keywords = ["toolkit", "utility", "library"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.7",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+# ---------------------------------------------------------------------------
+# 运行时依赖 —— 刻意保持为零。
+#
+# abt 的核心特色: 所有第三方包都是【懒加载】的。
+#   pip install abtbb 之后, `import abt` 和 import 任意子模块都【绝不】因为
+#   环境里没装 requests / sqlalchemy / redis 而报错;
+#   只有真正调用到用到它的那个函数时才会失败, 并在报错里告诉用户装什么。
+#
+# 所以下面这份列表里只允许出现两类东西:
+#   1) 纯类型兼容层 (typing_extensions) —— 3.7~3.9 没有 typing.Protocol 等
+#   2) 真正的标准库替代品 —— 目前没有
+# 新增可选第三方库时: 写进 [dependency-groups].dev (供 IDE 解析 import),
+# 由使用方自己 pip install, 【不要】加进本段。
+# ---------------------------------------------------------------------------
+dependencies = [
+    # ⚠️ marker 必须覆盖到 3.9(即 < '3.10'), 不能只写 < '3.8'。
+    #    typing.Protocol / get_args / get_origin 是 3.8+, typing.Annotated 是 3.9+,
+    #    typing.ParamSpec 是 3.10+ —— 写窄了 3.8/3.9 环境直接 ModuleNotFoundError。
+    #
+    #    3.7 单独写死上限: typing_extensions 4.8.0 起要求 >=3.8,
+    #    3.7 最高只能用 4.7.1。显式写出来, 不依赖 uv 的版本 fork 行为。
+    "typing_extensions>=4.0,<4.8; python_version < '3.8'",
+    "typing_extensions>=4.0; python_version >= '3.8'",
+]
+
+[project.urls]
+Homepage = "https://github.com/yanyue/abt"
+
+# CLI 入口: pip install abtbb 后进入 PATH。
+# 命令名用 `abtrun`, 不用 `abt` —— `abt` 已被 apiboot 的 [project.scripts] 占用,
+# 两个包共存时 PATH 上的 `abt` 会互相覆盖。
+# ⚠️ 注意: 命令名是【全局】的, 不像包名有 PyPI 命名空间保护。
+#    发布前确认 `abtrun` 不会和别人撞名:  `which -a abtrun`
+[project.scripts]
+abtrun = "abt.cli:main"
+
+# 只打包 abt/ 包目录 —— 这一行决定了【import 名】是 abt。
+# scripts/、tests/、examples/、.venv/ 永远不会进 wheel。
+# .env 显式排除, 防止本地 token 泄露 (白名单 + 黑名单双保险)。
+[tool.hatch.build.targets.wheel]
+packages = ["abt"]
+exclude = [".env", ".env.*", ".envrc"]
+
+[tool.hatch.build.targets.sdist]
+include = ["abt", "README.md", "pyproject.toml", "LICENSE"]
+exclude = ["scripts", "tests", "examples", ".venv", ".idea", ".env", ".env.*", ".envrc"]
+
+# dev 依赖: `uv sync` 时随 dev group 一起装, 不影响 `pip install abtbb` 的用户。
+#
+# 这个 group 同时承担两个职责:
+#   1) 开发工具链 (pytest / mypy / ruff / vermin)
+#   2) 【所有可选第三方库都列在这里】—— 装上后 IDE/Pylance 才能解析这些
+#      `import`, 不再报红; 运行时用户装什么版本就用什么版本, 一个都不装也能跑。
+#
+# ⚠️ 每条都带 `python_version >= '3.8'` marker, 原因:
+#   uv sync 做的是 universal resolution —— 会为 requires-python 覆盖到的
+#   每一个 Python 版本(含 3.7)各求一次解。dev 工具链【不需要】跑在 3.7 上,
+#   但只要它们参与 3.7 的求解, 就会因为新版 pytest / python-dotenv / twine
+#   都要求 >=3.8 而直接 "No solution found"。
+#   加上 marker 后, 3.7 的求解里只剩运行时依赖, 立刻有解。
+#   运行时依赖(typing_extensions)仍然正常覆盖 3.7 —— 这是 3.7 兼容性的关键。
+[dependency-groups]
+dev = [
+    # 开发 / 发布
+    "build; python_version >= '3.8'",
+    "twine; python_version >= '3.8'",
+    # 测试
+    "pytest>=7.4.4; python_version >= '3.8'",
+    # 静态检查
+    "mypy>=1.4.1; python_version >= '3.8'",
+    "ruff>=0.1.0; python_version >= '3.8'",
+    # Python 3.7 兼容性闸门 (mypy >=1.5 已不支持把 3.7 当 target, 改用 vermin)
+    "vermin>=1.6.0; python_version >= '3.8'",
+    # ---- 可选第三方库 (运行时懒加载, 这里只为了 IDE 能解析 import) ----
+    # 配置模块
+    "python-dotenv>=1.0.0; python_version >= '3.8'",
+]
+
+# 使用阿里 PyPI 镜像加速装包(国内开发)
+[tool.uv]
+index-url = "https://mirrors.aliyun.com/pypi/simple/"
+# `uv sync` 默认装 dev group, 免得每次都要 --group dev
+default-groups = ["dev"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+
+[tool.mypy]
+# ⚠️ 不写 python_version: mypy >=1.5 已拒绝 `--python-version 3.7`。
+#    Python 3.7 的语法下限改由下面的 vermin 把关, mypy 只管类型正确性。
+strict = true
+warn_unused_ignores = true
+show_error_codes = true
+warn_unreachable = true
+# 第三方库缺类型标注时不要连带报错
+[[tool.mypy.overrides]]
+module = ["apscheduler.*", "redis.*", "fakeredis.*"]
+ignore_missing_imports = true
+
+[tool.ruff]
+line-length = 100
+# Python 3.7 语法下限。ruff 若在某个版本里不再接受 py37, 改成 py38 即可 ——
+# 真正的下限闸门是上面的 vermin, ruff 这里只用来管现代化改写建议。
+target-version = "py37"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "C4", "SIM"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+# 测试里允许长断言行、允许未使用的 fixture 参数
+"tests/*" = ["E501", "B011"]
+
+# Python 3.7 兼容性的唯一闸门: 静态算出每个文件/特性需要的最低 Python 版本。
+# 命令: uv run vermin --target=3.7- --violations abt/
+[tool.vermin]
+target = "3.7-"
+violations = true
+# 评估字符串注解。默认 vermin 把注解当字符串、不求值, 于是 `int | None` (PEP 604,
+# 3.10+) 这类写法会被漏掉。但 pydantic / SQLModel 的模型类【会】在类定义时求值注解,
+# 3.7 上直接 TypeError —— 所以这里必须开启, 宁可误报也不能漏报。
+eval-annotations = true