py-handy

A practical and convenient python toolset

Usage

install

pip3 install -U pyhandytools

module

• file
• env
• logger
• crypto
• calc
• req
• cleaner

Modules

1. FileUtils - 文件操作工具

提供JSON/JSONL文件读写、目录管理、图片编解码等功能。

JSON操作

from pyhandytools.file import FileUtils

# 写入JSON文件
data = {"name": "test", "value": 123}
FileUtils.write2json("data.json", data)

# 读取JSON文件
loaded_data = FileUtils.load_json("data.json")
print(loaded_data)

JSONL操作

from pyhandytools.file import FileUtils

# 写入JSONL文件
data_list = [
    {"id": 1, "name": "Alice"},
    {"id": 2, "name": "Bob"}
]
FileUtils.write2jsonl("data.jsonl", data_list)

# 读取JSONL文件
loaded_data = FileUtils.load_jsonl("data.jsonl")
print(loaded_data)

目录操作

from pyhandytools.file import FileUtils

# 检查并创建目录
FileUtils.check_dir_path("./data/output")

# 统计目录中的文件数量
file_count = FileUtils.count_file_number("./data")
print(f"Total files: {file_count}")

图片编解码

from pyhandytools.file import ImageUtil

# 图片转base64
base64_str = ImageUtil.base64_encode_img("image.png")
print(base64_str)

# base64转图片
ImageUtil.base64_decode_img(base64_str, "decoded_image.png")

其他功能

from pyhandytools.file import FileUtils

# 美化JSON输出
data = {"key": "value"}
pretty_json = FileUtils.pretty_json(data)
print(pretty_json)

# 复制并删除原文件
FileUtils.cp_and_rm("old_file.txt", "new_file.txt")

---

2. EnvUtils - 环境工具

提供环境初始化和平台识别功能。

from pyhandytools.env import EnvUtils

# 初始化环境（过滤警告信息）
EnvUtils.init_env()

# 获取当前平台
platform = EnvUtils.get_platform()
print(f"Current platform: {platform}")
# 输出: linux, win32, 或 darwin

---

3. LoggerUtils - 日志工具

提供灵活的日志配置和管理功能。

基础使用

from pyhandytools.logger import LoggerUtils

# 初始化日志器
logger = LoggerUtils.new_generic_logger(
    service_name="my_service",
    logger_path="./logs/app.log",
    level="DEBUG"
)

# 使用日志
logger.info("This is an info message")
logger.debug("Debug information")
logger.warning("Warning message")
logger.error("Error occurred")

高级配置

from pyhandytools.logger import LoggerUtils

# 自定义日志配置
logger = LoggerUtils.init_logger(
    logger_path="./logs/custom.log",
    service_name="custom_service",
    level="INFO",
    rotation="100 MB",
    retention="30 days",
    enqueue=True,
    version="1.0.0"
)

logger.info("Custom logger initialized")

自定义日志格式

from pyhandytools.logger import LoggerUtils

custom_format = "{time:YYYY-MM-DD HH:mm:ss} | {level} | {message}"

logger = LoggerUtils.init_logger(
    logger_path="./logs/formatted.log",
    service_name="formatted_service",
    log_format=custom_format
)

logger.info("Formatted log message")

---

4. CryptoUtils - 加密工具

提供AES加密解密功能。

from pyhandytools.crypto import CryptoUtils

# 初始化加密工具（密钥会自动填充/截断到32字节）
crypto = CryptoUtils("my-secret-key-32-bytes")

# 加密
plaintext = "Hello, World!"
encrypted = crypto.encrypt(plaintext)
print(f"Encrypted: {encrypted}")

# 解密
decrypted = crypto.decrypt(encrypted)
print(f"Decrypted: {decrypted}")
# 输出: Hello, World!

# 支持Unicode字符
chinese_text = "你好，世界！"
encrypted_cn = crypto.encrypt(chinese_text)
decrypted_cn = crypto.decrypt(encrypted_cn)
print(decrypted_cn)

---

5. calc - 计算工具

提供真正的四舍五入功能。

from pyhandytools.calc import true_round

# 四舍五入到整数
print(true_round(3.4))    # 3
print(true_round(3.5))    # 4
print(true_round(3.6))    # 4

# 四舍五入到指定小数位
print(true_round(3.14159, 2))   # 3.14
print(true_round(3.14159, 3))   # 3.142
print(true_round(2.55, 1))     # 2.6

# 边界情况
print(true_round(0.5, 0))       # 1
print(true_round(0.4999, 0))    # 0

---

6. AsyncApiUtil - 异步请求工具

提供异步HTTP请求功能，支持并发控制。

基础使用

import asyncio
from pyhandytools.req import AsyncApiUtil

async def main():
    # POST请求
    url = "https://api.example.com/data"
    payload = {"key": "value"}
    
    response = await AsyncApiUtil.post(url, payload=payload)
    print(response)
    
    # GET请求
    params = {"id": 123}
    response = await AsyncApiUtil.get(url, params=params)
    print(response)

asyncio.run(main())

并发控制

import asyncio
from pyhandytools.req import AsyncApiUtil

async def fetch_data():
    url = "https://api.example.com/data"
    data_list = [{"prompt": f"item_{i}", "id": i} for i in range(100)]
    
    # 创建并发任务，限制并发数为10
    tasks = [
        AsyncApiUtil.req_post(url, data=item, workers=10)
        for item in data_list
    ]
    
    # 执行所有任务
    responses = await asyncio.gather(*tasks)
    
    for response in responses:
        print(response)

asyncio.run(fetch_data())

自定义配置

import asyncio
from pyhandytools.req import AsyncApiUtil

async def main():
    url = "https://api.example.com/data"
    
    # 自定义headers
    custom_headers = {
        "Authorization": "Bearer token123",
        "Content-Type": "application/json"
    }
    
    # 带超时的POST请求
    response = await AsyncApiUtil.post(
        url,
        payload={"data": "test"},
        headers=custom_headers,
        timeout=30.0,
        verify=False  # 不验证SSL证书
    )
    print(response)

asyncio.run(main())

---

7. ParserUtil - HTML清理工具

提供HTML标签清理和纯文本提取功能。

from pyhandytools.cleaner import ParserUtil

# 清理HTML，提取纯文本
html_content = """
<div>
    <h1>Title</h1>
    <p>Hello <strong>World</strong></p>
    <script>alert('test')</script>
    <style>.test{color:red}</style>
</div>
"""

clean_text = ParserUtil.clear_text(html_content)
print(clean_text)
# 输出: TitleHello World

# 删除额外的换行符或空格
text = "Hello\n\n\nWorld"
cleaned = ParserUtil.delete_extra_flag(text, "\n")
print(cleaned)
# 输出: Hello\nWorld

---

Requirements

• Python >= 3.8
• loguru
• aiohttp
• pycryptodome
• beautifulsoup4
• lxml
• lxml_html_clean

Python Version Support

• Python 3.8
• Python 3.9
• Python 3.10
• Python 3.11
• Python 3.12

UT

# 运行所有测试
python -m unittest discover -s ut -v

# 运行单个测试文件
python -m unittest ut.test_calc -v

License

MIT License

PYPI url

• https://pypi.org/project/pyhandytools/

Repository

• https://github.com/JimouChen/py-handy