yiwen-package 0.1.0

一个简单实用的 Python 工具包

yiwen-package

一个简单实用的 Python 工具包，提供常用的字符串、列表、文件和时间处理工具函数。

安装

pip install yiwen-package

功能特性

• 字符串工具 - 命名转换、截断、前缀/后缀处理
• 列表工具 - 分块、扁平化、去重、分组
• 文件工具 - JSON 读写、目录管理、文件大小格式化
• 时间工具 - 时间戳、日期格式化、相对时间

快速开始

from yiwen_package import (
    camel_to_snake,
    chunk,
    read_json,
    format_datetime,
    time_ago
)

# 字符串工具
camel_to_snake("MyClassName")  # "my_class_name"

# 列表工具
chunk([1, 2, 3, 4, 5], 2)  # [[1, 2], [3, 4], [5]]

# 文件工具
data = read_json("config.json")

# 时间工具
from datetime import datetime
format_datetime(datetime.now())  # "2023-11-06 14:30:45"

API 文档

字符串工具 (string_utils)

is_empty(s: str) -> bool

检查字符串是否为空或只包含空白字符。

is_empty("")        # True
is_empty("   ")     # True
is_empty("hello")   # False

truncate(s: str, length: int, suffix: str = '...') -> str

截断字符串到指定长度。

truncate("hello world", 8)              # "hello..."
truncate("hello world", 8, suffix=">>") # "hello >>"

remove_prefix(s: str, prefix: str) -> str

移除字符串的前缀。

remove_prefix("hello_world", "hello_")  # "world"

remove_suffix(s: str, suffix: str) -> str

移除字符串的后缀。

remove_suffix("hello_world", "_world")  # "hello"

camel_to_snake(s: str) -> str

将驼峰命名转换为下划线命名。

camel_to_snake("CamelCase")   # "camel_case"
camel_to_snake("myClassName") # "my_class_name"

snake_to_camel(s: str, capitalize_first: bool = False) -> str

将下划线命名转换为驼峰命名。

snake_to_camel("snake_case")                        # "snakeCase"
snake_to_camel("snake_case", capitalize_first=True) # "SnakeCase"

列表工具 (list_utils)

chunk(lst: List[T], size: int) -> List[List[T]]

将列表分割成指定大小的块。

chunk([1, 2, 3, 4, 5], 2)  # [[1, 2], [3, 4], [5]]

flatten(nested_list: List[Any]) -> List[Any]

展平嵌套列表。

flatten([[1, 2], [3, [4, 5]]])  # [1, 2, 3, 4, 5]

unique(lst: List[T], key=None) -> List[T]

去重，保持原始顺序。

unique([1, 2, 2, 3, 1])  # [1, 2, 3]

# 使用 key 函数
data = [{'id': 1, 'name': 'a'}, {'id': 2, 'name': 'b'}, {'id': 1, 'name': 'c'}]
unique(data, key=lambda x: x['id'])  # [{'id': 1, 'name': 'a'}, {'id': 2, 'name': 'b'}]

group_by(items: Iterable[T], key_func) -> dict

按指定函数分组。

group_by([1, 2, 3, 4, 5, 6], lambda x: x % 2)
# {0: [2, 4, 6], 1: [1, 3, 5]}

文件工具 (file_utils)

read_json(file_path: Union[str, Path]) -> Any

读取 JSON 文件。

data = read_json("config.json")

write_json(file_path: Union[str, Path], data: Any, indent: int = 2) -> None

写入 JSON 文件。

write_json("output.json", {"key": "value"})

ensure_dir(dir_path: Union[str, Path]) -> Path

确保目录存在，如果不存在则创建。

ensure_dir("data/output")  # 创建 data/output 目录

get_file_size(file_path: Union[str, Path]) -> int

获取文件大小（字节）。

get_file_size("file.txt")  # 1024

format_file_size(size_bytes: int) -> str

格式化文件大小为人类可读格式。

format_file_size(1024)           # "1.00 KB"
format_file_size(1024 * 1024)    # "1.00 MB"

时间工具 (time_utils)

now_timestamp() -> int

获取当前时间戳（秒）。

now_timestamp()  # 1699200000

now_timestamp_ms() -> int

获取当前时间戳（毫秒）。

now_timestamp_ms()  # 1699200000000

format_datetime(dt: Optional[datetime] = None, fmt: str = '%Y-%m-%d %H:%M:%S') -> str

格式化日期时间。

from datetime import datetime
format_datetime(datetime(2023, 11, 6, 14, 30, 45))  # "2023-11-06 14:30:45"
format_datetime(fmt='%Y/%m/%d')  # "2023/11/06"

parse_datetime(date_str: str, fmt: str = '%Y-%m-%d %H:%M:%S') -> datetime

解析日期时间字符串。

parse_datetime("2023-11-06 14:30:45")  # datetime(2023, 11, 6, 14, 30, 45)

time_ago(dt: datetime) -> str

返回相对时间描述。

from datetime import datetime, timedelta
dt = datetime.now() - timedelta(hours=3)
time_ago(dt)  # "3小时前"

add_days(dt: datetime, days: int) -> datetime

增加或减少天数。

from datetime import datetime
dt = datetime(2023, 11, 6)
add_days(dt, 5)   # datetime(2023, 11, 11)
add_days(dt, -5)  # datetime(2023, 11, 1)

开发

安装开发依赖

pip install -e ".[dev]"

运行测试

pytest

查看测试覆盖率

pytest --cov=yiwen_package --cov-report=html

许可证

MIT License - 详见 LICENSE 文件

作者

yw.hao ([e-mail])