# mymodule.py  —— 这是一个模块
def greet(name):
    return f"Hello, {name}!"

PI = 3.14159

class Calculator:
    pass

# main.py —— 导入并使用模块
import mymodule

print(mymodule.greet("Alice"))   # → Hello, Alice!
print(mymodule.PI)                # → 3.14159

# math_ops.py
def add(a, b):
    return a + b

# string_ops.py
def add(a, b):
    return a + b  # 同名函数，但互不干扰，因为命名空间不同

# main.py
import math_ops
import string_ops

print(math_ops.add(1, 2))      # → 3
print(string_ops.add("A", "B")) # → AB

import math

print(type(math))           # → <class 'module'>
print(math.__name__)         # → 'math'
print(math.__file__)         # → '/usr/lib/python3.12/math.py'（实际路径可能不同）
print(math.__dict__)         # → 模块中所有定义的字典（命名空间）

# 模块对象可以像任何对象一样被赋值给变量
m = math
print(m.sqrt(16))            # → 4.0

import sys

# 查看模块搜索路径
for i, path in enumerate(sys.path, 1):
    print(f"{i}. {path}")

import sys

# sys.path 的组成
print(f"1. 当前脚本目录: {sys.path[0]}")
print(f"2. PYTHONPATH 环境变量: {'已设置' if 'PYTHONPATH' in __import__('os').environ else '未设置'}")
print(f"3. 标准库路径: {[p for p in sys.path if 'lib/python' in p]}")
print(f"4. .pth 文件加载: {'site-packages' in str(sys.path)}")

# 演示搜索路径机制
import sys
import os

# 动态添加搜索路径
sys.path.insert(0, "/tmp/my_custom_modules")

# 查看当前工作目录
print(f"当前工作目录: {os.getcwd()}")
print(f"sys.path[0] (脚本目录): {sys.path[0]}")

# 写法 1：导入整个模块（推荐）
import math
print(math.sqrt(16))        # 通过模块名访问

# 写法 2：导入特定名称
from math import sqrt
print(sqrt(16))              # 直接使用，无需模块名前缀

# 写法 3：导入多个名称
from math import sqrt, pi, sin
print(sqrt(16), pi, sin(0))

# 写法 4：导入所有公开名称（谨慎使用）
from math import *           # 导入 math 的所有公开成员
print(sqrt(16))
print(pi)

# 写法 5：起别名
import numpy as np           # 模块别名
from math import sqrt as square_root  # 名称别名
print(square_root(16))

# 写法 6：延迟导入（在函数内部）
def use_math():
    import math              # 函数调用时才导入
    return math.sqrt(25)

# 全局导入 —— 在模块顶部（惯例）
import os

# 函数内导入 —— 延迟导入（只在需要时加载）
def read_file(path):
    import json              # 仅在函数被调用时导入
    with open(path) as f:
        return json.load(f)

# 条件导入 —— 根据条件选择不同模块
import sys
if sys.platform == 'win32':
    import msvcrt
else:
    import termios            # Unix 系

# 导入并赋值给不同名字
import sys as system_module
from os import path as ospath

# sys.modules 是模块缓存的字典
import sys

# 查看所有已加载的模块
print(f"已加载模块数量: {len(sys.modules)}")
print(f"前几个: {list(sys.modules.keys())[:10]}")

import sys

# 验证导入是否使用缓存
print("第一次导入...")
import json
print(f"json 在 sys.modules 中: {'json' in sys.modules}")

# 第二次导入——直接从缓存取，不会重新执行 json 代码
print("第二次导入...")
import json                 # 这个几乎不花时间
print(f"sys.modules['json'] is json: {sys.modules['json'] is json}")

# 演示模块缓存
import importlib
import sys

# 创建一个测试模块
with open('/tmp/mymod.py', 'w') as f:
    f.write("value = 1\n")

# 第一次导入
import importlib.util
spec = importlib.util.spec_from_file_location("mymod", "/tmp/mymod.py")
mod = importlib.util.module_from_spec(spec)
sys.modules["mymod"] = mod
spec.loader.exec_module(mod)
print(f"第一次: value = {mod.value}")  # → 1

# 修改源文件
with open('/tmp/mymod.py', 'w') as f:
    f.write("value = 999\n")

# 再次 import —— 使用缓存，不会读取新的源文件
import mymod                    # 这里会报错，因为我们刚用 importlib 手动注册了
# 用 reload 强制重新加载
importlib.reload(mod)
print(f"reload 后: value = {mod.value}")  # → 999

# 1. 检查模块是否已导入
if 'requests' not in sys.modules:
    print("requests 尚未加载")
    
# 2. 防御性移除缓存（危险操作！）
if 'my_module' in sys.modules:
    del sys.modules['my_module']   # 强制下次重新导入

# 3. 查看模块源代码位置
import pandas
print(sys.modules['pandas'].__file__) if 'pandas' in sys.modules else print("pandas 未加载")

# 4. 手动注册模块（高级用法）
import types
dummy_mod = types.ModuleType("dummy")
dummy_mod.x = 42
sys.modules["dummy"] = dummy_mod

import dummy                     # 这次不会出错！
print(dummy.x)                   # → 42

# calculator.py
def add(a, b):
    return a + b

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

# 这是一段测试代码 —— 只在直接运行时执行
if __name__ == '__main__':
    # 测试 add
    assert add(2, 3) == 5, "add(2,3) 应为 5"
    assert add(-1, 1) == 0
    
    # 测试 subtract
    assert subtract(5, 3) == 2
    
    # 交互测试
    print("✅ 所有测试通过")
    print(f"add(10, 20) = {add(10, 20)}")

# main.py
import calculator          # 会执行 calculator 的模块代码，但不会执行测试代码

print(calculator.add(5, 3))  # → 8（不会打印测试信息）

# 演示 __name__ 的运行时变化

# 选项 1：直接运行 python3 thisfile.py
# 选项 2：导入 import thisfile

def where_am_i():
    """打印当前模块的 __name__ 信息"""
    print(f"当前模块 __name__ = '{__name__}'")
    print(f"当前模块 __file__ = '{__file__}'")
    print(f"直接运行? {__name__ == '__main__'}")

where_am_i()

# 如果是被导入的，__name__ 会是模块名
# 如果是被直接运行的，__name__ 是 '__main__'

# 查看其他模块的 __name__
import math
import sys

print(f"math.__name__ = '{math.__name__}'")
print(f"sys.__name__  = '{sys.__name__}'")

# 每个模块有自己的 __name__
# math.__name__ 永远是 'math'
# sys.__name__  永远是 'sys'

# 模式 1：基本用法
if __name__ == '__main__':
    main()

# 模式 2：带命令行参数
if __name__ == '__main__':
    import sys
    if len(sys.argv) > 1:
        # 处理命令行参数
        pass

# 模式 3：单元测试自动运行
if __name__ == '__main__':
    import doctest
    doctest.testmod()
    # 或
    import unittest
    unittest.main()

# 模式 4：性能基准测试
if __name__ == '__main__':
    import timeit
    print(timeit.timeit('"-".join(str(n) for n in range(100))', number=10000))

# 模式 5：交互式帮助
if __name__ == '__main__':
    print("📖 帮助信息：这个模块提供了 XXX 功能")
    print("使用方法：import 模块名")

"""
示例：一个同时支持导入和直接运行的模块
"""

def factorial(n):
    """计算 n 的阶乘"""
    if n < 0:
        raise ValueError("负数没有阶乘")
    if n <= 1:
        return 1
    return n * factorial(n - 1)

def fibonacci(n):
    """返回前 n 个斐波那契数"""
    if n <= 0:
        return []
    if n == 1:
        return [0]
    result = [0, 1]
    for i in range(2, n):
        result.append(result[-1] + result[-2])
    return result

def is_prime(n):
    """判断 n 是否为质数"""
    if n < 2:
        return False
    for i in range(2, int(n ** 0.5) + 1):
        if n % i == 0:
            return False
    return True

# ---- 只有直接运行时才执行的代码 ----
if __name__ == '__main__':
    # 测试区
    print("🧪 运行自测试...")
    
    # 测试 factorial
    assert factorial(0) == 1
    assert factorial(5) == 120
    assert factorial(10) == 3628800
    
    # 测试 fibonacci
    assert fibonacci(0) == []
    assert fibonacci(1) == [0]
    assert fibonacci(5) == [0, 1, 1, 2, 3]
    
    # 测试 is_prime
    assert is_prime(2) == True
    assert is_prime(4) == False
    assert is_prime(17) == True
    
    print("✅ 所有测试通过！")
    print()
    
    # 交互演示
    import sys
    print(f"🎯 当前文件: {__file__}")
    print(f"🏷️  __name__ = {__name__}")
    
    if len(sys.argv) > 1:
        try:
            n = int(sys.argv[1])
            print(f"factorial({n}) = {factorial(n)}")
            print(f"fibonacci({n}) = {fibonacci(n)}")
            print(f"is_prime({n}) = {is_prime(n)}")
        except ValueError:
            print("❌ 请提供整数参数")

# mypackage/__init__.py

# 作用 1：包级别的文档
"""mypackage - 一个示例工具包"""

# 作用 2：集中导入，简化使用路径
from mypackage.module_a import func_a
from mypackage.module_b import func_b

# 用户可以直接：
# import mypackage
# mypackage.func_a()     # 而不需要 mypackage.module_a.func_a()

# 作用 3：包级别的变量
__version__ = "1.0.0"
__author__ = "Python Learner"

# 作用 4：控制 from mypackage import * 的行为
__all__ = ['func_a', 'func_b', 'CONSTANT', 'ModuleA']

# 作用 5：import 时的副作用（谨慎使用）
print(f"🔧 正在初始化 mypackage v{__version__}")

# 作用 6：延迟导入，只在需要时加载重型模块
def get_heavy_module():
    """延迟加载重型依赖"""
    from mypackage.heavy_module import HeavyProcessor
    return HeavyProcessor()

# mypackage/__init__.py

# 导入子模块中的特定函数
from .string_ops import capitalize, reverse
from .math_ops import add, subtract, multiply, divide

# 定义 __all__ —— 控制 from mypackage import * 的行为
__all__ = [
    'capitalize',    # 对外公开
    'reverse',       # 对外公开
    'add',           # 对外公开
    'subtract',      # 对外公开
    # 'multiply',    # 不对外公开（虽然可以导入，但默认不会）
    # 'divide',      # 不对外公开
    '__version__',
]

# 步骤 1：创建目录结构
# mytoolkit/
# ├── __init__.py
# ├── config.py
# ├── validators.py
# └── formatters.py

# 步骤 2：编写 __init__.py
"""
mytoolkit - 个人工具箱
"""

from mytoolkit.validators import validate_email, validate_phone
from mytoolkit.formatters import format_date, format_currency
from mytoolkit.config import load_config, save_config

__version__ = '0.1.0'
__all__ = [
    'validate_email',
    'validate_phone',
    'format_date',
    'format_currency',
    'load_config',
    'save_config',
]

# 步骤 3：在其他文件中使用
# 方式 A：导入包名，访问其属性
import mytoolkit
mytoolkit.validate_email("user@example.com")
mytoolkit.format_currency(1000)
print(mytoolkit.__version__)

# 方式 B：直接导入特定函数
from mytoolkit import validate_email, format_date

# 方式 C：导入子模块（需要模块中定义 __all__ 或显式指定）
from mytoolkit.validators import validate_email as email_validator

# 方式 D：导入所有公开接口
from mytoolkit import *
print(validate_email)   # ✅ 公开的
# print(validate_phone)  # ❌ 如果不在 __all__ 中则不可用

# 绝对导入示例

# 从标准库
import os
import sys
from datetime import datetime

# 从第三方包
import requests
from flask import Flask

# 从自己的包
import mypackage
from mypackage.module_a import func_a
from mypackage.subpackage.module_c import func_c

# package/subpackage/module_c.py

# .  表示当前包（即 subpackage）
from . import module_d           # 同级模块
from .module_d import func_d     # 同级模块中的函数

# .. 表示父包（即 package）
from .. import module_a
from ..module_a import func_a

# ... 表示父包的父包（不要滥用）
from ... import another_package

# 考虑以下目录结构：
# project/
# ├── main.py                ← 入口文件
# ├── package/
# │   ├── __init__.py
# │   ├── module_a.py
# │   └── subpackage/
# │       ├── __init__.py
# │       ├── module_b.py
# │       └── module_c.py

# === package/__init__.py ===
from .module_a import helper_a
from .subpackage import helper_b

# === package/module_a.py ===
# 绝对导入：明确、推荐
from package.subpackage.module_b import func_b

def helper_a():
    return "A"

# === package/subpackage/module_b.py ===
# 相对导入：简洁，但要正确理解上下文
from .. import module_a          # 从父包导入
from . import module_c           # 从同级导入

def func_b():
    return f"B + {module_a.helper_a()} + {module_c.func_c()}"

# === package/subpackage/module_c.py ===
def func_c():
    return "C"

# ❌ 错误：直接运行 main.py，里面使用相对导入
# main.py
from .mymodule import x   # ImportError: attempted relative import with no known parent package

# ✅ 正确：入口文件用绝对导入
# main.py
from mymodule import x     # 正确！

# PEP 8 推荐的导入顺序
# 1. 标准库
import os
import sys
from datetime import datetime

# 2. 第三方库
import requests
import numpy as np

# 3. 本地模块（绝对导入优先）
from myproject.models import User
from myproject.services import api

# from module import * 会导入模块中所有"公开"的名称

# 情形 A：模块定义了 __all__
# mymodule.py
# __all__ = ['func_a', 'CONSTANT']  # 只导入这两个

# 情形 B：模块没有 __all__
# 导入所有不以 _ 开头的名称（所谓的"伪私有"）

from math import *    # 导入 sqrt, pi, sin, cos... 等所有非 _ 开头的名称
print(sqrt(16))        # → 4.0
print(pi)              # → 3.14159

# mytoolkit/__init__.py

# 精准控制公开接口
__all__ = [
    'process_data',
    'validate_input',
    'DEFAULT_TIMEOUT',
]

# 内部实现细节（以 _ 开头），不对外公开
_internal_helper = None
_private_config = {}

def process_data(data):
    """公开的 API — 用户应该使用这个"""
    _validate_internal(data)
    return _transform(data)

def validate_input(data):
    """公开的 API"""
    return _internal_validation(data)

def _validate_internal(data):
    """内部函数，不属于公开 API"""
    pass

def _transform(data):
    """内部函数，不属于公开 API"""
    return data

DEFAULT_TIMEOUT = 30
_INTERNAL_CONSTANT = 42  # 以下划线开头，import * 不会导入

# 使用
from mytoolkit import *

print(process_data)      # ✅ 公开
print(validate_input)    # ✅ 公开
print(DEFAULT_TIMEOUT)   # ✅ 公开
# print(_validate_internal)  # ❌ NameError（不在 __all__ 中）
# print(_INTERNAL_CONSTANT)  # ❌ NameError（以下划线开头）

# 包级别：在 __init__.py 中定义 __all__
# 控制 from mypackage import * 的行为

# mypackage/__init__.py
from .module_a import func_a, _internal_func_a
from .module_b import func_b

__all__ = ['func_a', 'func_b']

# 使用
from mypackage import *
# 只导入 func_a 和 func_b
# _internal_func_a 不会被导入

# ⚠️ 避免在大型项目中用 import *
# 原因 1：命名冲突
from math import *    # 导入了 40 多个名字
from cmath import *   # 同名函数会被覆盖！

# 上面两条语句后：
# sqrt 可能指向 cmath.sqrt（复数版本），而不是 math.sqrt（实数版本）！

# 原因 2：不知道哪些名字被导入
# 代码阅读者不知道 sqrt 是从 math 还是 cmath 来的

# 推荐的做法
import math
import cmath

print(math.sqrt(-1))   # ValueError: math domain error
print(cmath.sqrt(-1))  # 1j（复数结果）

# Python 如何判断缓存是否有效？
#
# 每次生成 .pyc 时，Python 会记录：
# 1. 源文件的修改时间戳（mtime）
# 2. 源文件的大小（size）
#
# 当再次导入时：
# - 检查 .pyc 是否存在
# - 检查 .pyc 中记录的时间戳和大小是否与源文件匹配
# - 匹配 → 直接加载字节码（跳过编译）
# - 不匹配 → 重新编译源文件

# 可以手动控制缓存行为
import py_compile

# 手动编译某个文件
py_compile.compile('mymodule.py', cfile='__pycache__/mymodule.cpython-312.pyc')

# 或使用命令行
# python3 -m py_compile mymodule.py

import sys

# Python 提供了环境变量来控制缓存行为
# export PYTHONDONTWRITEBYTECODE=1  → 不写入 .pyc
# export PYTHONPYCACHEPREFIX=/tmp/pycache → 指定缓存目录

# 在代码中检查或控制
print(f"Python 不写字节码: {sys.dont_write_bytecode}")

# 如果 sys.dont_write_bytecode = True，则不会创建 __pycache__
# 可以通过 -B 选项启动：python3 -B script.py

# 运行时不生成 __pycache__
# python3 -B main.py

# strutils/__init__.py
"""
strutils - 字符串处理工具包

提供字符串操作、验证和格式化功能。
"""

from strutils.manipulation import (
    reverse,
    count_words,
    remove_duplicates,
    truncate,
)

from strutils.validation import (
    is_email,
    is_phone,
    is_url,
    is_palindrome,
)

from strutils.formatting import (
    to_title_case,
    to_snake_case,
    to_camel_case,
    mask_sensitive,
)

__version__ = '0.1.0'
__all__ = [
    'reverse', 'count_words', 'remove_duplicates', 'truncate',
    'is_email', 'is_phone', 'is_url', 'is_palindrome',
    'to_title_case', 'to_snake_case', 'to_camel_case', 'mask_sensitive',
]

# strutils/manipulation.py
"""字符串操作模块"""


def reverse(text: str) -> str:
    """反转字符串"""
    return text[::-1]


def count_words(text: str) -> int:
    """统计单词数"""
    return len(text.split())


def remove_duplicates(text: str) -> str:
    """移除连续重复字符"""
    if not text:
        return text
    result = [text[0]]
    for ch in text[1:]:
        if ch != result[-1]:
            result.append(ch)
    return ''.join(result)


def truncate(text: str, max_length: int = 50, suffix: str = '...') -> str:
    """截断字符串到指定长度"""
    if len(text) <= max_length:
        return text
    return text[:max_length - len(suffix)] + suffix

# strutils/validation.py
"""字符串验证模块（相对导入示例）"""

from .formatting import to_snake_case
import re


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


def is_phone(text: str) -> bool:
    """验证中国大陆手机号"""
    pattern = r'^1[3-9]\d{9}$'
    return bool(re.match(pattern, text.strip()))


def is_url(text: str) -> bool:
    """验证 URL 格式"""
    pattern = r'^https?://[^\s/$.?#].[^\s]*$'
    return bool(re.match(pattern, text.strip()))


def is_palindrome(text: str) -> bool:
    """判断是否为回文字符串"""
    cleaned = re.sub(r'[^a-zA-Z0-9]', '', text).lower()
    return cleaned == cleaned[::-1]


# 演示相对导入 —— 使用同包的 formatting 模块
def normalize_and_validate(email: str) -> dict:
    """规范化邮箱并验证"""
    normalized = to_snake_case(email.strip().lower())
    return {
        'original': email,
        'normalized': normalized,
        'is_valid': is_email(normalized),
    }

# strutils/formatting.py
"""字符串格式化模块"""


def to_title_case(text: str) -> str:
    """转为标题格式"""
    return text.title()


def to_snake_case(text: str) -> str:
    """转为蛇形命名（words_like_this）"""
    result = []
    for i, ch in enumerate(text):
        if ch.isupper():
            if i > 0 and text[i - 1].islower():
                result.append('_')
            result.append(ch.lower())
        elif ch in (' ', '-', '.'):
            if result and result[-1] != '_':
                result.append('_')
        else:
            result.append(ch)
    return ''.join(result).strip('_')


def to_camel_case(text: str) -> str:
    """转为驼峰命名（camelCase）"""
    words = text.replace('-', ' ').replace('_', ' ').split()
    if not words:
        return ''
    return words[0].lower() + ''.join(w.capitalize() for w in words[1:])


def mask_sensitive(text: str, visible_chars: int = 4, mask_char: str = '*') -> str:
    """脱敏处理：保留最后 visible_chars 位，其余替换为 mask_char"""
    if len(text) <= visible_chars:
        return text
    return mask_char * (len(text) - visible_chars) + text[-visible_chars:]

# mathutils/__init__.py
"""
mathutils - 数学计算工具包

提供基础运算、统计计算和单位转换功能。
"""

from mathutils.basic import (
    add, subtract, multiply, divide,
    power, sqrt, factorial, gcd, lcm,
)

from mathutils.statistics import (
    mean, median, mode, variance, std_dev,
)

from mathutils.conversion import (
    celsius_to_fahrenheit,
    fahrenheit_to_celsius,
    km_to_miles,
    miles_to_km,
    kg_to_lbs,
    lbs_to_kg,
)

__version__ = '0.1.0'
__all__ = [
    'add', 'subtract', 'multiply', 'divide',
    'power', 'sqrt', 'factorial', 'gcd', 'lcm',
    'mean', 'median', 'mode', 'variance', 'std_dev',
    'celsius_to_fahrenheit', 'fahrenheit_to_celsius',
    'km_to_miles', 'miles_to_km', 'kg_to_lbs', 'lbs_to_kg',
]

# mathutils/basic.py
"""基础运算模块"""


def add(*args: float) -> float:
    """加法"""
    return sum(args)


def subtract(a: float, b: float) -> float:
    """减法"""
    return a - b


def multiply(*args: float) -> float:
    """乘法"""
    result = 1
    for n in args:
        result *= n
    return result


def divide(a: float, b: float) -> float:
    """除法"""
    if b == 0:
        raise ZeroDivisionError("除数不能为 0")
    return a / b


def power(base: float, exp: float) -> float:
    """乘方"""
    return base ** exp


def sqrt(n: float) -> float:
    """平方根"""
    if n < 0:
        raise ValueError("负数没有实数平方根")
    return n ** 0.5


def factorial(n: int) -> int:
    """阶乘"""
    if n < 0:
        raise ValueError("负数没有阶乘")
    if n <= 1:
        return 1
    result = 1
    for i in range(2, n + 1):
        result *= i
    return result


def gcd(a: int, b: int) -> int:
    """最大公约数（欧几里得算法）"""
    while b:
        a, b = b, a % b
    return abs(a)


def lcm(a: int, b: int) -> int:
    """最小公倍数"""
    if a == 0 or b == 0:
        return 0
    return abs(a * b) // gcd(a, b)

# mathutils/statistics.py
"""统计计算模块（相对导入示例）"""

from .basic import sqrt as _sqrt
import math


def mean(data: list) -> float:
    """算术平均值"""
    if not data:
        raise ValueError("空数据集")
    return sum(data) / len(data)


def median(data: list) -> float:
    """中位数"""
    if not data:
        raise ValueError("空数据集")
    sorted_data = sorted(data)
    n = len(sorted_data)
    mid = n // 2
    if n % 2 == 1:
        return sorted_data[mid]
    return (sorted_data[mid - 1] + sorted_data[mid]) / 2


def mode(data: list):
    """众数"""
    if not data:
        raise ValueError("空数据集")
    from collections import Counter
    counter = Counter(data)
    max_count = max(counter.values())
    modes = [k for k, v in counter.items() if v == max_count]
    return modes[0] if len(modes) == 1 else modes


def variance(data: list, ddof: int = 0) -> float:
    """方差"""
    if not data:
        raise ValueError("空数据集")
    n = len(data)
    if n <= ddof:
        raise ValueError(f"数据量 {n} 不足以计算自由度 {ddof} 的方差")
    avg = mean(data)
    return sum((x - avg) ** 2 for x in data) / (n - ddof)


def std_dev(data: list, ddof: int = 0) -> float:
    """标准差"""
    return _sqrt(variance(data, ddof))

# mathutils/conversion.py
"""单位转换模块"""


def celsius_to_fahrenheit(c: float) -> float:
    """摄氏度 → 华氏度"""
    return c * 9 / 5 + 32


def fahrenheit_to_celsius(f: float) -> float:
    """华氏度 → 摄氏度"""
    return (f - 32) * 5 / 9


def km_to_miles(km: float) -> float:
    """公里 → 英里"""
    return km * 0.621371


def miles_to_km(miles: float) -> float:
    """英里 → 公里"""
    return miles / 0.621371


def kg_to_lbs(kg: float) -> float:
    """公斤 → 磅"""
    return kg * 2.20462


def lbs_to_kg(lbs: float) -> float:
    """磅 → 公斤"""
    return lbs / 2.20462

# 方式 1：导入整个包
import strutils

print(strutils.is_email("hello@example.com"))    # → True
print(strutils.reverse("Python"))                 # → nohtyP
print(strutils.mask_sensitive("1234567890"))      # → ******7890

# 方式 2：导入特定函数
from mathutils import add, mean, celsius_to_fahrenheit

print(add(1, 2, 3, 4, 5))              # → 15
print(mean([10, 20, 30, 40, 50]))       # → 30.0
print(celsius_to_fahrenheit(100))        # → 212.0

# 方式 3：使用 from ... import *
from strutils import *

print(count_words("hello world python"))  # → 3
print(is_palindrome("A man a plan a canal Panama"))  # → True
print(truncate("这是一段很长的文本内容...", 5))  # → 这是一...

# 方式 4：实际导入包的方法
from strutils.manipulation import truncate

# 演示 truncate
long_text = "Python 是一种广泛使用的解释型、高级编程语言。"
print(truncate(long_text, 20))
# → Python 是一种广泛使用...

# module_a.py
from module_b import func_b

def func_a():
    return func_b()

# module_b.py
from module_a import func_a

def func_b():
    return func_a()

# 运行时会报 ImportError
# 解决方案：延迟导入

# ✅ 解决方案 1：延迟导入（在函数内部导入）
# module_a.py
def func_a():
    from module_b import func_b
    return func_b()

# module_b.py
def func_b():
    from module_a import func_a
    return func_a()

# ✅ 解决方案 2：重构，提取公共代码到第三个模块
# common.py —— 放置 a 和 b 都需要的函数
def shared_func():
    pass

# module_a.py
from common import shared_func

# module_b.py
from common import shared_func

# ❌ 错误示例
# mypackage/__main__.py
from . import submodule   # ❌ ImportError: attempted relative import with no known parent package

# ✅ 正确做法：在入口文件中使用绝对导入
# main.py
from mypackage import submodule

# 场景：项目被多个 Python 版本运行
# Python 3.11 编译了 .pyc 文件
# Python 3.12 运行时会检测版本不匹配，重新编译
# 但如果源文件被删除，只有 .pyc 文件 → 无法运行！

# 解决方案：版本控制忽略 __pycache__
# .gitignore 中添加：
# __pycache__/
# *.pyc

# 假设有两个模块：
# module_a.py
VERSION = "1.0"

# module_b.py
VERSION = "2.0"

# main.py
from module_a import *
from module_b import *

print(VERSION)  # → "2.0"（module_a 的 VERSION 被覆盖！）
# 最后导入的模块的同名变量会覆盖之前的
# 解决方案：用 import module_a; module_a.VERSION

# 在库代码中修改 sys.path 会影响全局
# mylibrary.py
import sys
sys.path.insert(0, '/some/path')   # ⚠️ 这会影响所有后续模块导入

# 更好的做法：使用相对导入或绝对导入
# 避免在库代码中修改 sys.path

# 如果必须添加路径，使用上下文管理器
import sys
from contextlib import contextmanager

@contextmanager
def add_to_path(path):
    sys.path.insert(0, path)
    try:
        yield
    finally:
        sys.path.remove(path)

# 使用
with add_to_path('/tmp/custom_modules'):
    import my_custom_module

# 一个容易忽视的问题：当用多种路径导入同一模块时，可能导致分叉
# 比如 mypackage/__init__.py 中做了 print("初始化...")

import mypackage           # 打印 "初始化..."
import mypackage           # 不打印（缓存）
from mypackage import func # 不打印（缓存）

# 但如果 sys.path 中有重复路径，可能导致模块被不同名称加载
import sys

# 情况：两个不同路径都指向同一个物理位置
sys.path.insert(0, '/home/user/project')
sys.path.insert(0, '/home/user/project/subdir/..')  # 和上面等价但字符串不同

import mymodule    # 第一次加载
import mymodule     # 缓存命中

# 但如果之前从另一路径导入了同模块的"别名"
# 则可能存在两个副本