tea-tool 0.1.0__tar.gz

tea_tool-0.1.0/LICENSE

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

tea_tool-0.1.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.3
+Name: tea-tool
+Version: 0.1.0
+Summary: Commonly used Python development toolkits in business development.
+Author: Corenca
+Author-email: Corenca <corenca.wang@gmail.com>
+License: MIT License
+         
+         Copyright (c) 2026 Corenca
+         
+         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.
+Requires-Dist: polars[pyarrow]>=1.44.1
+Requires-Dist: pydantic>=2.13.5
+Requires-Dist: fastexcel>=0.21.0 ; extra == 'excel'
+Requires-Dist: xlsxwriter>=3.2.9 ; extra == 'excel'
+Requires-Python: >=3.12
+Provides-Extra: excel
+Description-Content-Type: text/markdown
+
+# tea-tool
+
+Commonly used Python development toolkits in business development.
+
+业务开发常用的 Python 工具集，面向 Python >= 3.12，基于 polars 与 pydantic 构建，覆盖数据读写（CSV / Excel）、时间处理、数据脱敏、数据模型基类等高频场景。
+
+## 特性一览
+
+| 模块 | 定位 | 状态 |
+| --- | --- | --- |
+| `tea_tool.util.collection` | 列表 / range / 任意可迭代对象的切分（按大小或按份数） | 已实现 |
+| `tea_tool.util.csv` | CSV 与 polars DataFrame 互转 | 已实现 |
+| `tea_tool.util.excel` | .xlsx 与 polars DataFrame 互转（需安装 `excel` 可选依赖） | 已实现 |
+| `tea_tool.util.enum` | 带额外信息 `msg` 的值枚举基类 `ValueMsgEnum` | 已实现 |
+| `tea_tool.datetime` | 时间处理：格式常量、时区常量、日历时刻边界与解析函数 | 已实现 |
+| `tea_tool.masking` | 通用脱敏：机制（策略 / 规则 / 编排器）与内容（业务规则）分离 | 已实现 |
+| `tea_tool.schema` | pydantic 模型统一基类与时间字段 JSON 序列化别名 | 已实现 |
+| `tea_tool.django` / `tea_tool.storage` | Django / 对象存储相关工具 | 计划中 |
+
+## 安装
+
+要求 Python >= 3.12，已发布到 PyPI：
+
+```bash
+# pip
+pip install tea-tool
+```
+
+```bash
+# uv
+uv add tea-tool
+```
+
+Excel 读写（`util.excel`）依赖可选的 fastexcel 与 xlsxwriter，按需安装：
+
+```bash
+pip install 'tea-tool[excel]'
+# 或
+uv add 'tea-tool[excel]'
+```
+
+未安装可选依赖时，调用对应读写函数会抛出带安装指引的 ImportError，指引信息同时给出 pip 与 uv 两种安装方式。
+
+## 模块速览
+
+各模块的每个函数 / 类的参数说明与用法示例见对应源码 docstring。
+
+- `tea_tool.util.collection` — 按固定大小切分可迭代对象（`chunked`、`chunk_list`），或按指定份数均分列表 / range（`split_list`、`split_range`），以及 range 版本的分块（`chunk_range`）。
+- `tea_tool.util.csv` — `csv_to_df` 读取 CSV 为 polars DataFrame、`df_to_csv` 将 DataFrame 写出为 CSV。
+- `tea_tool.util.excel` — `excel_to_df` 读取 .xlsx 为 polars DataFrame（支持文件表头到内存列名的映射）、`df_to_excel` 将 DataFrame 写出为 .xlsx。
+- `tea_tool.util.enum` — `ValueMsgEnum`：成员以 `(value, msg)` 二元组声明，`value` 为枚举值，`msg` 携带对应额外信息，并提供按值查找的 `get()`。
+- `tea_tool.datetime.formatter` — 常用日期时间格式常量：连字符 / 斜杠 / 中文 / ISO 等（如 `DATE_FORMAT`、`DATE_TIME_FORMAT_CN`）。
+- `tea_tool.datetime.timezone` — 常用 IANA 时区常量（`UTC`、`SHANGHAI`、`NEW_YORK` 等）与获取本地时区的 `local_tz()`。
+- `tea_tool.datetime.util` — 时段边界（`get_month_start` / `get_month_end` / `get_day_start` / `get_day_range`）、当月天数（`get_days_in_month`）、日期序列（`list_days`）、当前时刻（`get_local_time` / `get_utc_time`）、字符串解析（`parse_datetime`）。
+- `tea_tool.masking` — 机制与内容分离的脱敏工具：策略定义"如何脱"（`KeepStrategy` / `ReplaceStrategy` / `HashStrategy` / `RemoveStrategy`），规则在自由文本中发现敏感片段，`Masker` 提供 `mask`（单值）、`mask_text`（自由文本自动识别）、`mask_dict`（结构化字段映射）三个入口；`presets` 模块提供中国大陆常见个人信息的预置识别规则（手机号、身份证、邮箱、IP、银行卡号）。
+- `tea_tool.schema` — 项目数据模型统一基类 `BaseModel`（预设 `from_attributes`、`validate_assignment`、`populate_by_name`、忽略未声明字段等配置），以及 `DateTimeField` / `DateField` / `LocalDateTimeField` 时间字段标注（json 序列化时输出固定格式字符串）。
+
+## 开发与测试
+
+项目由 uv 管理，采用 src 布局，测试目录镜像源码目录结构：
+
+```bash
+uv sync            # 安装依赖（含 dev 组）
+uv run pytest      # 运行测试
+uv run ruff check  # 静态检查
+uv run ruff format # 格式化
+uv build           # 构建 wheel / sdist
+```
+
+## License
+
+MIT

tea_tool-0.1.0/README.md

@@ -0,0 +1,72 @@
+# tea-tool
+
+Commonly used Python development toolkits in business development.
+
+业务开发常用的 Python 工具集，面向 Python >= 3.12，基于 polars 与 pydantic 构建，覆盖数据读写（CSV / Excel）、时间处理、数据脱敏、数据模型基类等高频场景。
+
+## 特性一览
+
+| 模块 | 定位 | 状态 |
+| --- | --- | --- |
+| `tea_tool.util.collection` | 列表 / range / 任意可迭代对象的切分（按大小或按份数） | 已实现 |
+| `tea_tool.util.csv` | CSV 与 polars DataFrame 互转 | 已实现 |
+| `tea_tool.util.excel` | .xlsx 与 polars DataFrame 互转（需安装 `excel` 可选依赖） | 已实现 |
+| `tea_tool.util.enum` | 带额外信息 `msg` 的值枚举基类 `ValueMsgEnum` | 已实现 |
+| `tea_tool.datetime` | 时间处理：格式常量、时区常量、日历时刻边界与解析函数 | 已实现 |
+| `tea_tool.masking` | 通用脱敏：机制（策略 / 规则 / 编排器）与内容（业务规则）分离 | 已实现 |
+| `tea_tool.schema` | pydantic 模型统一基类与时间字段 JSON 序列化别名 | 已实现 |
+| `tea_tool.django` / `tea_tool.storage` | Django / 对象存储相关工具 | 计划中 |
+
+## 安装
+
+要求 Python >= 3.12，已发布到 PyPI：
+
+```bash
+# pip
+pip install tea-tool
+```
+
+```bash
+# uv
+uv add tea-tool
+```
+
+Excel 读写（`util.excel`）依赖可选的 fastexcel 与 xlsxwriter，按需安装：
+
+```bash
+pip install 'tea-tool[excel]'
+# 或
+uv add 'tea-tool[excel]'
+```
+
+未安装可选依赖时，调用对应读写函数会抛出带安装指引的 ImportError，指引信息同时给出 pip 与 uv 两种安装方式。
+
+## 模块速览
+
+各模块的每个函数 / 类的参数说明与用法示例见对应源码 docstring。
+
+- `tea_tool.util.collection` — 按固定大小切分可迭代对象（`chunked`、`chunk_list`），或按指定份数均分列表 / range（`split_list`、`split_range`），以及 range 版本的分块（`chunk_range`）。
+- `tea_tool.util.csv` — `csv_to_df` 读取 CSV 为 polars DataFrame、`df_to_csv` 将 DataFrame 写出为 CSV。
+- `tea_tool.util.excel` — `excel_to_df` 读取 .xlsx 为 polars DataFrame（支持文件表头到内存列名的映射）、`df_to_excel` 将 DataFrame 写出为 .xlsx。
+- `tea_tool.util.enum` — `ValueMsgEnum`：成员以 `(value, msg)` 二元组声明，`value` 为枚举值，`msg` 携带对应额外信息，并提供按值查找的 `get()`。
+- `tea_tool.datetime.formatter` — 常用日期时间格式常量：连字符 / 斜杠 / 中文 / ISO 等（如 `DATE_FORMAT`、`DATE_TIME_FORMAT_CN`）。
+- `tea_tool.datetime.timezone` — 常用 IANA 时区常量（`UTC`、`SHANGHAI`、`NEW_YORK` 等）与获取本地时区的 `local_tz()`。
+- `tea_tool.datetime.util` — 时段边界（`get_month_start` / `get_month_end` / `get_day_start` / `get_day_range`）、当月天数（`get_days_in_month`）、日期序列（`list_days`）、当前时刻（`get_local_time` / `get_utc_time`）、字符串解析（`parse_datetime`）。
+- `tea_tool.masking` — 机制与内容分离的脱敏工具：策略定义"如何脱"（`KeepStrategy` / `ReplaceStrategy` / `HashStrategy` / `RemoveStrategy`），规则在自由文本中发现敏感片段，`Masker` 提供 `mask`（单值）、`mask_text`（自由文本自动识别）、`mask_dict`（结构化字段映射）三个入口；`presets` 模块提供中国大陆常见个人信息的预置识别规则（手机号、身份证、邮箱、IP、银行卡号）。
+- `tea_tool.schema` — 项目数据模型统一基类 `BaseModel`（预设 `from_attributes`、`validate_assignment`、`populate_by_name`、忽略未声明字段等配置），以及 `DateTimeField` / `DateField` / `LocalDateTimeField` 时间字段标注（json 序列化时输出固定格式字符串）。
+
+## 开发与测试
+
+项目由 uv 管理，采用 src 布局，测试目录镜像源码目录结构：
+
+```bash
+uv sync            # 安装依赖（含 dev 组）
+uv run pytest      # 运行测试
+uv run ruff check  # 静态检查
+uv run ruff format # 格式化
+uv build           # 构建 wheel / sdist
+```
+
+## License
+
+MIT

tea_tool-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[project]
+name = "tea-tool"
+version = "0.1.0"
+readme = "README.md"
+description = "Commonly used Python development toolkits in business development."
+requires-python = ">=3.12"
+dependencies = [
+    "polars[pyarrow]>=1.44.1",
+    "pydantic>=2.13.5",
+]
+
+[project.license]
+file = "LICENSE"
+
+[[project.authors]]
+name = "Corenca"
+email = "corenca.wang@gmail.com"
+
+[project.optional-dependencies]
+excel = [
+    "fastexcel>=0.21.0",
+    "xlsxwriter>=3.2.9",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.8,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "fastexcel>=0.21.0",
+    "ipython>=9.17.1",
+    "pytest>=9.1.1",
+    "ruff>=0.16.5",
+    "xlsxwriter>=3.2.9",
+]

tea_tool-0.1.0/pyproject.toml.orig

@@ -0,0 +1,33 @@
+[project]
+name = "tea-tool"
+version = "0.1.0"
+license = {file = "LICENSE"}
+readme = "README.md"
+description = "Commonly used Python development toolkits in business development."
+authors = [
+    { name = "Corenca", email = "corenca.wang@gmail.com" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "polars[pyarrow]>=1.44.1",
+    "pydantic>=2.13.5",
+]
+
+[project.optional-dependencies]
+excel = [
+    "fastexcel>=0.21.0",
+    "xlsxwriter>=3.2.9",
+]
+
+[build-system]
+requires = ["uv_build>=0.12.8,<0.13.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "fastexcel>=0.21.0",
+    "ipython>=9.17.1",
+    "pytest>=9.1.1",
+    "ruff>=0.16.5",
+    "xlsxwriter>=3.2.9",
+]

tea_tool-0.1.0/src/tea_tool/datetime/formatter.py

@@ -0,0 +1,40 @@
+"""日期时间 strftime/strptime 格式化模板常量。
+
+常量按粒度组织：DATE（日）、TIME（时间）、DATE_TIME（日期时间）、MONTH（月）与
+YEAR 系压缩串（%Y%m%d…，常用于文件名/键）。同一粒度提供连字符（默认）、斜杠
+（_SLASH）、中文（_CN）分隔变体；后缀 _ZONE 携带 %z 时区偏移、_ISO 为 ISO 8601
+扩展 T 分隔。注意：%f 恒为 6 位微秒且 strftime 不支持截宽，故含 %f 的模板按
+微秒（MICROSECOND）命名；%z 输出形如 +0800 无冒号（近似 RFC 3339，非严格）。
+"""
+
+# 日期
+DATE_FORMAT = "%Y-%m-%d"
+DATE_FORMAT_SLASH = "%Y/%m/%d"
+DATE_FORMAT_CN = "%Y年%m月%d日"
+
+# 时间
+TIME_FORMAT = "%H:%M:%S"
+TIME_FORMAT_MINUTE = "%H:%M"
+TIME_FORMAT_SLASH = "%H/%M/%S"
+TIME_FORMAT_CN = "%H时%M分%S秒"
+
+# 日期时间
+DATE_TIME_FORMAT = "%Y-%m-%d %H:%M:%S"
+DATE_TIME_FORMAT_SLASH = "%Y/%m/%d %H:%M:%S"
+DATE_TIME_FORMAT_CN = "%Y年%m月%d日 %H时%M分%S秒"
+DATE_TIME_MICROSECOND = "%Y-%m-%d %H:%M:%S.%f"
+DATE_TIME_ZONE = "%Y-%m-%d %H:%M:%S%z"
+DATE_TIME_ISO = "%Y-%m-%dT%H:%M:%S"
+DATE_TIME_ISO_ZONE = "%Y-%m-%dT%H:%M:%S%z"
+
+# 月
+MONTH_FORMAT = "%Y-%m"
+
+# 年份系压缩串（无分隔符，常用于文件名/键）
+YEAR = "%Y"
+YEAR_TO_MONTH = "%Y%m"
+YEAR_TO_DAY = "%Y%m%d"
+YEAR_TO_HOUR = "%Y%m%d%H"
+YEAR_TO_MINUTE = "%Y%m%d%H%M"
+YEAR_TO_SECOND = "%Y%m%d%H%M%S"
+YEAR_TO_MICROSECOND = "%Y%m%d%H%M%S.%f"

tea_tool-0.1.0/src/tea_tool/datetime/timezone.py

@@ -0,0 +1,58 @@
+"""常用时区常量与本地时区获取。
+
+常量覆盖 UTC 及主流业务城市的 IANA 时区（UTC-12 ~ UTC+14 各主要时区带），
+命名统一全大写、多词下划线分隔，可直接作为 tzinfo 参数传入 datetime 相关
+构造与 tea_tool.datetime.util 各函数。依赖 zoneinfo（Python 3.9+ 内置），
+具体时区数据取自已安装的 tzdata。
+"""
+
+from datetime import datetime, tzinfo
+from zoneinfo import ZoneInfo
+
+UTC = ZoneInfo("UTC")
+
+# 亚洲
+SHANGHAI = ZoneInfo("Asia/Shanghai")
+SINGAPORE = ZoneInfo("Asia/Singapore")
+TOKYO = ZoneInfo("Asia/Tokyo")
+SEOUL = ZoneInfo("Asia/Seoul")
+HONG_KONG = ZoneInfo("Asia/Hong_Kong")
+BANGKOK = ZoneInfo("Asia/Bangkok")
+DUBAI = ZoneInfo("Asia/Dubai")
+KOLKATA = ZoneInfo("Asia/Kolkata")
+
+# 欧洲
+LONDON = ZoneInfo("Europe/London")
+PARIS = ZoneInfo("Europe/Paris")
+BERLIN = ZoneInfo("Europe/Berlin")
+AMSTERDAM = ZoneInfo("Europe/Amsterdam")
+MOSCOW = ZoneInfo("Europe/Moscow")
+
+# 美洲
+NEW_YORK = ZoneInfo("America/New_York")
+LOS_ANGELES = ZoneInfo("America/Los_Angeles")
+CHICAGO = ZoneInfo("America/Chicago")
+TORONTO = ZoneInfo("America/Toronto")
+SAO_PAULO = ZoneInfo("America/Sao_Paulo")
+
+# 大洋洲
+SYDNEY = ZoneInfo("Australia/Sydney")
+AUCKLAND = ZoneInfo("Pacific/Auckland")
+
+# 非洲
+JOHANNESBURG = ZoneInfo("Africa/Johannesburg")
+
+
+def local_tz() -> tzinfo:
+    """返回系统本地时区。
+
+    本地时区取自运行环境（TZ 环境变量或系统设置），与 datetime.now().astimezone()
+    的时区归属一致；系统时区可被识别为具体区域时返回 ZoneInfo，否则退化为固定
+    偏移时区。
+
+    Returns:
+        当前系统本地时区对应的 tzinfo 对象。
+    """
+    local = datetime.now().astimezone().tzinfo
+    assert local is not None
+    return local

tea_tool-0.1.0/src/tea_tool/datetime/util.py

@@ -0,0 +1,194 @@
+"""datetime 日期时间通用工具。
+
+提供日历运算（月份首末日、逐日序列）与时刻获取（日零点、当日时间范围、
+本地/UTC 当前时间、字符串解析）。日历运算中的月份首末日与逐日序列
+（get_month_start、get_month_end、list_days）仅接受 date；get_days_in_month
+接受 date/datetime（仅用其年月）。时刻类函数（get_day_start、get_day_range、
+get_local_time、get_utc_time、parse_datetime）产出 datetime：date 输入按该日
+提升，datetime 输入保留 naive/aware 属性。时区语义：本模块只做钟面解释
+（attach），不做跨时区换算；"本地时区"指系统时区，可用 timezone.local_tz()
+获取。
+"""
+
+from calendar import monthrange
+from datetime import UTC, date, datetime, time, timedelta, tzinfo
+
+from .timezone import local_tz
+
+
+def _shift_year_month(value: date | datetime, months: int) -> tuple[int, int]:
+    """计算 value 所在月偏移 months 个月后的 (年, 月)。
+
+    months 为负时同样正确（divmod 对负值取整向负无穷），例如 2026-01 偏移 -1
+    得到 (2025, 12)。
+
+    Args:
+        value: 基准日期或时间，取其所在年与月。
+        months: 月份偏移量。
+
+    Returns:
+        偏移后的 (年, 月) 二元组。
+    """
+    total = value.year * 12 + (value.month - 1) + months
+    year, month_index = divmod(total, 12)
+    return year, month_index + 1
+
+
+def get_month_start(value: date | datetime, months: int = 0) -> date:
+    """返回 value 所在月偏移 months 个月后的首日。
+
+    months 为正表示偏移到之后的月份、为负表示之前的月份，0（默认）即 value 所在
+    当月。value 无论 date 还是 datetime 均统一返回 date（datetime 仅取其年与月，
+    不带时分秒与时区），例如 2026-01-31 10:30 偏移 1 个月返回 2026-02-01。
+
+    Args:
+        value: 基准日期或时间，取其所在月。
+        months: 月份偏移量，正为后负为前，默认当月。
+
+    Returns:
+        目标月首日（date）。
+    """
+    year, month = _shift_year_month(value, months)
+    return date(year, month, 1)
+
+
+def get_month_end(value: date | datetime, months: int = 0) -> date:
+    """返回 value 所在月偏移 months 个月后的末日。
+
+    月份偏移语义与 get_month_start 一致（正后负前，0 为当月）；返回目标月的最后
+    一天，跨月取末日不受 value 原日影响，例如 2026-01-31 偏移 1 个月返回
+    2026-02-28。value 无论 date 还是 datetime 均统一返回 date（datetime 仅取其
+    年与月，不带时分秒与时区）。
+
+    Args:
+        value: 基准日期或时间，取其所在月。
+        months: 月份偏移量，正为后负为前，默认当月。
+
+    Returns:
+        目标月末日（date）。
+    """
+    year, month = _shift_year_month(value, months)
+    last = monthrange(year, month)[1]
+    return date(year, month, last)
+
+
+def get_days_in_month(value: date | datetime) -> int:
+    """返回 value 所在月的天数。
+
+    Args:
+        value: 基准日期或时间，取其所在月。
+
+    Returns:
+        所在月的天数（平年 2 月为 28、闰年为 29）。
+    """
+    return monthrange(value.year, value.month)[1]
+
+
+def get_day_start(value: date | datetime) -> datetime:
+    """返回 value 所在日的零点时刻。
+
+    时刻域函数：date 输入提升为当日 00:00 的 naive datetime；naive datetime 清零
+    时分秒与微秒；aware datetime 清零时刻但保留其 tzinfo（DST 切换日零点通常无
+    歧义，不做 fold 处理）。
+
+    Args:
+        value: 基准日期或时间，取其所在日。
+
+    Returns:
+        所在日零点对应的 datetime（naive 或保留输入的 aware 属性）。
+    """
+    if isinstance(value, datetime):
+        return value.replace(hour=0, minute=0, second=0, microsecond=0)
+    return datetime.combine(value, time.min)
+
+
+def get_day_range(
+    value: date | datetime, tz: tzinfo | None = None
+) -> tuple[datetime, datetime]:
+    """返回 value 所在日的时间范围 [当日零点, 次日零点)，左闭右开。
+
+    时刻域函数，返回值恒为 datetime 对。时区规则：
+    - tz 显式给出时，两端钟面时间 attach 该时区（覆盖 value 自带时区，不换算）；
+    - tz 缺省且 value 为 aware datetime 时，沿用 value 的时区；
+    - 其余情形（date / naive datetime）两端为 naive。
+    DST 切换日该范围的实际时长可能非 24 小时，但两端恒为该时区钟面零点。
+
+    Args:
+        value: 基准日期或时间，取其所在日。
+        tz: 目标时区；缺省时沿用输入时区或保持 naive。
+
+    Returns:
+        (当日零点, 次日零点) 元组。
+    """
+    if isinstance(value, datetime):
+        day = value.date()
+        resolved = tz if tz is not None else value.tzinfo
+    else:
+        day = value
+        resolved = tz
+    return (
+        datetime.combine(day, time.min, tzinfo=resolved),
+        datetime.combine(day + timedelta(days=1), time.min, tzinfo=resolved),
+    )
+
+
+def list_days(start: date, end: date) -> list[date]:
+    """返回 [start, end) 区间内逐日 date 序列，左闭右开不含 end。
+
+    start 等于或晚于 end 时返回空列表。
+
+    Args:
+        start: 起始日期（含）。
+        end: 结束日期（不含）。
+
+    Returns:
+        逐日 date 序列；start >= end 时为空列表。
+    """
+    result: list[date] = []
+    cursor = start
+    while cursor < end:
+        result.append(cursor)
+        cursor += timedelta(days=1)
+    return result
+
+
+def get_local_time() -> datetime:
+    """返回系统本地时区的当前时刻（aware）。
+
+    Returns:
+        带系统本地时区的当前 datetime。
+    """
+    return datetime.now().astimezone()
+
+
+def get_utc_time() -> datetime:
+    """返回 UTC 的当前时刻（aware）。
+
+    Returns:
+        带 UTC 时区的当前 datetime。
+    """
+    return datetime.now(UTC)
+
+
+def parse_datetime(text: str, fmt: str, tz: tzinfo | None = None) -> datetime:
+    """按格式化模板将时间字符串解析为 aware datetime。
+
+    结果为钟面解释：模板不含 %z 指令（字符串无时区信息）时，将解析出的钟面
+    时间 attach 到 tz（缺省为系统本地时区）；模板含 %z 指令时解析结果自带偏移
+    并直接返回，此时忽略 tz 参数。DST 歧义时刻按钟面解释，不做特殊折叠处理。
+
+    Args:
+        text: 待解析的时间字符串。
+        fmt: strptime 格式化模板，可复用 tea_tool.datetime.formatter 常量。
+        tz: attach 目标时区，缺省为系统本地时区；模板含 %z 时无效。
+
+    Returns:
+        解析得到的 aware datetime。
+
+    Raises:
+        ValueError: 当 text 与 fmt 不匹配时（strptime 原生异常）。
+    """
+    parsed = datetime.strptime(text, fmt)  # noqa: DTZ007 解析结果 naive 时后续按 tz 参数 attach 时区
+    if parsed.tzinfo is not None:
+        return parsed
+    return parsed.replace(tzinfo=tz if tz is not None else local_tz())

tea_tool-0.1.0/src/tea_tool/masking/__init__.py

@@ -0,0 +1,39 @@
+"""通用脱敏工具：机制与内容分离。
+
+本包提供脱敏机制——策略（strategies）、文本发现规则（rules）与编排器
+（Masker），不内置任何"哪些信息敏感、脱成什么样"的业务默认。规则与
+格式由使用方显式定义，可选用 presets 模块的预置规则集。
+
+典型用法（业务侧全局定义一次后复用）::
+
+    from tea_tool.masking import Masker, KeepStrategy
+    from tea_tool.masking.presets import CN_PII_RULES
+
+    phone_mask = KeepStrategy(prefix=3, suffix=4)
+    masker = Masker(rules=CN_PII_RULES)
+
+    masker.mask("13812345678", phone_mask)          # 138****5678
+    masker.mask_text("联系 13812345678")            # 联系 ***********
+    masker.mask_dict(data, fields={"phone": phone_mask})
+"""
+
+from .core import Masker
+from .rules import MaskMatch, MaskRule
+from .strategies import (
+    HashStrategy,
+    KeepStrategy,
+    MaskStrategy,
+    RemoveStrategy,
+    ReplaceStrategy,
+)
+
+__all__ = [
+    "HashStrategy",
+    "KeepStrategy",
+    "MaskMatch",
+    "MaskRule",
+    "MaskStrategy",
+    "Masker",
+    "RemoveStrategy",
+    "ReplaceStrategy",
+]