Python自定义模块的创建与调用方法

# 创建一个文件：utils.py
# 这就是一个模块！

# utils.py 内容：
"""
通用工具函数模块（utils）

提供常用的辅助函数：数据验证、格式化、字符串处理等。
"""

def read_number(prompt="请输入数字: "):
    """读取用户输入的数字（带错误处理）"""
    while True:
        try:
            return float(input(prompt))
        except ValueError:
            print("输入无效，请输入一个数字。")

def clamp(value, min_val, max_val):
    """将值限定在[min_val, max_val]范围内"""
    return max(min_val, min(value, max_val))

def truncate(text, max_length, suffix="..."):
    """截断文本到指定长度"""
    if len(text) <= max_length:
        return text
    return text[:max_length - len(suffix)] + suffix

# 使用（在同一个文件或另一个.py文件中）：
# import utils
# age = utils.read_number("请输入年龄: ")
# score = utils.clamp(age, 0, 150)

# 假设当前目录结构：
# my_project/
# ├── main.py
# └── calculator.py  ← 我们要创建的模块

# ===== calculator.py =====
"""计算器模块——提供基本数学运算"""

def add(a, b):
    return a + b

def subtract(a, b):
    return a - b

def multiply(a, b):
    return a * b

def divide(a, b):
    if b == 0:
        raise ValueError("除数不能为零")
    return a / b

def power(base, exp):
    return base ** exp

# 模块级常量
PI = 3.141592653589793
E = 2.718281828459045

# ===== main.py =====
import calculator

print(calculator.add(10, 5))       # 15
print(calculator.divide(10, 3))    # 3.3333333333333335
print(calculator.PI)               # 3.141592653589793

# ⚠️ 模块命名注意事项：

# 1. 不能和Python内置模块重名
# ❌ 不要创建：math.py、random.py、json.py、os.py
# 这会"遮蔽"标准库的同名模块！

# 2. 不能和已安装的第三方库重名
# ❌ 如果装了requests库，不要创建 requests.py

# 3. 使用小写字母和下划线（PEP 8）
# ✅ utils.py, data_processor.py, email_service.py
# ❌ Utils.py, DataProcessor.py, email-service.py

# 4. 避免使用Python关键字
# ❌ class.py, import.py, from.py, if.py

# 5. 使用有意义的名字
# ✅ user_manager.py
# ❌ um.py, stuff.py, temp.py

# ⚠️ 注意：导入模块时，模块中的所有顶层代码都会执行！

# ===== demo_module.py =====
print("模块被加载了！")  # ← 这行会在import时执行！

NAME = "demo_module"
VERSION = "1.0.0"

class Demo:
    """示例类"""
    pass

def greet():
    print(f"Hello from {NAME}!")

# ✅ 好的做法：只在模块中定义（无副作用的顶层代码）
# ❌ 坏的做法：在模块顶层执行有副作用的操作

# 示例：一个模块的顶层代码对比
# 好的模块
"""
连接配置和工具函数
"""
DATABASE_URL = "postgresql://localhost/mydb"

def connect():
    """连接到数据库"""
    pass

# 坏的模块
"""
这个模块在导入时就连接数据库——不好！
"""
# db = connect()  # 先注释掉——每次import都连接数据库！浪费且不可控
# data = load_all_data()  # 同样的问题

# ✅ 好的组织
# user_service.py     —— 用户相关的所有业务逻辑
# email_utils.py      —— 邮件发送相关的工具函数
# validators.py       —— 数据验证函数集合
# config.py           —— 应用配置常量

# ❌ 不好的组织
# everything.py       —— 所有函数混在一起
# helpers.py          —— "杂项"模块（当文件名就是"各种帮助函数"时，往往意味着缺乏组织）

# 项目结构：
# my_project/
# ├── main.py
# ├── validators.py    —— 数据验证
# ├── formatters.py    —— 格式化输出
# └── converters.py    —— 数据转换

# ===== validators.py =====
"""数据验证模块"""

import re

def is_valid_email(email):
    """验证邮箱格式"""
    pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
    return bool(re.match(pattern, email))

def is_valid_phone(phone):
    """验证手机号（中国）"""
    pattern = r'^1[3-9]\d{9}$'
    return bool(re.match(pattern, phone))

def is_strong_password(password):
    """验证密码强度：至少8位，包含字母和数字"""
    return (
        len(password) >= 8
        and any(c.isalpha() for c in password)
        and any(c.isdigit() for c in password)
    )

# ===== formatters.py =====
"""格式化输出模块"""

def format_currency(amount, symbol="¥"):
    """格式化金额"""
    return f"{symbol}{amount:,.2f}"

def format_percent(value, decimals=1):
    """格式化百分比"""
    return f"{value * 100:.{decimals}f}%"

def format_table(headers, rows, col_widths=None):
    """格式化表格"""
    if col_widths is None:
        col_widths = [max(len(str(row[i])) for row in [headers] + rows)
                      for i in range(len(headers))]

    lines = [" | ".join(str(h).ljust(w) for h, w in zip(headers, col_widths))]
    lines.append("-+-".join("-" * w for w in col_widths))
    for row in rows:
        lines.append(" | ".join(str(c).ljust(w) for c, w in zip(row, col_widths)))
    return "\n".join(lines)

# ===== main.py =====
import validators
import formatters

# 使用
print(validators.is_valid_email("test@example.com"))  # True
print(validators.is_strong_password("abc12345"))       # True

headers = ["姓名", "年龄", "城市"]
rows = [("张三", "25", "北京"), ("李四", "30", "上海")]
print(formatters.format_table(headers, rows))