py-simple-wrap 🚀

让 Python 读起来像普通的英语。

py-simple-wrap 是一个面向初学者的 Python 封装包，旨在帮助初学者和开发者使用简单、直观的函数完成常见任务。

本项目的目标是消除记忆复杂语法或编写重复样板代码的需要，让 Python 对每个人来说都更易于上手且更有趣。

如果你符合以下情况，你会爱上 py-simple-wrap：

前后对比

😰 传统方式

import requests
from bs4 import BeautifulSoup

try:
    response = requests.get('https://github.com', timeout=10)
    response.raise_for_status()
    page = BeautifulSoup(response.content, 'html.parser')
    title = page.title.string
except Exception as e:
    print("The site is down or address is invalid.")

😎 py-simple-wrap 方式

from py_simple import get_page_title

print(get_page_title("https://github.com"))

🛠️ 安装

pip install py-simple-wrap

from py_simple import make_blank_file, miles_to_km, is_valid_email

make_blank_file("notes.txt")
print(miles_to_km(26.2))                    # 42.16...
print(is_valid_email("hello@example.com"))  # True

完整教程见 QUICKSTART.md，或浏览完整的 文档站点。

⭐ 如果 py-simple-wrap 让你更省事了

请考虑给它一个 star —— 这有助于其他初学者找到它，也真的能让我开心一整天。如果你希望存在某个函数，fork 它并添加它；这个项目之所以发展起来，正是因为其他人也这样做了。下面每个模块都始于此处，除了 easy_strings，它来自一位贡献者。

🛠️ 模块菜单

py-simple-wrap 提供旨在简化常见 Python 任务的简单模块。

📂 简易文件管理器

点击展开 — 无需 os 样板代码

的文件操作

功能	作用
`make_blank_file("notes", "txt")`	创建一个空文件
`is_file_there("notes.txt")`	检查文件是否存在
`add_a_line("notes.txt", "hello!")`	向文件追加一行
`read_file_to_list("notes.txt")`	将行读取到列表中
`remove_file("notes.txt")`	删除文件
`rename_file("old.txt", "new.txt")`	重命名文件
`copy_file("src.txt", "dst.txt")`	复制文件
`list_files()` / `list_files("txt")`	列出文件，可选按扩展名

🕰️ Easy Date Formatter

点击展开 — 无需记忆 strftime 代码即可显示可读日期

以任意格式获取当前日期：

函数	示例输出
`get_pretty_date()`	`Friday, July 31, 2026`
`dd_mm_yyyy()`	`31-07-2026`
`mm_dd_yyyy()`	`07-31-2026`
`slash_dd_mm_yyyy()`	`31/07/2026`
`slash_mm_dd_yyyy()`	`07/31/2026`

需要过去或未来的日期？ 在上述任何函数中添加 past_ 或 future_ 并传入天数：

模式	示例
`past_<format>(7)`	`past_pretty_date(7)` → 一周前
`future_<format>(30)`	`future_dd_mm_yyyy(30)` → 30 天后

另可用： list_available_formats() 查看所有支持的格式名称。

🔢 简单数字

点击展开 — 无需心算即可进行数字检查和计算

功能	作用	示例
`is_even(n)`	检查一个数是否为偶数	`is_even(90)` → `True`
`is_odd(n)`	检查一个数是否为奇数	`is_odd(67)` → `True`
`is_positive(n)`	检查一个数是否为正数	`is_positive(90)` → `True`
`is_negative(n)`	检查一个数是否为负数	`is_negative(-10)` → `True`
`is_prime(n)`	检查一个数是否为质数	`is_prime(2)` → `True`
`is_evenly_divisible(n, d)`	检查 `n` 是否能被 `d` 整除	`is_evenly_divisible(90, 9)` → `True`
`average(nums)`	列表的平均值，四舍五入到小数点后两位	`average([1.5, 2, 3])` → `2.17`
`percentage_of(n, p)`	获取一个数的百分比	`percentage_of(100, 0.5)` → `50.0`
`round_to_nearest(n, m)`	四舍五入到最近的倍数	`round_to_nearest(23, 5)` → `25.0`
`greatest_common_divisor(a, b)`	求两个数的最大公约数	`greatest_common_divisor(12, 18)` → `6`
`clamp(n, min, max)`	将数字限制在指定范围内	`clamp(15, 0, 10)` → `10`

📋 Easy Lists

点击展开 — 保持代码简短且可读的列表辅助工具

功能	作用	示例
`unique_items(items)`	去除重复项，保留顺序	`unique_items([1, 2, 2, 3])` → `[1, 2, 3]`
`find_duplicates(items)`	查找出现多次的项	`find_duplicates([1, 2, 2, 3, 3, 3])` → `[2, 3]`
`chunk_list(items, size)`	将列表拆分为更小的列表	`chunk_list([1, 2, 3, 4, 5], 2)` → `[[1, 2], [3, 4], [5]]`
`flatten_list(items)`	将嵌套列表展平一层	`flatten_list([[1, 2], [3]])` → `[1, 2, 3]`
`most_common_item(items)`	查找出现频率最高的项	`most_common_item([1, 1, 2])` → `1`
`rotate_list(items, steps)`	将项向右旋转	`rotate_list([1, 2, 3], 1)` → `[3, 1, 2]`
`merge_lists(list_a, list_b)`	合并两个列表	`merge_lists([1, 2], [3, 4])` → `[1, 2, 3, 4]`
`alternate_lists(list_a, list_b)`	交替取项合并列表	`alternate_lists([1, 2], [3, 4])` → `[1, 3, 2, 4]`
`sum_all(items)`	求和，包括嵌套列表中的数字	`sum_all([1, [2, 3], 4])` → `10`
`sort_numbers(items)`	将数字从小到大排序	`sort_numbers([3, 1, 2])` → `[1, 2, 3]`
`sort_words(items)`	按字母顺序排序单词，忽略大小写	`sort_words(["banana", "Apple"])` → `["Apple", "banana"]`

🔤 Easy Strings

点击展开 — 读起来像英语的字符串操作

功能	作用	示例
`remove_extra_spaces(text)`	去除开头、结尾及连续空格	`remove_extra_spaces(" hello world ")` → `"hello world"`
`to_snake_case(text)`	转换为 snake_case	`to_snake_case("Hello World")` → `"hello_world"`
`to_kebab_case(text)`	转换为 kebab-case	`to_kebab_case("Hello World")` → `"hello-world"`
`is_palindrome(text)`	检查文本是否正读反读相同	`is_palindrome("Never odd or even")` → `True`
`is_alphanumeric(text)`	检查文本是否仅包含字母和数字	`is_alphanumeric("Something123")` → `True`
`count_words(text)`	统计单词数量	`count_words("Hello world! How are you?")` → `5`

✂️ Easy Text

点击展开 — 读起来像英语的文本格式化工具

|------------------------------|---------------------------------------------|---------------------------------------------------------------| | 功能 | 作用 | 示例 | | truncate(text, length) | 缩短文本并添加省略号 | truncate("Hello world!", 5) → "Hello…" | | remove_punctuation(text) | 去除标点符号，保留字母和数字 | remove_punctuation("Hello, world!") → "Hello world" | | reverse_words(text) | 反转单词顺序 | reverse_words("Hello world") → "world Hello" | | capitalize_title(text) | 将每个单词的首字母大写 | capitalize_title("the great gatsby") → "The Great Gatsby" | | count_letters(text) | 统计字母数量 | count_letters("Hello 123!") → 5 | | count_digits(text) | 统计数字数量 | count_digits("Hello 123!") → 3 | | mask_part(text, visible=4) | 用星号隐藏部分文本 | mask_part("1234567890", 4) → "1234 ******" | | pluralize(word, count) | 获取单数或复数形式 | pluralize("cat", 3) → "cats" | | extract_hashtags(text) | 提取不带 # 符号的话题标签 | extract_hashtags("#python rocks") → ["python"] | | word_frequency(text) | 统计每个单词出现的频率 | word_frequency("the cat and the dog") → {"the": 2, ...} |

🔄 Easy Converter

点击展开 — 无需记忆公式的单位换算

时间

函数	示例
`seconds_to_hh_mm_ss(3665)`	`"01:01:05"`
`hh_mm_ss_to_seconds(1, 1, 1)`	`3661`

距离与长度

函数	示例
`km_to_mile(100)`	`62.13`
`miles_to_km(100)`	`160.93`
`meters_to_feet(100)`	`328.08`
`feet_to_meters(328.08)`	`100.0`
`cm_to_inches(100)`	`39.37`
`inches_to_cm(39.37)`	`100.0`

重量

函数	示例
`kg_to_lb(5)`	`11.02`
`lb_to_kg(110.23)`	`50.0`

温度

函数	示例
`celsius_to_fahrenheit(25)`	`77.0`
`fahrenheit_to_celsius(104)`	`40.0`

体积

函数	示例
`fluid_oz_to_ml(1, standard='us')`	`29.6`
`fluid_oz_to_ml(1, standard='uk')`	`28.4`
`ml_to_fluid_oz(1, standard='us')`	`0.03`
`ml_to_fluid_oz(1, standard='uk')`	`0.04`

面积

函数	示例
`sq_meters_to_sq_feet(10)`	`107.64`
`sq_feet_to_sq_meters(107.64)`	`10.0`

速度

函数	示例
`mph_to_kph(0.621371)`	`1.0`
`kph_to_mph(1.60934)`	`1.0`

✅ Easy Validator

点击展开 — 无需记忆正则表达式即可进行输入验证

功能	检查内容	示例
`is_valid_email(str)`	有效的电子邮件格式	`is_valid_email("hello@world.com")` → `True`
`is_valid_username(str)`	仅包含字母、数字和下划线	`is_valid_username("user_name")` → `True`
`is_valid_url(str)`	包含 http、https 或 www 的 URL	`is_valid_url("www.google.com")` → `True`
`is_valid_zipcode(int)`	5 位美国邮政编码	`is_valid_zipcode(12345)` → `True`
`is_password_secure(str)`	8 个以上字符，包含大写、小写、数字、特殊字符，无重复	`is_password_secure("1andkrf!AG5")` → `True`

🌐 Easy Web

点击展开 — 无需 requests/BS4 样板代码即可进行网页抓取和检查

功能	作用	示例
`is_page_up(url)`	检查站点是否返回 200	`is_page_up("https://github.com")` → `True`
`get_page_title(url)`	获取页面标题	`get_page_title("https://github.com")` → `"GitHub · ..."`
`get_page_content(url)`	获取格式化的 HTML	`get_page_content("https://google.com")`
`count_links(url)`	统计页面上的链接数量	`count_links("https://github.com")` → `144`
`get_link_list(url)`	以列表形式获取所有链接	`get_link_list("https://github.com")` → `[...]`
`count_tags(url, tag)`	统计指定类型的标签数量 (例如 `'a'`, `'img'`)	`count_tags("https://github.com", "img")` → `12`
`get_tag_list(url, tag)`	从每个匹配的标签中获取有用信息	`get_tag_list("https://github.com", "img")` → `[...]`
`print_allowed_tags()`	打印支持的标签 → 属性映射	`print_allowed_tags()` → `{'a': 'href', 'img': 'src'}`
`get_meta_description(url)`	获取所有 meta 标签的内容	`get_meta_description("https://github.com")` → `[...]`
`get_all_headers(url)`	从所有 `<header>` 标签中获取文本	`get_all_headers("https://github.com")` → `[...]`

🎨 Easy Colors

点击展开 — 无需记忆公式即可进行 hex/RGB/HSL 颜色转换

功能	作用	示例
`is_valid_hex(hex_code)`	检查字符串是否为有效的十六进制颜色代码	`is_valid_hex("#FFFFFF")` → `True`
`hex_to_rgb(hex_code)`	将十六进制颜色代码转换为 (R, G, B) 元组	`hex_to_rgb("#FFFFFF")` → `(255, 255, 255)`
`rgb_to_hex(r, g, b)`	将 (R, G, B) 值转换为十六进制颜色字符串	`rgb_to_hex(255, 255, 255)` → `"#FFFFFF"`
`rgb_to_hsl(r, g, b)`	将 (R, G, B) 值转换为 (H, S, L) 元组	`rgb_to_hsl(255, 0, 0)` → `(0.0, 100.0, 50.0)`
`hsl_to_rgb(h, s, lightness)`	将 (H, S, L) 颜色转换为 (R, G, B) 元组	`hsl_to_rgb(120, 100, 50)` → `(0, 255, 0)`
`random_hex_color()`	返回一个随机的有效十六进制颜色字符串	`random_hex_color()` → 例如 `"#A1B2C3"`
`is_light_color(hex_code)`	根据感知亮度返回十六进制颜色是否为“浅色”	`is_light_color("#FFFFFF")` → `True`
`hex_to_rgba(hex_code, alpha)`	将十六进制颜色和 alpha 值转换为 (R, G, B, A) 元组	`hex_to_rgba("#FF0000", 0.5)` → `(255, 0, 0, 0.5)`
`contrast_ratio(hex1, hex2)`	计算两个十六进制颜色之间的 WCAG 对比度	`contrast_ratio("#000000", "#FFFFFF")` → `21.0`

🔄 Easy Flow

点击展开 — 无需样板代码即可运行脚本、计时和重试

功能	作用	示例
`run_py_file(filename)`	将 `.py` 文件作为 `__main__` 运行，失败时抛出 `EasyFlowError`	`run_py_file("script.py")`
`run_py_file_safe(filename)`	与 `run_py_file` 相同，但返回 `(success, error)` 而不是抛出异常	`success, error = run_py_file_safe("script.py")`
`time_function_call(function, args=None)`	运行一次函数并返回其耗时（以秒为单位）	`time_function_call(add, [2, 3])` → `0.000002`
`time_it`	用于测量函数执行时间并打印耗时的装饰器	在函数定义上方使用 `@time_it`
`retry(func, attempts=3, delay=1)`	调用函数，若失败则重试，尝试之间设有暂停	`retry(flaky_api, attempts=5, delay=2)`

📄 Easy JSON

点击展开 — 无需样板代码的 JSON 文件处理

功能	作用	示例
`open_json(path)`	将 JSON 文件读取为字典	`open_json("config.json")`
`save_json_data(path, dict)`	将字典保存为新的 JSON 文件	`save_json_data("config.json", {"name": "Sara"})`
`update_json(path, dict)`	将新数据合并到现有的 JSON 文件中	`update_json("config.json", {"name": "Sara"})`
`pretty_json(data=dict)`	将字典以缩进 JSON 格式美观打印	`pretty_json(data={"name": "Sara"})`
`pretty_json(filepath=path)`	美观打印 JSON 文件的内容	`pretty_json(filepath="config.json")`
`is_json_file(path)`	检查文件是否存在且为 .json	`is_json_file("config.json")` → `True`
`is_nested_json(data=dict)`	检查字典是否包含嵌套的字典/列表	`is_nested_json(data={"a": 1, "b": {"c": 2}})` → `True`
`flatten_json(data=dict)`	将嵌套字典展平为单层键	`flatten_json(data={"a": 1, "b": {"c": 2}})` → `{"a": 1, "b-c": 2}`

🔍 Easy Regex

点击展开 — 无需编写正则表达式即可从文本中提取常见模式

功能	作用	示例
`extract_emails(text)`	查找文本中的所有电子邮件地址	`extract_emails("Contact hello@example.com")` → `['hello@example.com']`
`extract_urls(text)`	查找文本中的所有 URL	`extract_urls("Visit www.example.com")` → `['www.example.com']`
`extract_number_sequences(text)`	查找由 `-`、`_`、`:` 或 `.` 连接的数字序列（日期、时间、IP、ID）	`extract_number_sequences("IP 192.168.1.1 at 14:32")` → `['192.168.1.1', '14:32']`
`extract_numbers(text)`	查找所有独立的数字序列	`extract_numbers("I have 3 cats and 12 fish")` → `['3', '12']`

⚡ Easy Async

点击展开 — 无需直接操作 ThreadPoolExecutor 即可同时运行多个函数

函数	功能	示例
`run_at_the_same_time_no_params(functions)`	同时运行多个函数	`run_at_the_same_time_no_params([add, sub])` → `[('add', 2), ('sub', 2)]`
`run_at_the_same_time_with_params(functions_and_args)`	同时运行多个函数，每个函数拥有各自的参数	`run_at_the_same_time_with_params([(add, 1, 1), (sub, 4, 2)])` → `[('add', 2), ('sub', 2)]`

🔑 Easy Dict

点击展开 — 无需样板代码的字典操作

函数	功能	示例
`merge_dicts(dict_a, dict_b)`	合并两个字典，共享键以 dict_b 为准	`merge_dicts({"a": 1}, {"b": 2})` → `{"a": 1, "b": 2}`
`lists_to_dict(keys, values)`	将两个列表合并为字典，按位置配对	`lists_to_dict(["name", "age"], ["Ana", 25])` → `{"name": "Ana", "age": 25}`
`invert_dict(dictionary)`	返回一个新字典，键和值互换	`invert_dict({"a": 1, "b": 2})` → `{1: "a", 2: "b"}`
`get_nested_value(dictionary, path)`	使用点分隔路径获取嵌套值，并提供默认回退值	`get_nested_value({"user": {"name": "Ana"}}, "user.name")` → `"Ana"`
`sort_dict_by_key(dictionary)`	返回一个新字典，键按字母顺序排序	`sort_dict_by_key({"b": 2, "a": 1})` → `{"a": 1, "b": 2}`
`sort_dict_by_value(dictionary)`	返回一个新字典，值按从小到大排序	`sort_dict_by_value({"a": 2, "b": 1})` → `{"b": 1, "a": 2}`
`rename_key(dictionary, old, new)`	返回字典的副本，其中一个键被重命名	`rename_key({"name": "Ana"}, "name", "username")` → `{"username": "Ana"}`
`find_keys(needle, dictionary)`	返回所有值与给定 needle 匹配的键	`find_keys(1, {"a": 1, "b": 2, "c": 1})` → `["a", "c"]`
`count_values(dictionary)`	统计字典中每个值出现的次数	`count_values({"a": 1, "b": 2, "c": 1})` → `{1: 2, 2: 1}`
`most_common_value(dictionary)`	返回字典中出现次数最多的值	`most_common_value({"a": 1, "b": 2, "c": 1})` → `1`

🖼️ Easy Images

点击展开 — 调整大小、转换、旋转和检查图像，而无需直接处理 Pillow

功能	作用	示例
`resize_image("photo.jpg", "photo_small.jpg", 320, 240)`	将图像调整为指定尺寸并保存	将 `photo.jpg` 保存为 320×240 版本的 `photo_small.jpg`
`convert_image("photo.png", "photo.jpg")`	根据文件扩展名将图像转换为不同格式	将 `photo.png` 保存为位于 `photo.jpg` 的 JPEG 文件
`rotate_image("photo.jpg", "photo_rotated.jpg", 90)`	按指定角度（逆时针）旋转图像并保存	将 `photo.jpg` 旋转 90° 后保存为 `photo_rotated.jpg`
`get_image_info("photo.jpg")`	获取图像的基本信息	`get_image_info("photo.jpg")` → `{"width": 1920, "height": 1080, "format": "JPEG", "mode": "RGB"}`

🧮 简易数学

点击展开 — 无需重新推导公式的数学辅助工具

函数	功能	示例
`get_least_common_multiple(a, b)`	返回两个整数的最小公倍数	`get_least_common_multiple(4, 6)` → `12`
`factorial(n)`	返回一个整数的阶乘	`factorial(5)` → `120`
`fibonacci(count)`	返回前 `count` 个斐波那契数	`fibonacci(5)` → `[0, 1, 1, 2, 3]`
`prime_factorization(n)`	返回一个数的质因数，包括重复项	`prime_factorization(12)` → `[2, 2, 3]`
`sum_of_digits(n)`	返回一个整数各位数字之和	`sum_of_digits(1234)` → `10`
`divisors(n)`	返回所有能整除 n 的正整数	`divisors(12)` → `[1, 2, 3, 4, 6, 12]`

📊 Easy Stats

点击展开 — 无需记忆公式即可进行统计操作

函数	功能	示例
`median(nums)`	返回数字列表的中位数	`median([4, 1, 9, 2])` → `3.0`
`mode(nums)`	返回出现次数最多的数字	`mode([2, 1, 2, 3])` → `2`
`data_range(nums)`	返回最大数与最小数之间的差值	`data_range([4, 1, 8, 2])` → `7`
`variance(nums)`	返回数字的离散程度，作为样本方差	`variance([1, 2, 3])` → `1.0`
`standard_deviation(nums)`	返回数字通常距离平均值的距离	`standard_deviation([1, 2, 3])` → `1.0`
`percentile(nums, percent)`	返回给定百分比的数字所低于的数值	`percentile([1, 2, 3, 4], 75)` → `3`

📑 Easy CSV

点击展开 — 无需 csv 模块样板代码即可读写 CSV

函数	功能	示例
`read_csv_to_list("people.csv")`	将 CSV 文件读取为字典（或列表）列表	`read_csv_to_list("people.csv")` → `[{'Name': 'Alice', 'Age': '24'}]`
`write_csv_from_list("people.csv", data)`	将字典或列表列表写入 CSV 文件	`write_csv_from_list("people.csv", [{"Name": "Alice", "Age": "24"}])`
`get_csv_columns("people.csv")`	返回 CSV 文件的列标题	`get_csv_columns("people.csv")` → `['Name', 'Age']`
`filter_csv_rows("people.csv", "Name", "Alice")`	返回某列匹配给定值的行	`filter_csv_rows("people.csv", "Name", "Alice")` → `[{'Name': 'Alice', 'Age': '24'}]`

🎮 Easy Game

点击展开 — 无需样板代码的 pygame 设置

功能	作用	示例
`basic_game_setup(800, 600, "My Game")`	通过一次调用设置 pygame 窗口和时钟（init, display, caption, clock）	`screen, clock = basic_game_setup(800, 600, "My Game")`

🤝 贡献

我非常乐意得到您的帮助，让 Python 对每个人来说都更简单！

欢迎任何形式的贡献：

修复文档
改进现有模块
建议新功能
添加新功能
改进示例

请在提交更改前查看 CONTRIBUTING.md。

每一份贡献都有助于让 py-simple-wrap 对初学者和开发者更好。

🤝 贡献者

衷心感谢这些优秀的人，帮助让 Python 对每个人来说都更简单！

表情符号说明：

💻 = 代码
📖 = 文档
🐛 = 错误报告
🧪 = 测试
🚇 = 基础设施
🛡️ = 维护者
👑 = 原作者
🚀 = 项目管理
✋ = 协作者

_{Sara Czasak} 🛡️ 🚀 💻 📖 👑 ✋	_{jagjitkaur0000} 🧪 ✋	_{atiqur rahman} 🧪 ✋	_{Gaohar Imran} 🧪 💻 ✋	_{Yassin Azzouzi} 📖 ✋	_ghostfix-pm 🚇 🧪 💻 📖	_{Pranjal Solanki} 💻
_{Shivam Singh} 📖 🧪 💻	_{Challa Leela Prasad} 💻	_HeaTTap 📖 🧪 💻	_{Avery Quinn} 🧪	_{Marcos Max} 📖	_Matheus 🧪	_{Mlandvo Maphalala} 🧪 🐛
_qotique 📖	_AureSerua 💻	_{Dane Parin} 💻 🧪	_{Vijay Misal} 💻 🧪