标准模块速查与实战

from datetime import datetime, date, time, timedelta, timezone

# ── 创建 datetime 对象 ──────────────────────────────
dt = datetime(2024, 1, 15, 10, 30, 0)     # 指定参数
now = datetime.now()                        # 当前本地时间
utc_now = datetime.now(timezone.utc)        # 当前 UTC 时间
today = datetime.today()                    # 当前时间（无时区信息）

# ── 从字符串解析 ──────────────────────────────────
dt = datetime.strptime('2024-01-15 10:30:00', '%Y-%m-%d %H:%M:%S')

# ── 从时间戳创建 ──────────────────────────────────
dt = datetime.fromtimestamp(1705305000)     # 本地时间
dt = datetime.utcfromtimestamp(1705305000)  # UTC 时间（已弃用，用下面方式）
dt = datetime.fromtimestamp(1705305000, tz=timezone.utc)

# ── 修改已有对象（返回新对象，原对象不变）─────────
dt = datetime(2024, 1, 15, 10, 30, 0)
new_dt = dt.replace(year=2025, hour=14)     # 2025-01-15 14:30:00

from datetime import datetime

dt = datetime(2024, 1, 15, 10, 30, 0)

# datetime → 字符串
s1 = dt.strftime('%Y-%m-%d')              # '2024-01-15'
s2 = dt.strftime('%Y年%m月%d日 %H:%M')     # '2024年01月15日 10:30'
s3 = dt.isoformat()                        # '2024-01-15T10:30:00'（ISO 8601）

# 字符串 → datetime
dt1 = datetime.strptime('2024-01-15', '%Y-%m-%d')
dt2 = datetime.strptime('15/01/2024 10:30', '%d/%m/%Y %H:%M')
dt3 = datetime.fromisoformat('2024-01-15T10:30:00')  # Python 3.7+

from datetime import datetime, timedelta, timezone
from zoneinfo import ZoneInfo  # Python 3.9+

# ── timedelta 运算 ─────────────────────────────────
now = datetime.now()
one_week_later = now + timedelta(weeks=1)
three_days_ago = now - timedelta(days=3)
two_hours_later = now + timedelta(hours=2)

# timedelta 的基本单位是 day 和 second
delta = timedelta(days=5, hours=3, minutes=30)
print(delta.days)              # 5
print(delta.seconds)           # 12600（3h30m = 12600s）
print(delta.total_seconds())   # 462600.0

# ── 两个 datetime 相减得到 timedelta ───────────────
dt1 = datetime(2024, 1, 15)
dt2 = datetime(2024, 6, 1)
diff = dt2 - dt1
print(diff.days)               # 138

# ── 时区处理（Python 3.9+ 推荐 zoneinfo）───────────
# 创建时区感知的 datetime
shanghai_tz = ZoneInfo('Asia/Shanghai')
newyork_tz = ZoneInfo('America/New_York')

dt_shanghai = datetime(2024, 1, 15, 10, 30, tzinfo=shanghai_tz)
dt_newyork = dt_shanghai.astimezone(newyork_tz)
print(dt_shanghai)  # 2024-01-15 10:30:00+08:00
print(dt_newyork)   # 2024-01-14 21:30:00-05:00

import time

# 获取当前本地时间的 struct_time
t = time.localtime()
# time.struct_time(
#     tm_year=2024,    # 年
#     tm_mon=6,        # 月 (1-12)
#     tm_mday=6,       # 日 (1-31)
#     tm_hour=14,      # 时 (0-23)
#     tm_min=30,       # 分 (0-59)
#     tm_sec=0,        # 秒 (0-61，闰秒)
#     tm_wday=3,       # 星期 (0=周一 ... 6=周日)
#     tm_yday=158,     # 年内天数 (1-366)
#     tm_isdst=0       # 夏令时标志 (-1=未知, 0=否, 1=是)
# )

# struct_time ↔ 时间戳
ts = time.mktime(t)           # → 1717651800.0
t2 = time.localtime(ts)       # → struct_time

# struct_time ↔ 格式化字符串
s = time.strftime('%Y-%m-%d %H:%M:%S', t)    # → '2024-06-06 14:30:00'
t3 = time.strptime(s, '%Y-%m-%d %H:%M:%S')   # → struct_time

import time

# ✅ 正确的计时方式
start = time.perf_counter()
# ... 执行代码 ...
elapsed = time.perf_counter() - start
print(f"耗时: {elapsed:.4f}s")

# ✅ 正确的超时检测（不受系统时钟跳变影响）
deadline = time.monotonic() + 30  # 30秒超时
while time.monotonic() < deadline:
    # ... 执行任务 ...
    break

# ✅ 纳秒精度计时（Python 3.7+）
start_ns = time.perf_counter_ns()
# ... 执行代码 ...
elapsed_ns = time.perf_counter_ns() - start_ns
print(f"耗时: {elapsed_ns / 1_000_000:.2f}ms")

import random

# ── 随机种子：确保可复现 ────────────────────────────
random.seed(42)
print(random.random())   # 0.6394267984578837（每次运行相同）
print(random.randint(1, 10))  # 2

random.seed(42)          # 重置种子后序列重新开始
print(random.random())   # 0.6394267984578837（相同）

# ── 线程安全问题 ──────────────────────────────────
# random 模块的全局状态不是线程安全的！
# 多线程环境应使用独立的 Random 实例：
import threading

def worker(seed_val):
    local_rng = random.Random(seed_val)  # 每个线程独立实例
    print(local_rng.random())

threads = [threading.Thread(target=worker, args=(i,)) for i in range(4)]
for t in threads:
    t.start()

import random
import secrets

# ❌ 伪随机——不适合密码学
token = ''.join(random.choices('abcdefghijklmnopqrstuvwxyz0123456789', k=16))
# 可预测！知道种子就能重现

# ✅ 安全随机——密码学安全
token = secrets.token_urlsafe(16)      # 'xZ7vQk2mPn4bRt9w'
password = secrets.token_hex(16)        # 'a1b2c3d4e5f6...'（32个十六进制字符）
rand_int = secrets.randbelow(100)       # [0, 100) 安全随机整数

import random
from collections import Counter

# ── 加权随机（如抽奖概率）─────────────────────────────
prizes = ['一等奖', '二等奖', '三等奖', '谢谢参与']
weights = [1, 5, 20, 74]    # 概率权重（1% / 5% / 20% / 74%）

results = random.choices(prizes, weights=weights, k=10000)
print(Counter(results))
# Counter({'谢谢参与': 7400, '三等奖': 2000, '二等奖': 500, '一等奖': 100})

# ── 蒙特卡洛模拟：估算 π ──────────────────────────
def estimate_pi(n: int) -> float:
    """在单位正方形内随机投点，落在内切圆内的比例 ≈ π/4"""
    inside = 0
    for _ in range(n):
        x, y = random.random(), random.random()
        if x**2 + y**2 <= 1:
            inside += 1
    return 4 * inside / n

print(f"π ≈ {estimate_pi(1_000_000):.4f}")  # π ≈ 3.1416

import json

# ═══════════════════════════════════════════════════
# 核心四函数
# ═══════════════════════════════════════════════════

# 1. dumps：Python 对象 → JSON 字符串
json_str = json.dumps(
    obj,                   # 要序列化的对象
    indent=2,              # 缩进空格数（美化输出）
    ensure_ascii=False,    # 允许非 ASCII（中文不转义）
    sort_keys=True,        # 按键名排序
    separators=(',', ':'), # 自定义分隔符（紧凑输出）
    default=str,           # 不可序列化类型的回退函数
)

# 2. loads：JSON 字符串 → Python 对象
obj = json.loads(
    json_str,              # JSON 字符串
    object_hook=None,      # 自定义 dict 解码回调
    parse_float=float,     # 自定义浮点数解析（如用 Decimal）
    parse_int=int,         # 自定义整数解析
)

# 3. dump：Python 对象 → 写入文件
with open('data.json', 'w', encoding='utf-8') as f:
    json.dump(obj, f, indent=2, ensure_ascii=False)

# 4. load：从文件读取 → Python 对象
with open('data.json', 'r', encoding='utf-8') as f:
    obj = json.load(f)

import json
from datetime import datetime, date
from decimal import Decimal

# ── 方式 1：JSONEncoder 子类（推荐）──────────────────
class EnhancedEncoder(json.JSONEncoder):
    """支持 datetime/date/Decimal/set 的自定义编码器"""

    def default(self, obj):
        if isinstance(obj, datetime):
            return obj.isoformat()          # ISO 8601 格式
        if isinstance(obj, date):
            return obj.isoformat()
        if isinstance(obj, Decimal):
            return str(obj)                  # 避免浮点精度损失
        if isinstance(obj, set):
            return sorted(obj)               # 转为排序列表
        return super().default(obj)          # 其他类型抛 TypeError

# 使用
data = {
    'event': 'created',
    'timestamp': datetime.now(),
    'price': Decimal('19.99'),
    'tags': {'python', 'json'},
}
print(json.dumps(data, cls=EnhancedEncoder, ensure_ascii=False, indent=2))
# {
#   "event": "created",
#   "timestamp": "2024-06-06T14:30:00.123456",
#   "price": "19.99",
#   "tags": ["json", "python"]
# }

# ── 方式 2：object_hook 自定义解码 ──────────────────
def decode_datetime(dct):
    """自动识别 ISO 格式的时间字符串并转回 datetime"""
    for key, value in dct.items():
        if isinstance(value, str) and 'T' in value:
            try:
                dct[key] = datetime.fromisoformat(value)
            except ValueError:
                pass
    return dct

obj = json.loads(json_str, object_hook=decode_datetime)

# orjson 用法示例
import orjson

data = {'name': '张三', 'age': 25}
json_bytes = orjson.dumps(data)          # 返回 bytes
json_str = json_bytes.decode('utf-8')    # 转为 str

# orjson 自动处理 datetime
from datetime import datetime
data = {'ts': datetime.now()}
json_bytes = orjson.dumps(data)          # 直接序列化，无需自定义 Encoder

import re

# re.IGNORECASE (re.I) - 忽略大小写
re.search(r'hello', 'HELLO', re.I)        # 匹配成功

# re.MULTILINE (re.M) - ^ 和 $ 匹配每行的开头和结尾
text = "第一行\n第二行\n第三行"
re.findall(r'^第\w+行', text, re.M)        # ['第一行', '第二行', '第三行']

# re.DOTALL (re.S) - . 也匹配换行符
re.search(r'a.*b', 'a\nb', re.S)          # 匹配成功

# re.VERBOSE (re.X) - 允许注释和空白，提高可读性
pattern = re.compile(r'''
    \d{3}      # 区号
    -?         # 可选的连字符
    \d{4}      # 前四位
    -?         # 可选的连字符
    \d{4}      # 后四位
''', re.X)

import re

# ── 普通分组 ──────────────────────────────────────
date_pattern = r'(\d{4})-(\d{2})-(\d{2})'
match = re.match(date_pattern, '2024-01-15')
match.group(0)    # '2024-01-15'（完整匹配）
match.group(1)    # '2024'（年）
match.group(2)    # '01'（月）
match.groups()    # ('2024', '01', '15')

# ── 命名分组（推荐）──────────────────────────────
named_pattern = r'(?P<year>\d{4})-(?P<month>\d{2})-(?P<day>\d{2})'
match = re.match(named_pattern, '2024-01-15')
match.group('year')      # '2024'
match.groupdict()        # {'year': '2024', 'month': '01', 'day': '15'}

# ── 替换中引用分组 ─────────────────────────────────
# 隐藏手机号中间四位
phone = '13812345678'
hidden = re.sub(r'(\d{3})\d{4}(\d{4})', r'\1****\2', phone)
print(hidden)             # '138****5678'

import re

# 频繁使用的正则表达式应编译为 Pattern 对象
# 内部缓存机制：re 模块会缓存最近 _MAXCACHE (64) 个编译结果
# 但显式编译更清晰，且避免缓存失效

# ✅ 编译一次，多次使用
phone_re = re.compile(r'1[3-9]\d{9}')
texts = ['手机: 13812345678', '电话: 18987654321']
for text in texts:
    match = phone_re.search(text)
    if match:
        print(match.group())

# ✅ 使用回调函数进行高级替换
def double_num(match):
    return str(int(match.group()) * 2)

result = re.sub(r'\d+', double_num, 'Hello 123 World 456')
print(result)  # 'Hello 246 World 912'

import itertools
import operator

# ── 管道式处理：惰性计算，内存极低 ──────────────────
result = list(
    itertools.islice(                       # 第3步：取前 10 个
        itertools.accumulate(               # 第2步：累积求和
            itertools.filterfalse(          # 第1步：过滤偶数
                lambda x: x % 2 == 0,
                range(100)
            )
        ),
        10
    )
)
print(result)  # [1, 4, 9, 16, 25, 36, 49, 64, 81, 100]

# ── groupby：按键分组（必须先排序！）───────────────
data = [('a', 1), ('a', 2), ('b', 1), ('b', 2), ('a', 3)]
data.sort(key=lambda x: x[0])  # ⚠️ 必须先排序！

for key, group in itertools.groupby(data, key=lambda x: x[0]):
    print(key, list(group))
# a [('a', 1), ('a', 2)]
# b [('b', 1), ('b', 2)]
# a [('a', 3)]

# ── chain.from_iterable：优雅的扁平化 ──────────────
nested = [[1, 2, 3], [4, 5], [6, 7, 8, 9]]
flat = list(itertools.chain.from_iterable(nested))
print(flat)  # [1, 2, 3, 4, 5, 6, 7, 8, 9]

# ── product：笛卡尔积 ─────────────────────────────
suits = ['♠', '♥', '♦', '♣']
ranks = ['A', '2', '3', 'K']
deck = list(itertools.product(ranks, suits))
print(len(deck))  # 52

import functools
import time

# ── 基本用法 ──────────────────────────────────────
@functools.lru_cache(maxsize=128)
def fibonacci(n):
    if n < 2:
        return n
    return fibonacci(n-1) + fibonacci(n-2)

print(fibonacci(100))                   # 瞬间完成（无缓存时指数级慢）
print(fibonacci.cache_info())
# CacheInfo(hits=98, misses=101, maxsize=128, currsize=101)

# ── maxsize 选择策略 ─────────────────────────────
# maxsize=None  → 无限缓存，适合参数空间有限且命中率高的场景
# maxsize=128   → 默认值，适合大多数场景
# maxsize=2**n  → LRU 内部用双向链表，2 的幂次方性能更优

# ── cache_info 诊断 ──────────────────────────────
info = fibonacci.cache_info()
hit_rate = info.hits / (info.hits + info.misses) if info.hits + info.misses else 0
print(f"命中率: {hit_rate:.1%}")

# ── 线程安全 ──────────────────────────────────────
# lru_cache 是线程安全的：更新操作由 GIL 保护
# 但如果缓存函数本身有副作用，仍需自行加锁

# ── 清除缓存 ──────────────────────────────────────
fibonacci.cache_clear()

import functools

# ── partial：固定部分参数 ──────────────────────────
def power(base, exp):
    return base ** exp

square = functools.partial(power, exp=2)     # 固定 exp=2
cube = functools.partial(power, exp=3)       # 固定 exp=3
print(square(4))   # 16
print(cube(3))     # 27

# 实际应用：固定 API 参数
import json
json_utf8 = functools.partial(json.dumps, ensure_ascii=False, indent=2)
print(json_utf8({'name': '张三'}))
# {
#   "name": "张三"
# }

# ── wraps：保留被装饰函数的元数据 ──────────────────
def my_decorator(func):
    @functools.wraps(func)  # ← 必须！否则 __name__ 变成 'wrapper'
    def wrapper(*args, **kwargs):
        print("函数调用前")
        result = func(*args, **kwargs)
        print("函数调用后")
        return result
    return wrapper

@my_decorator
def greet(name):
    """问候函数"""
    return f"Hello, {name}!"

print(greet.__name__)   # 'greet'（不是 'wrapper'）
print(greet.__doc__)    # '问候函数'

import functools

@functools.singledispatch
def process(obj):
    """通用处理函数——根据第一个参数的类型自动分派"""
    raise NotImplementedError(f"不支持的类型: {type(obj)}")

@process.register
def _(obj: int):
    return f"处理整数: {obj * 2}"

@process.register
def _(obj: str):
    return f"处理字符串: {obj.upper()}"

@process.register
def _(obj: list):
    return f"处理列表: 长度 {len(obj)}"

print(process(10))          # '处理整数: 20'
print(process("hello"))     # '处理字符串: HELLO'
print(process([1, 2, 3]))   # '处理列表: 长度 3'

from pathlib import Path

# ── 路径拼接（使用 / 运算符，比 os.path.join 更直观）──
base = Path('/Users/docs')
data_dir = base / 'project' / 'data'
config = base / 'config' / 'app.json'

# ── 文件读写（一行代码完成）──────────────────────────
# 写入
Path('output.txt').write_text('Hello, World!', encoding='utf-8')

# 读取
content = Path('output.txt').read_text(encoding='utf-8')

# 追加（需用 open 方法）
with Path('output.txt').open('a', encoding='utf-8') as f:
    f.write('\nNew line')

# ── 目录遍历 ──────────────────────────────────────
# 遍历直接子项
for item in Path('data').iterdir():
    if item.is_file():
        print(f"文件: {item.name} ({item.stat().st_size} bytes)")
    elif item.is_dir():
        print(f"目录: {item.name}/")

# 递归查找所有 Python 文件
for py_file in Path('.').rglob('*.py'):
    print(py_file)

# ── 批量操作 ──────────────────────────────────────
# 查找并处理所有日志文件
for log_file in Path('logs').glob('*.log'):
    content = log_file.read_text()
    if 'ERROR' in content:
        error_log = Path('errors') / log_file.name
        error_log.parent.mkdir(parents=True, exist_ok=True)
        error_log.write_text(content)

from typing import (
    Optional, Union, Callable, TypeVar, Generic,
    Protocol, TypeAlias, Final, Literal, TypedDict, Any, Never,
)

# ═══════════════════════════════════════════════════
# 基础类型注解
# ═══════════════════════════════════════════════════

# Python 3.9+ 使用内置泛型（推荐）
def process_items(
    items: list[str],           # 字符串列表
    mapping: dict[str, int],    # 字符串→整数的映射
    unique: set[int],           # 整数集合
    pair: tuple[str, int],      # 固定结构元组
) -> None:
    pass

# ═══════════════════════════════════════════════════
# Optional 与 Union
# ═══════════════════════════════════════════════════

# Python 3.10+ 新语法（推荐）
def find_user(user_id: int) -> str | None:
    users = {1: 'Alice', 2: 'Bob'}
    return users.get(user_id)

def process(value: int | str | float) -> str:
    return str(value)

# ═══════════════════════════════════════════════════
# Callable 可调用类型
# ═══════════════════════════════════════════════════

def apply_function(
    func: Callable[[int, int], int],  # 接受两个 int，返回 int
    a: int,
    b: int,
) -> int:
    return func(a, b)

# ═══════════════════════════════════════════════════
# TypeVar 与 Generic
# ═══════════════════════════════════════════════════

T = TypeVar('T')

def first_item(items: list[T]) -> T:
    """返回列表第一个元素，保持类型"""
    return items[0]

class Stack(Generic[T]):
    def __init__(self) -> None:
        self._items: list[T] = []

    def push(self, item: T) -> None:
        self._items.append(item)

    def pop(self) -> T:
        return self._items.pop()

# ═══════════════════════════════════════════════════
# Protocol 协议（结构化子类型）
# ═══════════════════════════════════════════════════

class SupportsLength(Protocol):
    def __len__(self) -> int: ...

def get_size(obj: SupportsLength) -> int:
    return len(obj)

# 任何有 __len__ 方法的类型都兼容
get_size([1, 2, 3])    # OK
get_size("hello")      # OK

# ═══════════════════════════════════════════════════
# Literal 与 TypedDict
# ═══════════════════════════════════════════════════

def set_mode(mode: Literal['read', 'write', 'append']) -> None:
    pass

set_mode('read')    # OK
# set_mode('delete')  # 类型检查错误！

class UserDict(TypedDict):
    name: str
    age: int
    active: bool

user: UserDict = {'name': 'Alice', 'age': 25, 'active': True}

import json
from pathlib import Path
from datetime import datetime

class AppConfig:
    """类型安全的配置管理器"""

    CONFIG_PATH = Path('config.json')

    def __init__(self) -> None:
        self.config: dict = self._load()

    def _load(self) -> dict:
        """加载配置文件"""
        if not self.CONFIG_PATH.exists():
            return self._default_config()
        return json.loads(self.CONFIG_PATH.read_text(encoding='utf-8'))

    def _save(self) -> None:
        """保存配置文件"""
        self.CONFIG_PATH.write_text(
            json.dumps(self.config, ensure_ascii=False, indent=2),
            encoding='utf-8',
        )

    @staticmethod
    def _default_config() -> dict:
        return {
            'app_name': 'MyApp',
            'version': '1.0.0',
            'created_at': datetime.now().isoformat(),
            'debug': False,
        }

    def get(self, key: str, default=None):
        return self.config.get(key, default)

    def set(self, key: str, value) -> None:
        self.config[key] = value
        self._save()

# 使用
config = AppConfig()
print(config.get('app_name'))     # 'MyApp'
config.set('debug', True)          # 自动持久化

import itertools
import functools
import operator
from collections import Counter

# 统计文本中每个单词的词频，取前 N 个高频词
def top_words(text: str, n: int = 10) -> list[tuple[str, int]]:
    words = text.lower().split()
    word_counts = Counter(words)
    return word_counts.most_common(n)

# 使用 itertools 管道处理多文件
def process_files(directory: str, pattern: str = '*.txt') -> dict:
    from pathlib import Path

    # 管道：遍历文件 → 读取文本 → 统计词频 → 合并结果
    files = Path(directory).glob(pattern)
    all_words: list[str] = []

    for file_path in files:
        text = file_path.read_text(encoding='utf-8')
        words = text.lower().split()
        all_words.extend(words)

    # 使用 itertools + functools 进行高级统计
    total = len(all_words)
    unique = len(set(all_words))
    top = Counter(all_words).most_common(10)

    return {'total': total, 'unique': unique, 'top': top}

# ═══════════════════════════════════════════════════
# PEP 8 推荐的导入分组（组间空一行）
# ═══════════════════════════════════════════════════

# 第1组：标准库
import json
import re
from datetime import datetime, timedelta
from pathlib import Path

# 第2组：第三方库
import requests
from bs4 import BeautifulSoup

# 第3组：本地模块
from myapp.config import settings
from myapp.utils import helper