xiaoyi-utils 0.1.3__tar.gz

xiaoyi_utils-0.1.3/PKG-INFO

@@ -0,0 +1,68 @@
+Metadata-Version: 2.5
+Name: xiaoyi-utils
+Version: 0.1.3
+Summary: 一个用于学习 Python 公共库构建和发布的示例工程
+Requires-Python: >=3.14
+Requires-Dist: markdown>=3.5
+Requires-Dist: python-dateutil>=2.8
+Description-Content-Type: text/markdown
+
+# xiaoyi-utils
+
+一个用于学习 Python 公共库构建和发布的示例工程，提供常用工具函数。
+
+## 安装
+
+```bash
+pip install -e .
+```
+
+## 模块说明
+
+### date — 日期时间
+
+```python
+from xiaoyi_utils.date import parse_date, format_datetime, add_days, diff_days
+
+dt = parse_date("2026-09-03")
+print(format_datetime(dt, "%Y年%m月%d日"))
+print(add_days(dt, 7))
+print(diff_days("2026-01-01", "2026-09-03"))
+```
+
+### markdown — Markdown 处理
+
+```python
+from xiaoyi_utils.markdown import md_to_html, md_to_plain
+
+html = md_to_html("# Hello **world**")
+plain = md_to_plain("# Hello **world**")
+```
+
+### text — 文本处理
+
+```python
+from xiaoyi_utils.text import truncate, slugify, camel_to_snake
+
+print(truncate("这是一段很长的文本", 6))
+print(slugify("Hello World 你好"))
+print(camel_to_snake("UserProfile"))
+```
+
+### hash — 哈希摘要
+
+```python
+from xiaoyi_utils.hash import md5, sha256, file_hash
+
+print(sha256("hello"))
+print(file_hash("README.md"))
+```
+
+### json_util — JSON 工具
+
+```python
+from xiaoyi_utils.json_util import safe_loads, pretty_dumps, read_json, write_json
+
+data = safe_loads('{"name": "xiaoyi"}', default={})
+print(pretty_dumps(data))
+```

xiaoyi_utils-0.1.3/README.md

@@ -0,0 +1,59 @@
+# xiaoyi-utils
+
+一个用于学习 Python 公共库构建和发布的示例工程，提供常用工具函数。
+
+## 安装
+
+```bash
+pip install -e .
+```
+
+## 模块说明
+
+### date — 日期时间
+
+```python
+from xiaoyi_utils.date import parse_date, format_datetime, add_days, diff_days
+
+dt = parse_date("2026-09-03")
+print(format_datetime(dt, "%Y年%m月%d日"))
+print(add_days(dt, 7))
+print(diff_days("2026-01-01", "2026-09-03"))
+```
+
+### markdown — Markdown 处理
+
+```python
+from xiaoyi_utils.markdown import md_to_html, md_to_plain
+
+html = md_to_html("# Hello **world**")
+plain = md_to_plain("# Hello **world**")
+```
+
+### text — 文本处理
+
+```python
+from xiaoyi_utils.text import truncate, slugify, camel_to_snake
+
+print(truncate("这是一段很长的文本", 6))
+print(slugify("Hello World 你好"))
+print(camel_to_snake("UserProfile"))
+```
+
+### hash — 哈希摘要
+
+```python
+from xiaoyi_utils.hash import md5, sha256, file_hash
+
+print(sha256("hello"))
+print(file_hash("README.md"))
+```
+
+### json_util — JSON 工具
+
+```python
+from xiaoyi_utils.json_util import safe_loads, pretty_dumps, read_json, write_json
+
+data = safe_loads('{"name": "xiaoyi"}', default={})
+print(pretty_dumps(data))
+```

xiaoyi_utils-0.1.3/pyproject.toml

@@ -0,0 +1,22 @@
+# pyproject.toml
+
+[build-system] # 构建系统配置，指定构建工具和依赖
+requires = ["hatchling"] # 依赖的后端构建工具
+build-backend = "hatchling.build" # 使用哪个工具的哪个模块来构建项目
+
+[project] # 工程描述
+name = "xiaoyi-utils" # 发行版名称
+version = "0.1.3" # 版本号，遵循语义化版本控制
+description = "一个用于学习 Python 公共库构建和发布的示例工程" # 项目简介
+requires-python = ">=3.14" # 指定支持的 Python 版本
+readme = "README.md" # 指定项目的 README 文件路径
+dependencies = [
+    "python-dateutil>=2.8", # 依赖的第三方库，指定版本要求
+    "Markdown>=3.5", # 另一个依赖
+]
+
+[tool.hatch.build.targets.sdist] # 配置源代码分发包
+# 配置留空，表示它会默认包含所有项目文件
+
+[tool.hatch.build.targets.wheel] # 配置 wheel 包
+packages = ["src/xiaoyi_utils"] # 配置 wheel 包的构建目标，指定包含的包路径

xiaoyi_utils-0.1.3/src/xiaoyi_utils/__init__.py

@@ -0,0 +1,5 @@
+"""xiaoyi-utils：常用 Python 工具函数集合。"""
+
+__version__ = "0.1.3"
+
+__all__ = ["__version__"]

xiaoyi_utils-0.1.3/src/xiaoyi_utils/date/__init__.py

@@ -0,0 +1,23 @@
+"""日期与时间工具模块。"""
+
+from xiaoyi_utils.date.core import (
+    add_days,
+    add_months,
+    diff_days,
+    format_datetime,
+    is_weekend,
+    now,
+    parse_date,
+    today,
+)
+
+__all__ = [
+    "add_days",
+    "add_months",
+    "diff_days",
+    "format_datetime",
+    "is_weekend",
+    "now",
+    "parse_date",
+    "today",
+]

xiaoyi_utils-0.1.3/src/xiaoyi_utils/date/core.py

@@ -0,0 +1,83 @@
+"""日期与时间相关工具。"""
+
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta, timezone
+from typing import overload
+
+from dateutil import parser as date_parser
+from dateutil.relativedelta import relativedelta
+
+
+def now(tz: timezone | None = None) -> datetime:
+    """返回当前时间，默认本地时区。"""
+    return datetime.now(tz)
+
+
+def today() -> date:
+    """返回今天的日期。"""
+    return date.today()
+
+
+def parse_date(value: str | datetime | date, *, dayfirst: bool = False) -> datetime:
+    """解析多种格式的日期字符串，返回 datetime。"""
+    if isinstance(value, datetime):
+        return value
+    if isinstance(value, date):
+        return datetime(value.year, value.month, value.day)
+    return date_parser.parse(value, dayfirst=dayfirst)
+
+
+def format_datetime(
+    value: datetime | date | str,
+    fmt: str = "%Y-%m-%d %H:%M:%S",
+    *,
+    dayfirst: bool = False,
+) -> str:
+    """格式化日期/时间为字符串。"""
+    dt = parse_date(value, dayfirst=dayfirst) if isinstance(value, str) else value
+    if isinstance(dt, date) and not isinstance(dt, datetime):
+        dt = datetime(dt.year, dt.month, dt.day)
+    return dt.strftime(fmt)
+
+
+def add_days(value: datetime | date | str, days: int, *, dayfirst: bool = False) -> datetime:
+    """在指定日期上增加天数。"""
+    dt = parse_date(value, dayfirst=dayfirst) if isinstance(value, str) else value
+    if isinstance(dt, date) and not isinstance(dt, datetime):
+        dt = datetime(dt.year, dt.month, dt.day)
+    return dt + timedelta(days=days)
+
+
+def add_months(value: datetime | date | str, months: int, *, dayfirst: bool = False) -> datetime:
+    """在指定日期上增加月数。"""
+    dt = parse_date(value, dayfirst=dayfirst) if isinstance(value, str) else value
+    if isinstance(dt, date) and not isinstance(dt, datetime):
+        dt = datetime(dt.year, dt.month, dt.day)
+    return dt + relativedelta(months=months)
+
+
+@overload
+def diff_days(start: datetime | date | str, end: datetime | date | str, *, dayfirst: bool = False) -> int: ...
+
+
+def diff_days(
+    start: datetime | date | str,
+    end: datetime | date | str,
+    *,
+    dayfirst: bool = False,
+) -> int:
+    """计算两个日期之间的天数差（end - start）。"""
+    start_dt = parse_date(start, dayfirst=dayfirst) if isinstance(start, str) else start
+    end_dt = parse_date(end, dayfirst=dayfirst) if isinstance(end, str) else end
+
+    start_date = start_dt.date() if isinstance(start_dt, datetime) else start_dt
+    end_date = end_dt.date() if isinstance(end_dt, datetime) else end_dt
+    return (end_date - start_date).days
+
+
+def is_weekend(value: datetime | date | str, *, dayfirst: bool = False) -> bool:
+    """判断是否为周末（周六或周日）。"""
+    dt = parse_date(value, dayfirst=dayfirst) if isinstance(value, str) else value
+    target = dt.date() if isinstance(dt, datetime) else dt
+    return target.weekday() >= 5

xiaoyi_utils-0.1.3/src/xiaoyi_utils/hash/__init__.py

@@ -0,0 +1,5 @@
+"""哈希工具模块。"""
+
+from xiaoyi_utils.hash.core import file_hash, md5, sha256
+
+__all__ = ["file_hash", "md5", "sha256"]

xiaoyi_utils-0.1.3/src/xiaoyi_utils/hash/core.py

@@ -0,0 +1,33 @@
+"""哈希与摘要工具。"""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+
+def _digest(data: bytes, algorithm: str) -> str:
+    hasher = hashlib.new(algorithm)
+    hasher.update(data)
+    return hasher.hexdigest()
+
+
+def md5(text: str | bytes) -> str:
+    """计算 MD5 十六进制摘要。"""
+    data = text.encode("utf-8") if isinstance(text, str) else text
+    return _digest(data, "md5")
+
+
+def sha256(text: str | bytes) -> str:
+    """计算 SHA256 十六进制摘要。"""
+    data = text.encode("utf-8") if isinstance(text, str) else text
+    return _digest(data, "sha256")
+
+
+def file_hash(path: str | Path, *, algorithm: str = "sha256", chunk_size: int = 8192) -> str:
+    """计算文件的哈希值。"""
+    hasher = hashlib.new(algorithm)
+    with Path(path).open("rb") as fp:
+        while chunk := fp.read(chunk_size):
+            hasher.update(chunk)
+    return hasher.hexdigest()

xiaoyi_utils-0.1.3/src/xiaoyi_utils/json_util/__init__.py

@@ -0,0 +1,5 @@
+"""JSON 工具模块。"""
+
+from xiaoyi_utils.json_util.core import pretty_dumps, read_json, safe_loads, write_json
+
+__all__ = ["pretty_dumps", "read_json", "safe_loads", "write_json"]

xiaoyi_utils-0.1.3/src/xiaoyi_utils/json_util/core.py

@@ -0,0 +1,45 @@
+"""JSON 读写与格式化工具。"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, TypeVar
+
+T = TypeVar("T")
+
+
+def safe_loads(text: str, default: T | None = None) -> Any | T:
+    """安全解析 JSON 字符串，失败时返回 default。"""
+    try:
+        return json.loads(text)
+    except (json.JSONDecodeError, TypeError):
+        return default
+
+
+def pretty_dumps(data: Any, *, indent: int = 2, ensure_ascii: bool = False) -> str:
+    """格式化输出 JSON 字符串。"""
+    return json.dumps(data, indent=indent, ensure_ascii=ensure_ascii, default=str)
+
+
+def read_json(path: str | Path, *, default: T | None = None) -> Any | T:
+    """读取 JSON 文件，失败时返回 default。"""
+    try:
+        with Path(path).open("r", encoding="utf-8") as fp:
+            return json.load(fp)
+    except (OSError, json.JSONDecodeError):
+        return default
+
+
+def write_json(
+    path: str | Path,
+    data: Any,
+    *,
+    indent: int = 2,
+    ensure_ascii: bool = False,
+) -> None:
+    """写入 JSON 文件。"""
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with target.open("w", encoding="utf-8") as fp:
+        json.dump(data, fp, indent=indent, ensure_ascii=ensure_ascii, default=str)

xiaoyi_utils-0.1.3/src/xiaoyi_utils/markdown/__init__.py

@@ -0,0 +1,5 @@
+"""Markdown 工具模块。"""
+
+from xiaoyi_utils.markdown.core import is_markdown, md_to_html, md_to_plain
+
+__all__ = ["is_markdown", "md_to_html", "md_to_plain"]

xiaoyi_utils-0.1.3/src/xiaoyi_utils/markdown/core.py

@@ -0,0 +1,34 @@
+"""Markdown 相关工具。"""
+
+from __future__ import annotations
+
+import re
+
+import markdown
+
+
+def md_to_html(text: str, *, extensions: list[str] | None = None) -> str:
+    """将 Markdown 文本转换为 HTML。"""
+    ext = extensions or ["extra", "codehilite"]
+    return markdown.markdown(text, extensions=ext)
+
+
+def md_to_plain(text: str) -> str:
+    """去除 Markdown 标记，提取纯文本。"""
+    html = md_to_html(text, extensions=[])
+    plain = re.sub(r"<[^>]+>", "", html)
+    plain = re.sub(r"\s+", " ", plain)
+    return plain.strip()
+
+
+def is_markdown(text: str) -> bool:
+    """简单判断文本是否包含常见 Markdown 语法。"""
+    patterns = (
+        r"^#{1,6}\s",  # 标题
+        r"\*\*.+\*\*",  # 粗体
+        r"\[.+\]\(.+\)",  # 链接
+        r"^\s*[-*+]\s",  # 无序列表
+        r"^\s*\d+\.\s",  # 有序列表
+        r"```",  # 代码块
+    )
+    return any(re.search(pattern, text, re.MULTILINE) for pattern in patterns)

xiaoyi_utils-0.1.3/src/xiaoyi_utils/text/__init__.py

@@ -0,0 +1,19 @@
+"""文本处理工具模块。"""
+
+from xiaoyi_utils.text.core import (
+    camel_to_snake,
+    is_blank,
+    remove_whitespace,
+    slugify,
+    snake_to_camel,
+    truncate,
+)
+
+__all__ = [
+    "camel_to_snake",
+    "is_blank",
+    "remove_whitespace",
+    "slugify",
+    "snake_to_camel",
+    "truncate",
+]

xiaoyi_utils-0.1.3/src/xiaoyi_utils/text/core.py

@@ -0,0 +1,53 @@
+"""文本处理工具。"""
+
+from __future__ import annotations
+
+import re
+import unicodedata
+
+
+def truncate(text: str, length: int, *, suffix: str = "...") -> str:
+    """截断文本，超出部分用后缀代替。"""
+    if length <= 0:
+        return ""
+    if len(text) <= length:
+        return text
+    if len(suffix) >= length:
+        return suffix[:length]
+    return text[: length - len(suffix)] + suffix
+
+
+def slugify(text: str, *, separator: str = "-") -> str:
+    """将文本转为 URL 友好的 slug。"""
+    normalized = unicodedata.normalize("NFKD", text)
+    ascii_text = normalized.encode("ascii", "ignore").decode("ascii")
+    slug = re.sub(r"[^\w\s-]", "", ascii_text.lower())
+    slug = re.sub(r"[\s_-]+", separator, slug).strip(separator)
+    return slug
+
+
+def camel_to_snake(name: str) -> str:
+    """驼峰命名转蛇形命名。"""
+    s1 = re.sub(r"(.)([A-Z][a-z]+)", r"\1_\2", name)
+    return re.sub(r"([a-z0-9])([A-Z])", r"\1_\2", s1).lower()
+
+
+def snake_to_camel(name: str, *, upper_first: bool = False) -> str:
+    """蛇形命名转驼峰命名。"""
+    parts = name.split("_")
+    if not parts:
+        return name
+    head, *tail = parts
+    camel = head if upper_first else head.lower()
+    camel += "".join(word.capitalize() for word in tail)
+    return camel
+
+
+def remove_whitespace(text: str) -> str:
+    """移除所有空白字符。"""
+    return re.sub(r"\s+", "", text)
+
+
+def is_blank(text: str | None) -> bool:
+    """判断文本是否为空或仅含空白。"""
+    return text is None or not text.strip()