abragimbaliev/checkmax-phone-utils

# checkmax-phone-utils [](https://pypi.org/project/checkmax-phone-utils/) [](https://www.python.org/downloads/) [](LICENSE) [](https://checkmaxapp.com) 一个小巧且专注的 Python 工具包，用于电话号码的**格式验证**、 **E.164 标准化**，以及为 [CheckMaxApp](https://checkmaxapp.com) 服务提供的**可选 API 客户端**。基于 Google 的 [libphonenumber](https://github.com/google/libphonenumber)（Python 移植版）构建。 可以在你自己的代码中将其作为开箱即用的辅助工具，或者作为 即将推出的 CheckMaxApp REST API 的客户端库。 ## 快速入门 ``` pip install checkmax-phone-utils ``` ``` from checkmax_phone_utils import normalize, validate_e164, is_mobile normalize("+7 (916) 123-45-67") # '+79161234567' normalize("8 916 123-45-67", "RU") # '+79161234567' validate_e164("+1 415 555 2671") # (True, '+14155552671') is_mobile("+79161234567") # True ``` ## 功能说明 | 函数 | 用途 | | --- | --- | | `normalize(raw, default_region)` | 将任何形如电话号码的输入转换为规范的 E.164 格式，或返回 `None`。 | | `validate_e164(raw, region)` | 返回原始输入的 `(is_valid, e164_or_none)`。 | | `is_mobile(e164)` | 如果号码是手机（或手机或固网）则返回 True。 | | `detect_region(raw)` | 返回国际号码的 ISO 3166-1 alpha-2 地区代码。 | | `clean(raw)` | 去除所有非数字字符或开头的 `+`。 | | `CheckMaxClient(api_key).check_number` | （存根）一旦 API 公开，将检查号码是否已在 MAX 上注册。 | 完整参考：请参阅 docstring —— 每个公开函数都包含示例 和边界情况说明。 ## API 参考 ### `normalize(raw: str, default_region: str = "RU") -> str | None` 安全的高层入口。清理、解析、验证并返回 规范的 `+CCNNNNNNNNNNN` 格式，如果输入不是有效的 电话号码，则返回 `None`。 ``` >>> normalize("+7 (916) 123-45-67") '+79161234567' >>> normalize("garbage") is None True ``` ### `validate_e164(raw: str, region: str = "RU") -> tuple[bool, str | None]` 返回 `(is_valid, e164)`。有效时，`e164` 为规范格式； 否则为 `None`。当你想同时保留这两个信号时非常有用。 ### `is_mobile(e164: str) -> bool` 对于 `MOBILE` 和 `FIXED_LINE_OR_MOBILE` 号码返回 True；否则返回 False， 包括无法解析输入的情况。 ### `detect_region(raw: str) -> str | None` 从国际格式的号码（带有 `+` 或 `00` 前缀）检测 ISO 地区。当输入缺少国家前缀时 返回 `None`。 ### `CheckMaxClient(api_key: str)` 即将推出的 [CheckMaxApp REST API](https://checkmaxapp.com/api) 的占位客户端。在 API 公开之前， 当前调用将返回 `{"status": "unavailable", ...}`。 ``` from checkmax_phone_utils import CheckMaxClient client = CheckMaxClient(api_key="REPLACE_WHEN_API_LIVE") client.check_number("+79161234567") # {'error': 'API 尚未公开, ...', 'status': 'unavailable', 'phone': '+79161234567'} ``` ## 示例 [`examples/`](examples) 目录包含可运行的脚本： - `examples/basic_validation.py` — 针对小型样本列表进行单号码验证。 - `examples/bulk_normalize.py` — 批量标准化包含电话号码的 CSV 文件， 输出带有 `e164` 和 `valid` 列的 CSV。 - `examples/api_client_demo.py` — CheckMaxApp 客户端的预期接口。 ## 路线图 - v0.1 — 格式验证、E.164 标准化、存根客户端（当前版本）。 - v0.2 — 异步客户端、重试机制、公开 API 发布时的结构化错误。 - v0.3 — 批量 endpoint、可选缓存、服务端速率限制感知。 - v0.4 — PyPI 上的类型存根、CLI 入口 (`checkmax phone `)。 ## 开发 ``` git clone https://github.com/abragimbaliev/checkmax-phone-utils.git cd checkmax-phone-utils pip install -e ".[dev]" pytest ``` CI 会在每次推送时针对 Python 3.10、3.11 和 3.12 运行 `pytest`。 ## 许可证 [MIT](LICENSE)。版权所有 (c) 2026 CheckMax Team。 ## 作者 CheckMax Team — `dev@checkmaxapp.com` 在寻找托管服务吗？ **[CheckMaxApp](https://checkmaxapp.com)** — 为 MAX messenger 提供电话号码验证。

标签：API客户端, Python, 安全规则引擎, 工具库, 数据校验, 无后门, 电话号码处理, 逆向工具