lantool 0.1.0__py3-none-any.whl

lantool/__init__.py

@@ -0,0 +1,261 @@
+"""lantool —— 轻量实用的 Python 通用工具库。
+
+零依赖核心 + 按需扩展（可选依赖缺失时给出友好安装提示）；
+所有公共 API 均可从包顶层直接导入，例如：
+
+    from lantool import base64_encode, sha256, now_str
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _pkg_version
+
+try:
+    __version__ = _pkg_version("lantool")
+except PackageNotFoundError:  # 源码拷贝未安装场景
+    __version__ = "0.0.0.dev0"
+
+# 导出名 → 模块路径映射（PEP 562 懒加载：按需 import，保证 import lantool 零开销）
+_EXPORTS: dict[str, str] = {
+    # errors —— 统一异常体系
+    "LanToolError": "lantool.errors",
+    "EncodeError": "lantool.errors",
+    "ParseError": "lantool.errors",
+    "ValidationError": "lantool.errors",
+    "CryptoError": "lantool.errors",
+    "OptionalDependencyError": "lantool.errors",
+    # encoding —— 编解码
+    "base64_encode": "lantool.encoding",
+    "base64_decode": "lantool.encoding",
+    "base64_encode_bytes": "lantool.encoding",
+    "base64_decode_bytes": "lantool.encoding",
+    "url_encode": "lantool.encoding",
+    "url_decode": "lantool.encoding",
+    "hex_encode": "lantool.encoding",
+    "hex_decode": "lantool.encoding",
+    "unicode_encode": "lantool.encoding",
+    "unicode_decode": "lantool.encoding",
+    "morse_encode": "lantool.encoding",
+    "morse_decode": "lantool.encoding",
+    "convert_base": "lantool.encoding",
+    "image_to_base64": "lantool.encoding",
+    "image_from_base64": "lantool.encoding",
+    # hashing —— 哈希
+    "SUPPORTED_ALGORITHMS": "lantool.hashing",
+    "md5": "lantool.hashing",
+    "sha1": "lantool.hashing",
+    "sha256": "lantool.hashing",
+    "sha512": "lantool.hashing",
+    "hash_text": "lantool.hashing",
+    "hash_file": "lantool.hashing",
+    "hmac_digest": "lantool.hashing",
+    "crc32": "lantool.hashing",
+    # bytesize —— 字节单位
+    "convert_size": "lantool.bytesize",
+    "human_size": "lantool.bytesize",
+    "parse_size": "lantool.bytesize",
+    # ids —— 唯一标识
+    "uuid1": "lantool.ids",
+    "uuid3": "lantool.ids",
+    "uuid4": "lantool.ids",
+    "uuid5": "lantool.ids",
+    "uuid7": "lantool.ids",
+    "short_id": "lantool.ids",
+    "nano_id": "lantool.ids",
+    # password —— 密码与随机串
+    "random_password": "lantool.password",
+    "random_string": "lantool.password",
+    "password_strength": "lantool.password",
+    # convert —— 类型安全转换
+    "to_int": "lantool.convert",
+    "to_float": "lantool.convert",
+    "to_bool": "lantool.convert",
+    "to_str": "lantool.convert",
+    "to_datetime": "lantool.convert",
+    # times —— 时间
+    "DEFAULT_DATETIME_FMT": "lantool.times",
+    "timestamp": "lantool.times",
+    "now": "lantool.times",
+    "now_utc": "lantool.times",
+    "now_str": "lantool.times",
+    "now_formats": "lantool.times",
+    "from_timestamp": "lantool.times",
+    "to_timestamp": "lantool.times",
+    "timestamp_to_str": "lantool.times",
+    "str_to_timestamp": "lantool.times",
+    "human_duration": "lantool.times",
+    # text —— 文本
+    "to_snake": "lantool.text",
+    "to_camel": "lantool.text",
+    "to_pascal": "lantool.text",
+    "to_kebab": "lantool.text",
+    "to_upper": "lantool.text",
+    "to_lower": "lantool.text",
+    "invert_case": "lantool.text",
+    "alternate_case": "lantool.text",
+    "capitalize_words": "lantool.text",
+    "count_chars": "lantool.text",
+    "natural_sort": "lantool.text",
+    "mask": "lantool.text",
+    "truncate": "lantool.text",
+    "java_fields": "lantool.text",
+    # jsonx —— JSON
+    "dumps": "lantool.jsonx",
+    "loads": "lantool.jsonx",
+    "pretty": "lantool.jsonx",
+    "compact": "lantool.jsonx",
+    "validate": "lantool.jsonx",
+    # xmlix —— XML
+    "format_xml": "lantool.xmlix",
+    "compact_xml": "lantool.xmlix",
+    "validate_xml": "lantool.xmlix",
+    "escape_xml": "lantool.xmlix",
+    "unescape_xml": "lantool.xmlix",
+    # diffx —— 文本差异
+    "unified_diff": "lantool.diffx",
+    "ndiff": "lantool.diffx",
+    "diff_ratio": "lantool.diffx",
+    "html_diff": "lantool.diffx",
+    # formatx —— 数字格式化
+    "format_number": "lantool.formatx",
+    "format_currency": "lantool.formatx",
+    "format_percent": "lantool.formatx",
+    # validator —— 校验
+    "is_email": "lantool.validator",
+    "is_phone_cn": "lantool.validator",
+    "is_ipv4": "lantool.validator",
+    "is_ipv6": "lantool.validator",
+    "is_ip": "lantool.validator",
+    "is_url": "lantool.validator",
+    "is_id_card_cn": "lantool.validator",
+    # collx —— 集合工具
+    "deep_merge": "lantool.collx",
+    "chunk": "lantool.collx",
+    "flatten": "lantool.collx",
+    "unique": "lantool.collx",
+    "unique_by": "lantool.collx",
+    # retry —— 重试
+    "retry": "lantool.retryx",
+    # cronx —— Cron
+    "cron_parse": "lantool.cronx",
+    "cron_next_run": "lantool.cronx",
+    "cron_describe": "lantool.cronx",
+    # misc —— 杂项工具
+    "bmi": "lantool.misc",
+    "bmi_info": "lantool.misc",
+    "curl": "lantool.misc",
+    "regex_test": "lantool.misc",
+    # webdata —— Web 数据
+    "HTTP_STATUS_CODES": "lantool.webdata",
+    "CONTENT_TYPES": "lantool.webdata",
+    "USER_AGENTS": "lantool.webdata",
+    "http_status": "lantool.webdata",
+    "http_status_description": "lantool.webdata",
+    "search_status": "lantool.webdata",
+    "content_type": "lantool.webdata",
+    "random_user_agent": "lantool.webdata",
+    "parse_user_agent": "lantool.webdata",
+    # chardata —— 字符数据
+    "HTML_ENTITIES": "lantool.chardata",
+    "EMOJI_CATEGORIES": "lantool.chardata",
+    "ascii_table": "lantool.chardata",
+    "ascii_info": "lantool.chardata",
+    "html_escape": "lantool.chardata",
+    "html_unescape": "lantool.chardata",
+    "emoji_list": "lantool.chardata",
+    "random_emoji": "lantool.chardata",
+    # decorators —— 通用装饰器
+    "timing": "lantool.decorators",
+    "suppress_errors": "lantool.decorators",
+    "rate_limit": "lantool.decorators",
+    "module_block": "lantool.decorators",
+    # files —— 文件工具
+    "safe_read_text": "lantool.files",
+    "safe_write_text": "lantool.files",
+    "append_text": "lantool.files",
+    "ensure_dir": "lantool.files",
+    "mime_type": "lantool.files",
+    "file_info": "lantool.files",
+    "temp_dir": "lantool.files",
+    # env —— 环境变量
+    "get_env": "lantool.env",
+    "get_env_int": "lantool.env",
+    "get_env_float": "lantool.env",
+    "get_env_bool": "lantool.env",
+    "get_env_json": "lantool.env",
+    "get_env_list": "lantool.env",
+    # log —— 日志工厂
+    "DEFAULT_LOG_FMT": "lantool.log",
+    "LevelFilter": "lantool.log",
+    "DailySizeRotatingHandler": "lantool.log",
+    "get_logger": "lantool.log",
+    # security —— 加解密（可选 [security]）
+    "aes_encrypt": "lantool.security",
+    "aes_decrypt": "lantool.security",
+    "des_encrypt": "lantool.security",
+    "des_decrypt": "lantool.security",
+    "des3_encrypt": "lantool.security",
+    "des3_decrypt": "lantool.security",
+    "rsa_generate_keys": "lantool.security",
+    "rsa_encrypt": "lantool.security",
+    "rsa_decrypt": "lantool.security",
+    "rsa_sign": "lantool.security",
+    "rsa_verify": "lantool.security",
+    "bcrypt_hash": "lantool.security",
+    "bcrypt_verify": "lantool.security",
+    # jwtx —— JWT（可选 [jwt]）
+    "jwt_encode": "lantool.jwtx",
+    "jwt_decode": "lantool.jwtx",
+    # yamlix —— YAML（可选 [yaml]）
+    "json_to_yaml": "lantool.yamlix",
+    "yaml_to_json": "lantool.yamlix",
+    "yaml_load": "lantool.yamlix",
+    # imagex —— 图片（可选 [image]）
+    "compress_image": "lantool.imagex",
+    "watermark_text": "lantool.imagex",
+    "watermark_image": "lantool.imagex",
+    "make_favicon": "lantool.imagex",
+    # qrcodex —— 二维码（可选 [qr]）
+    "qrcode_png": "lantool.qrcodex",
+    "qrcode_svg": "lantool.qrcodex",
+    # barcodex —— 条形码（可选 [barcode]）
+    "barcode_png": "lantool.barcodex",
+    "barcode_svg": "lantool.barcodex",
+    # pdfx —— PDF（可选 [pdf]）
+    "pdf_info": "lantool.pdfx",
+    "pdf_split": "lantool.pdfx",
+    "pdf_extract_pages": "lantool.pdfx",
+    "pdf_merge": "lantool.pdfx",
+    "pdf_watermark": "lantool.pdfx",
+    "images_to_pdf": "lantool.pdfx",
+}
+
+__all__ = list(_EXPORTS)
+
+
+def __getattr__(name: str) -> object:
+    """按需加载导出对象（PEP 562 模块级 __getattr__）。
+
+    首次访问后写入模块全局命名空间缓存，后续访问零查找开销。
+
+    Args:
+        name: 导出对象名称。
+
+    Returns:
+        目标模块中的对应对象。
+
+    Raises:
+        AttributeError: 名称不在导出映射中。
+    """
+    module_path = _EXPORTS.get(name)
+    if module_path is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    from importlib import import_module
+
+    value = getattr(import_module(module_path), name)
+    globals()[name] = value  # 缓存：后续访问直接命中，不再经过本函数
+    return value
+
+
+def __dir__() -> list[str]:
+    """返回模块属性与全部可导出名称（支持 dir(lantool) 与 IDE 补全）。"""
+    return sorted(set(globals()) | set(__all__))

lantool/__main__.py

@@ -0,0 +1,70 @@
+"""lantool 自检命令：python -m lantool —— 输出版本、Python 环境与各可选依赖可用性。"""
+
+import codecs
+import sys
+from contextlib import suppress
+
+
+def _ensure_utf8_stdio() -> None:
+    """管道/重定向场景下将标准输出/错误流统一为 UTF-8。
+
+    Windows 的 Python 在管道下默认跟随系统区域（中文系统为 GBK），中文输出到
+    UTF-8 终端或文件会乱码。交互终端（isatty）的编码与终端显示匹配，保持原样。
+    """
+    for stream in (sys.stdout, sys.stderr):
+        if stream is None:
+            continue
+        isatty = getattr(stream, "isatty", None)
+        if isatty is not None and isatty():
+            continue
+        encoding = getattr(stream, "encoding", None)
+        if not encoding:
+            continue
+        try:
+            if codecs.lookup(encoding).name == "utf-8":
+                continue
+        except LookupError:
+            pass  # 未知编码名：交由 reconfigure 尝试，失败再保持原样
+        # 嵌入式解释器等非标准流无法重配时保持原样
+        with suppress(AttributeError, OSError, ValueError):
+            stream.reconfigure(encoding="utf-8")
+
+
+# CLI 执行路径先于包内导入统一输出编码，导入失败的回溯信息同样保持可读
+if __name__ == "__main__":
+    _ensure_utf8_stdio()
+
+from importlib.util import find_spec  # noqa: E402
+
+from lantool._optional import EXTRA_MODULES  # noqa: E402
+
+
+def _check_extra(extra: str) -> bool:
+    """检测 extras 的全部依赖模块是否已安装。"""
+    return all(find_spec(module) is not None for module in EXTRA_MODULES[extra])
+
+
+def main() -> int:
+    """打印环境自检报告（作为库函数调用时不对进程标准流做任何改动）。"""
+    import lantool
+
+    print("=" * 52)
+    print("lantool 自检报告")
+    print("=" * 52)
+    print(f"lantool 版本 : {lantool.__version__}")
+    print(f"Python 版本  : {sys.version.split()[0]} ({sys.platform})")
+    print(f"安装位置     : {lantool.__file__}")
+    print("-" * 52)
+    print("可选功能（extras）可用性：")
+    for extra in sorted(EXTRA_MODULES):
+        if _check_extra(extra):
+            print(f"  [{extra:<8}] [OK] 可用")
+        else:
+            print(f'  [{extra:<8}] [--] 未安装（pip install "lantool[{extra}]"）')
+    print("-" * 52)
+    print("核心功能（纯标准库）始终可用 [OK]")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())