1. 学习路线总览

入门基础          →  进阶提升          →  专业方向
┌─────────┐       ┌─────────┐         ┌──────────┐
│ 语法基础 │       │ 面向对象 │         │ Web 开发  │
│ 数据类型 │       │ 装饰器   │         │ 数据分析  │
│ 流程控制 │  ──→  │ 生成器   │   ──→   │ 自动化运维│
│ 函数     │       │ 并发编程 │         │ 机器学习  │
│ 文件IO   │       │ 标准库   │         │ 爬虫     │
└─────────┘       └─────────┘         └──────────┘

1.1 分阶段路线

2. 核心知识图谱

2.1 必须扎实掌握

语言核心：
├── 数据类型（list / dict / set / tuple / str）
├── 控制流（if / for / while / break / continue）
├── 函数（参数 / 返回值 / 作用域 / 闭包）
├── 面向对象（类 / 继承 / 多态 / 魔术方法）
├── 异常处理（try/except/finally / 自定义异常）
├── 文件操作（读写 / 上下文管理器）
├── 模块与包（import / __init__.py / 相对导入）
└── 迭代协议（迭代器 / 生成器 / yield）

2.2 进阶必备

高级特性：
├── 装饰器（函数装饰器 / 类装饰器 / 带参数）
├── 上下文管理器（__enter__ / __exit__ / contextlib）
├── 描述符（__get__ / __set__ / __delete__）
├── 元类（type / __init_subclass__ / metaclass）
├── 反射（getattr / hasattr / __getattr__）
├── 类型提示（typing / Generic / Protocol）
└── 数据类（dataclass / pydantic）

2.3 并发编程

并发模型：
├── 多线程（threading / GIL / 线程池）
├── 多进程（multiprocessing / 进程池 / 进程通信）
├── 异步 IO（asyncio / await / Task / 事件循环）
└── 并发工具（concurrent.futures / queue / Lock）

3. 专业方向选择

3.1 Web 后端开发

技术栈：
├── 框架：FastAPI（推荐）/ Django / Flask
├── 数据库：PostgreSQL / MySQL + SQLAlchemy
├── 缓存：Redis
├   消息队列：Celery + RabbitMQ
├── 部署：Docker + Gunicorn + Nginx
└── 监控：Prometheus + Grafana

进阶路线：
1. 掌握一个框架（FastAPI）
2. 学习数据库设计与 ORM
3. 理解 RESTful / GraphQL API 设计
4. 学习认证授权（JWT / OAuth2）
5. 实践微服务架构

3.2 数据分析与科学计算

技术栈：
├── 核心：NumPy / Pandas
├── 可视化：Matplotlib / Seaborn / Plotly
├── 机器学习：Scikit-learn
├   深度学习：PyTorch / TensorFlow
├── 数据处理：Jupyter Notebook
└── 大数据：PySpark / Dask

进阶路线：
1. 熟练 Pandas 数据操作
2. 掌握统计基础与数据可视化
3. 学习 Scikit-learn 经典算法
4. 深入 PyTorch 深度学习
5. 实践端到端数据项目

3.3 自动化与运维

技术栈：
├── 脚本：Python 标准库 / Click / Typer
├── 自动化：Selenium / Playwright
├   运维：Ansible / Fabric
├── 定时任务：APScheduler / Celery Beat
├── 监控：psutil / logging
└── 配置管理：pydantic-settings

3.4 爬虫与数据采集

技术栈：
├── 请求：requests / httpx / aiohttp
├── 解析：BeautifulSoup / lxml / parsel
├── 框架：Scrapy
├   动态页面：Playwright / Selenium
├── 反爬：代理池 / 验证码识别 / 指纹伪装
└── 存储：SQLite / MongoDB / Elasticsearch

4. 推荐书籍

4.1 入门到进阶

4.2 专业方向

5. 在线文档与资源

5.1 官方文档

Python 官方文档      https://docs.python.org/zh-cn/3/
PEP 索引            https://peps.python.org/
FastAPI 文档         https://fastapi.tiangolo.com/zh/
Django 文档          https://docs.djangoproject.com/zh-hans/
Flask 文档           https://dormousehole.readthedocs.io/
Pandas 文档          https://pandas.pydata.org/docs/

5.2 学习平台

Real Python          https://realpython.com/      （高质量教程）
PyCoder's Weekly     https://pycoders.com/         （每周周刊）
Python Weekly        https://www.pythonweekly.com/ （新闻聚合）
Stack Overflow       https://stackoverflow.com/    （问答社区）

5.3 中文资源

廖雪峰 Python 教程   https://liaoxuefeng.com/books/python/
菜鸟教程             https://www.runoob.com/python3/
掘金 / SegmentFault  技术社区

6. 优质开源项目学习

6.1 阅读源码提升

6.2 参与开源

# 1. 从 Good First Issue 开始
#    GitHub 搜索 label:"good first issue" language:Python

# 2. 阅读贡献指南（CONTRIBUTING.md）

# 3. 从文档改进、Bug 修复开始

# 4. 逐步参与功能开发

7. 编码能力提升方法

7.1 刷题练习

LeetCode        https://leetcode.cn/        （算法面试）
HackerRank      https://www.hackerrank.com/  （Python 专项）
Codewars        https://www.codewars.com/    （游戏化练习）
Exercism        https://exercism.org/        （代码评审）

建议：
- 每日 1-2 题，坚持 3 个月
- 先独立思考，再看题解
- 注重时间/空间复杂度分析

7.2 项目实战

进阶项目建议（由易到难）：

1. 命令行待办工具（argparse + JSON 存储）
2. 个人博客系统（FastAPI + SQLite）
3. 股票数据分析仪表盘（Pandas + Plotly）
4. 分布式爬虫系统（Scrapy + Redis）
5. 即时聊天应用（WebSocket + asyncio）
6. 微服务电商后台（FastAPI + Docker + PostgreSQL）

7.3 代码审查

# 审查自己代码的检查清单：

# □ 命名是否清晰（变量、函数、类）
# □ 函数是否单一职责（不超过 30 行）
# □ 是否有类型提示
# □ 异常是否被正确处理
# □ 是否有重复代码（DRY 原则）
# □ 是否有单元测试
# □ 是否通过 ruff / mypy 检查
# □ 复杂逻辑是否有注释说明

8. Python 版本与生态趋势

3.1 近年重要特性

3.2 值得关注的新工具

uv        → 超快包管理（替代 pip/pip-tools）
ruff      → 超快 linter + formatter（替代 flake8/black/isort）
mypy      → 静态类型检查
pydantic  → 数据校验（v2 基于 Rust，性能大幅提升）

9. 持续学习建议

9.1 制定计划

每周学习节奏建议：

周一~周五：每天 1 小时
├── 30 分钟：学习新知识 / 阅读文档
└── 30 分钟：动手编码练习

周末：2-3 小时
├── 完整项目实战
└── 总结复盘 + 写技术笔记

9.2 知识管理

建立个人知识库：

1. 用 Markdown 记录学习笔记
2. GitHub 维护代码示例仓库
3. 写技术博客（输出倒逼输入）
4. 定期回顾与重构旧代码
5. 关注 PEP 提案，了解语言演进

9.3 社区参与

- 加入 Python 中文社区 / 本地 PyCon
- 参与开源项目贡献
- 在 Stack Overflow 回答问题
- 技术分享（公司内部 / 线上直播）

10. 小结

学习没有捷径，但方向比速度更重要。 扎实基础 → 选择方向 → 深度实战 → 持续输出，这是最可靠的成长路径。

]]> https://example.com/posts/language/python-54-python%E9%A1%B9%E7%9B%AE%E6%9C%80%E4%BD%B3%E5%AE%9E%E8%B7%B5/ Sat, 27 Dec 2025 00:00:00 +0000 ixiaoqiang0011@gmail.com (星辰逐梦) https://example.com/posts/language/python-54-python%E9%A1%B9%E7%9B%AE%E6%9C%80%E4%BD%B3%E5%AE%9E%E8%B7%B5/ 学习目标：掌握 Python 项目的工程化最佳实践，涵盖目录结构、配置管理、依赖锁定、部署上线与 CI/CD。

---

1. 项目目录结构

1.1 标准结构

my_project/
├── pyproject.toml        # 项目元数据与依赖（现代标准）
├── requirements.txt      # 依赖锁定（兼容传统工具）
├── README.md             # 项目说明
├── .gitignore            # Git 忽略规则
├── .env.example          # 环境变量示例
├── Makefile              # 常用命令快捷方式
├── src/                  # 源码目录
│   └── my_package/
│       ├── __init__.py
│       ├── core/         # 核心逻辑
│       ├── models/       # 数据模型
│       ├── services/     # 业务服务
│       └── utils/        # 工具函数
├── tests/                # 测试目录
│   ├── conftest.py       # pytest 固件
│   ├── unit/             # 单元测试
│   └── integration/      # 集成测试
├── docs/                 # 文档
└── scripts/              # 脚本工具

1.2 使用 src 布局的好处

# src 布局强制安装后才可导入，避免测试误用本地路径

# 传统布局（不推荐）
my_package/
    __init__.py
tests/
    test_xxx.py   # 可能直接 import my_package（未安装状态）

# src 布局（推荐）
src/
    my_package/
        __init__.py
tests/
    test_xxx.py   # 必须先 pip install -e . 才能导入

---

2. 项目配置

2.1 pyproject.toml（推荐）

# pyproject.toml
[build-system]
requires = ["setuptools>=68.0", "wheel"]
build-backend = "setuptools.backends._legacy:_Backend"

[project]
name = "my-package"
version = "1.0.0"
description = "我的 Python 项目"
requires-python = ">=3.10"
dependencies = [
    "requests>=2.31",
    "pydantic>=2.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0",
    "pytest-cov>=4.0",
    "ruff>=0.1",
    "mypy>=1.5",
]

[project.scripts]
my-tool = "my_package.cli:main"

# ruff 配置
[tool.ruff]
line-length = 100
target-version = "py310"

[tool.ruff.lint]
select = ["E", "F", "I", "N", "W"]

# pytest 配置
[tool.pytest.ini_options]
testpaths = ["tests"]
addopts = "-v --cov=my_package --cov-report=term-missing"

2.2 环境变量管理

# config.py
from pydantic_settings import BaseSettings
from functools import lru_cache


class Settings(BaseSettings):
    """应用配置（从环境变量读取）"""
    app_name: str = "My App"
    debug: bool = False
    database_url: str = "sqlite:///./app.db"
    secret_key: str = "change-me"
    api_timeout: int = 30

    class Config:
        env_file = ".env"
        env_file_encoding = "utf-8"


@lru_cache
def get_settings() -> Settings:
    """单例配置（缓存）"""
    return Settings()


# 使用
settings = get_settings()
print(settings.database_url)

# .env
DEBUG=true
DATABASE_URL=postgresql://user:pass@localhost:5432/mydb
SECRET_KEY=your-production-secret

---

3. 依赖管理

3.1 使用 pip-tools 锁定依赖

# 安装
pip install pip-tools

# 编写 requirements.in（顶层依赖）
# requirements.in
fastapi
uvicorn[standard]
sqlalchemy

# 编译生成锁定的 requirements.txt
pip-compile requirements.in -o requirements.txt

# 安装精确版本
pip-sync requirements.txt

3.2 使用 uv（高性能替代）

# 安装 uv（Rust 编写，极快）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建项目
uv init my_project
cd my_project

# 添加依赖
uv add fastapi uvicorn sqlalchemy
uv add --dev pytest ruff mypy

# 同步环境
uv sync

# 运行
uv run pytest

---

4. 日志与配置

4.1 结构化日志

# logging_config.py
import logging
import sys
from pathlib import Path


def setup_logging(log_file: str = "app.log", level: str = "INFO"):
    """配置日志"""
    log_format = "%(asctime)s | %(levelname)-8s | %(name)s | %(message)s"
    date_format = "%Y-%m-%d %H:%M:%S"

    # 控制台 + 文件双输出
    logging.basicConfig(
        level=level,
        format=log_format,
        datefmt=date_format,
        handlers=[
            logging.StreamHandler(sys.stdout),
            logging.FileHandler(log_file, encoding='utf-8'),
        ],
    )

    # 降低第三方库日志级别
    logging.getLogger("urllib3").setLevel(logging.WARNING)


# 使用
logger = logging.getLogger(__name__)
setup_logging()
logger.info("服务启动")
logger.error("数据库连接失败", exc_info=True)

4.2 使用 loguru（更简洁）

from loguru import logger

# 自动带颜色、时间、文件位置
logger.info("用户登录: user_id={}", 123)

# 输出到文件并自动轮转
logger.add("app.log", rotation="10 MB", retention="7 days", encoding="utf-8")

# JSON 格式（便于日志收集）
logger.add("app.json", serialize=True)

try:
    1 / 0
except Exception:
    logger.exception("计算失败")

---

5. 错误处理架构

# errors.py
from enum import Enum
from dataclasses import dataclass


class ErrorCode(Enum):
    SUCCESS = 0
    PARAM_ERROR = 1001
    NOT_FOUND = 1002
    UNAUTHORIZED = 1003
    SERVER_ERROR = 5000


@dataclass
class AppError(Exception):
    """应用统一异常"""
    code: ErrorCode
    message: str

    def __post_init__(self):
        super().__init__(self.message)


# 业务中使用
def get_user(user_id: int, db):
    user = db.query(User).get(user_id)
    if not user:
        raise AppError(ErrorCode.NOT_FOUND, f"用户 {user_id} 不存在")
    return user


# 统一捕获
def handle_errors(func):
    """错误处理装饰器"""
    from functools import wraps
    @wraps(func)
    def wrapper(*args, **kwargs):
        try:
            result = func(*args, **kwargs)
            return {"code": 0, "message": "success", "data": result}
        except AppError as e:
            return {"code": e.code.value, "message": e.message, "data": None}
        except Exception as e:
            logger.exception("未预期错误")
            return {"code": 5000, "message": "服务器错误", "data": None}
    return wrapper

---

6. 部署上线

6.1 Docker 容器化

# Dockerfile
FROM python:3.12-slim

WORKDIR /app

# 安装依赖（利用缓存层）
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# 拷贝源码
COPY src/ ./src/
COPY pyproject.toml .

# 安装项目
RUN pip install -e .

EXPOSE 8000

CMD ["uvicorn", "my_package.main:app", "--host", "0.0.0.0", "--port", "8000"]

# docker-compose.yml
version: "3.8"

services:
  api:
    build: .
    ports:
      - "8000:8000"
    environment:
      - DATABASE_URL=postgresql://user:pass@db:5432/mydb
    depends_on:
      - db

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: mydb
    volumes:
      - pgdata:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine

volumes:
  pgdata:

# 构建并启动
docker-compose up -d --build

6.2 Gunicorn + Uvicorn 生产部署

# 安装
pip install gunicorn uvicorn[standard]

# 多 worker 部署
gunicorn my_package.main:app \
    -w 4 \
    -k uvicorn.workers.UvicornWorker \
    --bind 0.0.0.0:8000 \
    --timeout 120 \
    --access-logfile - \
    --error-logfile -

---

7. CI/CD 自动化

7.1 GitHub Actions

# .github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        python-version: ["3.10", "3.11", "3.12"]

    steps:
      - uses: actions/checkout@v4

      - name: 安装 Python
        uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}

      - name: 安装依赖
        run: |
          pip install -e ".[dev]"

      - name: 代码检查
        run: |
          ruff check src/ tests/
          mypy src/

      - name: 运行测试
        run: pytest --cov

      - name: 上传覆盖率
        uses: codecov/codecov-action@v4

7.2 Makefile 快捷命令

# Makefile
.PHONY: install test lint format type-check clean

install:
	pip install -e ".[dev]"

test:
	pytest -v --cov

lint:
	ruff check src/ tests/

format:
	ruff format src/ tests/
	ruff check --fix src/ tests/

type-check:
	mypy src/

clean:
	find . -type d -name __pycache__ -exec rm -rf {} +
	find . -type d -name .pytest_cache -exec rm -rf {} +
	rm -rf .coverage htmlcov dist build *.egg-info

make install   # 安装
make test      # 测试
make lint      # 检查
make format    # 格式化

---

8. 性能优化要点

# 1. 使用 __slots__ 减少内存
class Point:
    __slots__ = ('x', 'y')
    def __init__(self, x, y):
        self.x = x
        self.y = y

# 2. 使用生成器处理大数据
def read_large_file(path):
    with open(path) as f:
        for line in f:
            yield line.strip()

# 3. 字符串拼接用 join
parts = ['a', 'b', 'c']
result = ''.join(parts)  # 比 += 快

# 4. 使用局部变量加速循环
def process(data):
    append = result.append  # 局部引用
    for item in data:
        append(item * 2)

# 5. 缓存计算结果
from functools import lru_cache

@lru_cache(maxsize=128)
def fibonacci(n):
    if n < 2:
        return n
    return fibonacci(n - 1) + fibonacci(n - 2)

---

9. 小结

维度	推荐方案
项目结构	src 布局 + pyproject.toml
依赖管理	uv / pip-tools 锁定版本
配置管理	pydantic-settings + .env
日志	loguru 或标准 logging
代码质量	ruff + mypy + pytest
容器化	Docker + docker-compose
生产部署	Gunicorn + Uvicorn
CI/CD	GitHub Actions

---

10. 练习题

1. 将之前的 API 项目改造为 src 布局，使用 pyproject.toml 管理依赖。
2. 为项目编写 Dockerfile 和 docker-compose.yml，实现一键部署。
3. 配置 GitHub Actions，实现推送代码自动运行 lint 和测试。
4. 使用 Makefile 整合 install、test、lint、format 命令。

---

下节预告：我们将梳理 Python 学习路线与推荐资源，为持续进阶指明方向。

]]> https://example.com/posts/language/python-53-restful-api%E5%AE%9E%E6%88%98/ Wed, 24 Dec 2025 00:00:00 +0000 ixiaoqiang0011@gmail.com (星辰逐梦) https://example.com/posts/language/python-53-restful-api%E5%AE%9E%E6%88%98/ 学习目标：使用 FastAPI 开发一个完整的 RESTful API 服务，掌握路由设计、数据校验、认证授权与自动文档。

---

1. RESTful 设计原则

1.1 核心概念

REST = Representational State Transfer（表现层状态转化）

资源（Resource）→ 用 URI 标识，如 /users/1
操作（Action）  → 用 HTTP 方法表达

GET    /users      → 获取用户列表
GET    /users/1    → 获取单个用户
POST   /users      → 创建用户
PUT    /users/1    → 更新用户（全量）
PATCH  /users/1    → 更新用户（部分）
DELETE /users/1    → 删除用户

1.2 HTTP 状态码

状态码	含义	场景
200	OK	请求成功
201	Created	资源创建成功
204	No Content	删除成功
400	Bad Request	参数错误
401	Unauthorized	未认证
403	Forbidden	无权限
404	Not Found	资源不存在
422	Unprocessable Entity	数据校验失败
500	Internal Server Error	服务器错误

---

2. 项目搭建

2.1 目录结构

api_project/
├── main.py            # 入口
├── config.py          # 配置
├── database.py        # 数据库连接
├── models.py          # 数据模型
├── schemas.py         # 请求/响应模型
├── auth.py            # 认证逻辑
├── routers/
│   ├── __init__.py
│   ├── users.py       # 用户路由
│   └── items.py       # 商品路由
└── requirements.txt

2.2 安装依赖

pip install fastapi uvicorn[standard] sqlalchemy pydantic python-jose[cryptography] passlib[bcrypt]

# 启动开发服务器
uvicorn main:app --reload --port 8000

---

3. 数据库与模型

3.1 数据库连接

# database.py
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker, declarative_base

SQLALCHEMY_DATABASE_URL = "sqlite:///./app.db"

engine = create_engine(
    SQLALCHEMY_DATABASE_URL,
    connect_args={"check_same_thread": False}  # SQLite 专用
)

SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
Base = declarative_base()


def get_db():
    """数据库会话依赖"""
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

3.2 数据模型

# models.py
from sqlalchemy import Column, Integer, String, Float, Boolean, ForeignKey
from sqlalchemy.orm import relationship
from database import Base


class User(Base):
    __tablename__ = "users"

    id = Column(Integer, primary_key=True, index=True)
    username = Column(String(50), unique=True, index=True, nullable=False)
    email = Column(String(100), unique=True, nullable=False)
    hashed_password = Column(String(200), nullable=False)
    is_active = Column(Boolean, default=True)
    items = relationship("Item", back_populates="owner")


class Item(Base):
    __tablename__ = "items"

    id = Column(Integer, primary_key=True, index=True)
    name = Column(String(100), nullable=False)
    description = Column(String(500))
    price = Column(Float, nullable=False)
    owner_id = Column(Integer, ForeignKey("users.id"))
    owner = relationship("User", back_populates="items")

3.3 Pydantic 模型

# schemas.py
from pydantic import BaseModel, EmailStr, Field
from datetime import datetime
from typing import Optional


# ---- 请求模型 ----
class UserCreate(BaseModel):
    username: str = Field(..., min_length=3, max_length=50)
    email: EmailStr
    password: str = Field(..., min_length=6)


class UserUpdate(BaseModel):
    email: Optional[EmailStr] = None
    is_active: Optional[bool] = None


class ItemCreate(BaseModel):
    name: str = Field(..., min_length=1, max_length=100)
    description: Optional[str] = None
    price: float = Field(..., gt=0)


class ItemUpdate(BaseModel):
    name: Optional[str] = None
    description: Optional[str] = None
    price: Optional[float] = Field(None, gt=0)


# ---- 响应模型 ----
class UserResponse(BaseModel):
    id: int
    username: str
    email: str
    is_active: bool

    class Config:
        from_attributes = True  # ORM 模式


class ItemResponse(BaseModel):
    id: int
    name: str
    description: Optional[str]
    price: float
    owner_id: int

    class Config:
        from_attributes = True


class Token(BaseModel):
    access_token: str
    token_type: str

---

4. 认证授权

# auth.py
from datetime import datetime, timedelta
from jose import JWTError, jwt
from passlib.context import CryptContext
from fastapi import Depends, HTTPException, status
from fastapi.security import OAuth2PasswordBearer
from sqlalchemy.orm import Session
from database import get_db
import models

SECRET_KEY = "your-secret-key-change-in-production"
ALGORITHM = "HS256"
ACCESS_TOKEN_EXPIRE_MINUTES = 60

pwd_context = CryptContext(schemes=["bcrypt"], deprecated="auto")
oauth2_scheme = OAuth2PasswordBearer(tokenUrl="token")


def hash_password(password: str) -> str:
    return pwd_context.hash(password)


def verify_password(plain: str, hashed: str) -> bool:
    return pwd_context.verify(plain, hashed)


def create_access_token(data: dict) -> str:
    to_encode = data.copy()
    expire = datetime.utcnow() + timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
    to_encode.update({"exp": expire})
    return jwt.encode(to_encode, SECRET_KEY, algorithm=ALGORITHM)


def get_current_user(
    token: str = Depends(oauth2_scheme),
    db: Session = Depends(get_db),
) -> models.User:
    """获取当前认证用户"""
    credentials_exception = HTTPException(
        status_code=status.HTTP_401_UNAUTHORIZED,
        detail="无法验证凭据",
        headers={"WWW-Authenticate": "Bearer"},
    )
    try:
        payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
        username: str = payload.get("sub")
        if username is None:
            raise credentials_exception
    except JWTError:
        raise credentials_exception

    user = db.query(models.User).filter(models.User.username == username).first()
    if user is None:
        raise credentials_exception
    return user

---

5. 路由实现

5.1 认证路由

# routers/auth.py
from fastapi import APIRouter, Depends, HTTPException, status
from fastapi.security import OAuth2PasswordRequestForm
from sqlalchemy.orm import Session
from database import get_db
import models, schemas, auth

router = APIRouter(tags=["认证"])


@router.post("/register", response_model=schemas.UserResponse, status_code=201)
def register(user: schemas.UserCreate, db: Session = Depends(get_db)):
    """注册用户"""
    if db.query(models.User).filter(models.User.username == user.username).first():
        raise HTTPException(status_code=400, detail="用户名已存在")
    if db.query(models.User).filter(models.User.email == user.email).first():
        raise HTTPException(status_code=400, detail="邮箱已注册")

    db_user = models.User(
        username=user.username,
        email=user.email,
        hashed_password=auth.hash_password(user.password),
    )
    db.add(db_user)
    db.commit()
    db.refresh(db_user)
    return db_user


@router.post("/token", response_model=schemas.Token)
def login(
    form: OAuth2PasswordRequestForm = Depends(),
    db: Session = Depends(get_db),
):
    """登录获取 Token"""
    user = db.query(models.User).filter(
        models.User.username == form.username
    ).first()
    if not user or not auth.verify_password(form.password, user.hashed_password):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="用户名或密码错误",
        )
    access_token = auth.create_access_token(data={"sub": user.username})
    return {"access_token": access_token, "token_type": "bearer"}

5.2 用户路由

# routers/users.py
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.orm import Session
from typing import List
from database import get_db
import models, schemas, auth

router = APIRouter(prefix="/users", tags=["用户"])


@router.get("/", response_model=List[schemas.UserResponse])
def list_users(skip: int = 0, limit: int = 20, db: Session = Depends(get_db)):
    """获取用户列表"""
    return db.query(models.User).offset(skip).limit(limit).all()


@router.get("/{user_id}", response_model=schemas.UserResponse)
def get_user(user_id: int, db: Session = Depends(get_db)):
    """获取单个用户"""
    user = db.query(models.User).filter(models.User.id == user_id).first()
    if not user:
        raise HTTPException(status_code=404, detail="用户不存在")
    return user


@router.put("/me", response_model=schemas.UserResponse)
def update_profile(
    user_update: schemas.UserUpdate,
    current_user: models.User = Depends(auth.get_current_user),
    db: Session = Depends(get_db),
):
    """更新个人信息"""
    if user_update.email:
        current_user.email = user_update.email
    if user_update.is_active is not None:
        current_user.is_active = user_update.is_active
    db.commit()
    db.refresh(current_user)
    return current_user


@router.delete("/me", status_code=204)
def delete_account(
    current_user: models.User = Depends(auth.get_current_user),
    db: Session = Depends(get_db),
):
    """注销账户"""
    db.delete(current_user)
    db.commit()

5.3 商品路由（含权限控制）

# routers/items.py
from fastapi import APIRouter, Depends, HTTPException
from sqlalchemy.orm import Session
from typing import List
from database import get_db
import models, schemas, auth

router = APIRouter(prefix="/items", tags=["商品"])


@router.get("/", response_model=List[schemas.ItemResponse])
def list_items(skip: int = 0, limit: int = 20, db: Session = Depends(get_db)):
    """获取商品列表（公开）"""
    return db.query(models.Item).offset(skip).limit(limit).all()


@router.post("/", response_model=schemas.ItemResponse, status_code=201)
def create_item(
    item: schemas.ItemCreate,
    current_user: models.User = Depends(auth.get_current_user),
    db: Session = Depends(get_db),
):
    """创建商品（需登录）"""
    db_item = models.Item(**item.model_dump(), owner_id=current_user.id)
    db.add(db_item)
    db.commit()
    db.refresh(db_item)
    return db_item


@router.put("/{item_id}", response_model=schemas.ItemResponse)
def update_item(
    item_id: int,
    item_update: schemas.ItemUpdate,
    current_user: models.User = Depends(auth.get_current_user),
    db: Session = Depends(get_db),
):
    """更新商品（仅拥有者）"""
    item = db.query(models.Item).filter(models.Item.id == item_id).first()
    if not item:
        raise HTTPException(status_code=404, detail="商品不存在")
    if item.owner_id != current_user.id:
        raise HTTPException(status_code=403, detail="无权修改他人商品")

    update_data = item_update.model_dump(exclude_unset=True)
    for field, value in update_data.items():
        setattr(item, field, value)
    db.commit()
    db.refresh(item)
    return item


@router.delete("/{item_id}", status_code=204)
def delete_item(
    item_id: int,
    current_user: models.User = Depends(auth.get_current_user),
    db: Session = Depends(get_db),
):
    """删除商品（仅拥有者）"""
    item = db.query(models.Item).filter(models.Item.id == item_id).first()
    if not item:
        raise HTTPException(status_code=404, detail="商品不存在")
    if item.owner_id != current_user.id:
        raise HTTPException(status_code=403, detail="无权删除他人商品")
    db.delete(item)
    db.commit()

---

6. 主应用入口

# main.py
from fastapi import FastAPI
from database import Base, engine
from routers import auth, users, items

# 创建数据表
Base.metadata.create_all(bind=engine)

app = FastAPI(
    title="商品管理 API",
    description="FastAPI + SQLAlchemy + JWT 认证的 RESTful API 示例",
    version="1.0.0",
)

# 注册路由
app.include_router(auth.router)
app.include_router(users.router)
app.include_router(items.router)


@app.get("/", tags=["根"])
def root():
    return {"message": "欢迎使用商品管理 API", "docs": "/docs"}


@app.get("/health", tags=["根"])
def health_check():
    return {"status": "healthy"}

---

7. 中间件与异常处理

7.1 自定义异常

# main.py 追加
from fastapi import Request
from fastapi.responses import JSONResponse


class BizError(Exception):
    """业务异常"""
    def __init__(self, code: int, message: str):
        self.code = code
        self.message = message


@app.exception_handler(BizError)
async def biz_error_handler(request: Request, exc: BizError):
    return JSONResponse(
        status_code=200,
        content={"code": exc.code, "message": exc.message, "data": None},
    )


# 全局异常兜底
@app.exception_handler(Exception)
async def global_exception_handler(request: Request, exc: Exception):
    return JSONResponse(
        status_code=500,
        content={"code": 500, "message": "服务器内部错误", "data": None},
    )

7.2 请求日志中间件

import time
import logging

logger = logging.getLogger("api")


@app.middleware("http")
async def log_requests(request: Request, call_next):
    start = time.time()
    response = await call_next(request)
    duration = (time.time() - start) * 1000

    logger.info(
        f"{request.method} {request.url.path} "
        f"→ {response.status_code} ({duration:.1f}ms)"
    )
    return response

7.3 统一响应格式

# schemas.py 追加
from typing import TypeVar, Generic, Optional
from pydantic import BaseModel

T = TypeVar("T")


class ApiResponse(BaseModel, Generic[T]):
    """统一响应模型"""
    code: int = 200
    message: str = "success"
    data: Optional[T] = None


# 使用示例
@router.get("/{item_id}", response_model=ApiResponse[schemas.ItemResponse])
def get_item(item_id: int, db: Session = Depends(get_db)):
    item = db.query(models.Item).filter(models.Item.id == item_id).first()
    if not item:
        raise BizError(code=404, message="商品不存在")
    return ApiResponse(data=item)

---

8. 自动文档与测试

8.1 访问交互式文档

启动服务后访问：
- Swagger UI:  http://localhost:8000/docs
- ReDoc:       http://localhost:8000/redoc

8.2 API 测试

# test_api.py
from fastapi.testclient import TestClient
from main import app

client = TestClient(app)


def test_register_and_login():
    """测试注册和登录"""
    # 注册
    resp = client.post("/register", json={
        "username": "testuser",
        "email": "test@example.com",
        "password": "123456",
    })
    assert resp.status_code == 201

    # 登录
    resp = client.post("/token", data={
        "username": "testuser",
        "password": "123456",
    })
    assert resp.status_code == 200
    token = resp.json()["access_token"]
    return token


def test_create_item():
    """测试创建商品"""
    token = test_register_and_login()
    resp = client.post(
        "/items/",
        json={"name": "笔记本电脑", "price": 5999.0},
        headers={"Authorization": f"Bearer {token}"},
    )
    assert resp.status_code == 201
    assert resp.json()["name"] == "笔记本电脑"

# 运行测试
pytest test_api.py -v

---

9. 小结

模块	技术选型
Web 框架	FastAPI（异步、高性能）
数据库 ORM	SQLAlchemy
数据校验	Pydantic
认证授权	JWT（python-jose）+ OAuth2
密码加密	passlib + bcrypt
自动文档	Swagger UI / ReDoc
测试	TestClient + pytest

---

10. 练习题

1. 为商品 API 添加分类（Category）功能，实现商品与分类的一对多关系。
2. 实现分页查询，返回 total、page、items 的分页结构。
3. 添加管理员角色（is_superuser），管理员可删除任何用户的商品。
4. 编写完整的 pytest 测试用例，覆盖所有 API 端点。

---

下节预告：我们将总结 Python 项目的最佳实践，涵盖目录结构、配置管理与部署。

]]> https://example.com/posts/language/python-52-%E6%95%B0%E6%8D%AE%E5%88%86%E6%9E%90%E5%AE%9E%E6%88%98/ Sun, 21 Dec 2025 00:00:00 +0000 ixiaoqiang0011@gmail.com (星辰逐梦) https://example.com/posts/language/python-52-%E6%95%B0%E6%8D%AE%E5%88%86%E6%9E%90%E5%AE%9E%E6%88%98/ 学习目标：使用 pandas 和 matplotlib 进行数据清洗、分析与可视化，完成一个完整的数据分析项目。

---

1. 数据分析工具链

1.1 核心库介绍

pandas      → 数据处理与分析（DataFrame）
numpy       → 数值计算
matplotlib  → 基础绘图
seaborn     → 统计可视化（基于 matplotlib）

1.2 安装依赖

pip install pandas numpy matplotlib seaborn

import pandas as pd
import numpy as np
import matplotlib.pyplot as plt
import seaborn as sns

# 中文显示设置
plt.rcParams['font.sans-serif'] = ['Arial Unicode MS', 'SimHei']
plt.rcParams['axes.unicode_minus'] = False

---

2. 数据加载与概览

2.1 读取数据

import pandas as pd

# 读取 CSV
df = pd.read_csv('sales_data.csv', encoding='utf-8')

# 读取 Excel（需安装 openpyxl）
# df = pd.read_excel('sales_data.xlsx', sheet_name='Sheet1')

# 读取 JSON
# df = pd.read_json('data.json')

print(df.shape)        # (行数, 列数)
print(df.columns)      # 列名
print(df.dtypes)       # 数据类型

2.2 查看数据

# 前 5 行
print(df.head())

# 后 5 行
print(df.tail())

# 随机 3 行
print(df.sample(3))

# 基本信息
df.info()

# 数值列统计描述
print(df.describe())

---

3. 数据清洗

3.1 生成示例数据

import pandas as pd
import numpy as np

# 构造销售数据（含缺失值和异常值）
data = {
    'date': pd.date_range('2024-01-01', periods=100, freq='D'),
    'product': np.random.choice(['手机', '电脑', '耳机', '平板'], 100),
    'region': np.random.choice(['华东', '华北', '华南', '西南'], 100),
    'quantity': np.random.randint(1, 50, 100),
    'price': np.random.uniform(100, 5000, 100).round(2),
}
df = pd.DataFrame(data)
df['amount'] = df['quantity'] * df['price']

# 人为制造缺失值和异常值
df.loc[10:15, 'price'] = np.nan          # 缺失值
df.loc[20, 'amount'] = -999              # 异常值（负数）
df.loc[30, 'quantity'] = 0               # 零值

print(df.info())

3.2 处理缺失值

# 检查缺失值
print(df.isnull().sum())

# 按产品分组，用组内均值填充价格
df['price'] = df.groupby('product')['price'].transform(
    lambda x: x.fillna(x.mean())
)

# 仍有缺失则用全局均值
df['price'].fillna(df['price'].mean(), inplace=True)
print(f"填充后缺失值: {df['price'].isnull().sum()}")

3.3 处理异常值

# 识别异常值（负金额）
print(df[df['amount'] < 0])

# 修正：重新计算
df.loc[df['amount'] < 0, 'amount'] = df['quantity'] * df['price']

# 用 IQR 检测价格异常
Q1 = df['price'].quantile(0.25)
Q3 = df['price'].quantile(0.75)
IQR = Q3 - Q1
lower = Q1 - 1.5 * IQR
upper = Q3 + 1.5 * IQR

outliers = df[(df['price'] < lower) | (df['price'] > upper)]
print(f"价格异常值数量: {len(outliers)}")

# 截断处理
df['price'] = df['price'].clip(lower, upper)

3.4 去重与类型转换

# 去除完全重复行
df.drop_duplicates(inplace=True)

# 类型转换
df['quantity'] = df['quantity'].astype(int)
df['date'] = pd.to_datetime(df['date'])

# 添加派生列
df['month'] = df['date'].dt.month
df['weekday'] = df['date'].dt.day_name()

---

4. 数据分析

4.1 分组聚合

# 按产品统计
product_stats = df.groupby('product').agg(
    总销量=('quantity', 'sum'),
    总金额=('amount', 'sum'),
    平均单价=('price', 'mean'),
    订单数=('amount', 'count'),
).round(2)

print(product_stats)

# 按地区和产品交叉统计
pivot = pd.pivot_table(
    df,
    values='amount',
    index='region',
    columns='product',
    aggfunc='sum',
    fill_value=0,
)
print(pivot)

4.2 时间序列分析

# 设置日期索引
df.set_index('date', inplace=True)

# 按月汇总
monthly = df.resample('M')['amount'].sum()
print(monthly)

# 7 日滑动平均
df['amount_7d_ma'] = df['amount'].rolling(window=7).mean()

# 累计销售额
df['cumsum'] = df['amount'].cumsum()

4.3 排序与筛选

# 销量 TOP 5
top5 = df.nlargest(5, 'amount')[['product', 'region', 'amount']]
print(top5)

# 筛选条件
high_value = df[(df['amount'] > 10000) & (df['region'] == '华东')]
print(f"华东高价值订单: {len(high_value)} 笔")

---

5. 数据可视化

5.1 柱状图

import matplotlib.pyplot as plt

fig, ax = plt.subplots(figsize=(8, 5))

product_stats['总金额'].plot(kind='bar', ax=ax, color='steelblue')
ax.set_title('各产品销售总额')
ax.set_xlabel('产品')
ax.set_ylabel('金额（元）')
ax.tick_params(axis='x', rotation=0)

# 添加数值标签
for i, v in enumerate(product_stats['总金额']):
    ax.text(i, v + 500, f'{v:,.0f}', ha='center', fontsize=9)

plt.tight_layout()
plt.savefig('product_sales.png', dpi=150)
plt.show()

5.2 饼图

# 地区销售占比
region_sales = df.groupby('region')['amount'].sum()

fig, ax = plt.subplots(figsize=(6, 6))
ax.pie(
    region_sales,
    labels=region_sales.index,
    autopct='%1.1f%%',
    startangle=90,
    colors=['#4C72B0', '#DD8452', '#55A467', '#C44E52'],
)
ax.set_title('各地区销售占比')
plt.tight_layout()
plt.savefig('region_pie.png', dpi=150)
plt.show()

5.3 折线图（趋势）

fig, ax = plt.subplots(figsize=(10, 5))
monthly.plot(ax=ax, marker='o', color='steelblue')
ax.set_title('月度销售趋势')
ax.set_xlabel('月份')
ax.set_ylabel('金额（元）')
ax.grid(True, alpha=0.3)
plt.tight_layout()
plt.savefig('monthly_trend.png', dpi=150)
plt.show()

5.4 使用 seaborn 绘制高级图表

import seaborn as sns

# 箱线图：各产品价格分布
fig, ax = plt.subplots(figsize=(8, 5))
sns.boxplot(data=df.reset_index(), x='product', y='price', ax=ax)
ax.set_title('各产品价格分布')
plt.tight_layout()
plt.savefig('price_boxplot.png', dpi=150)
plt.show()

# 热力图：地区×产品销售额
fig, ax = plt.subplots(figsize=(7, 5))
sns.heatmap(pivot, annot=True, fmt='.0f', cmap='YlOrRd', ax=ax)
ax.set_title('地区×产品销售额热力图')
plt.tight_layout()
plt.savefig('sales_heatmap.png', dpi=150)
plt.show()

---

6. 完整分析项目

"""
销售数据分析报告
- 读取数据 → 清洗 → 分析 → 可视化 → 导出报告
"""

import pandas as pd
import matplotlib.pyplot as plt
import numpy as np
from pathlib import Path

plt.rcParams['font.sans-serif'] = ['Arial Unicode MS', 'SimHei']
plt.rcParams['axes.unicode_minus'] = False


class SalesAnalyzer:
    """销售数据分析器"""

    def __init__(self, filepath: str):
        self.df = pd.read_csv(filepath, parse_dates=['date'])
        self.report = {}

    def clean(self) -> 'SalesAnalyzer':
        """数据清洗"""
        # 填充缺失
        self.df['price'] = self.df.groupby('product')['price'].transform(
            lambda x: x.fillna(x.mean())
        )
        # 去除异常
        self.df = self.df[self.df['amount'] > 0]
        # 派生字段
        self.df['month'] = self.df['date'].dt.month
        return self

    def analyze(self) -> 'SalesAnalyzer':
        """数据分析"""
        self.report['总销售额'] = self.df['amount'].sum()
        self.report['总订单数'] = len(self.df)
        self.report['平均客单价'] = self.df['amount'].mean()

        self.product_summary = self.df.groupby('product').agg(
            销售额=('amount', 'sum'),
            销量=('quantity', 'sum'),
        ).sort_values('销售额', ascending=False)

        self.monthly = self.df.resample('M', on='date')['amount'].sum()
        return self

    def visualize(self, outdir: str = '.'):
        """生成图表"""
        Path(outdir).mkdir(exist_ok=True)

        # 产品销售柱状图
        fig, ax = plt.subplots(figsize=(8, 5))
        self.product_summary['销售额'].plot(kind='bar', ax=ax, color='steelblue')
        ax.set_title('各产品销售额')
        ax.set_ylabel('金额（元）')
        plt.tight_layout()
        plt.savefig(f'{outdir}/product_sales.png', dpi=150)
        plt.close()

        # 月度趋势
        fig, ax = plt.subplots(figsize=(10, 5))
        self.monthly.plot(ax=ax, marker='o')
        ax.set_title('月度销售趋势')
        ax.set_ylabel('金额（元）')
        ax.grid(True, alpha=0.3)
        plt.tight_layout()
        plt.savefig(f'{outdir}/monthly_trend.png', dpi=150)
        plt.close()

    def export(self, outpath: str = 'analysis_report.csv'):
        """导出分析结果"""
        self.product_summary.to_csv(outpath, encoding='utf-8-sig')
        print(f"报告已导出: {outpath}")
        for k, v in self.report.items():
            print(f"  {k}: {v:,.2f}")


# 使用
# analyzer = SalesAnalyzer('sales_data.csv')
# analyzer.clean().analyze().visualize('output').export()

---

7. 导出数据

# 导出 CSV（utf-8-sig 兼容 Excel）
df.to_csv('cleaned_data.csv', index=False, encoding='utf-8-sig')

# 导出 Excel（多个 sheet）
with pd.ExcelWriter('report.xlsx') as writer:
    df.to_excel(writer, sheet_name='明细数据', index=False)
    product_stats.to_excel(writer, sheet_name='产品汇总')
    pivot.to_excel(writer, sheet_name='地区透视')

# 导出 JSON
df.reset_index().to_json('data.json', orient='records', force_ascii=False, indent=2)

---

8. 小结

操作	方法
读取数据	read_csv / read_excel / read_json
数据清洗	fillna / dropna / drop_duplicates
分组聚合	groupby / pivot_table / agg
时间序列	resample / rolling / cumsum
可视化	plot / seaborn / matplotlib
导出	to_csv / to_excel / to_json

---

9. 练习题

1. 读取一份真实 CSV 数据（如股票、天气），完成缺失值处理和异常值检测。
2. 使用 pivot_table 分析不同月份各地区的销售情况并绘制热力图。
3. 实现一个数据分析类，接收任意 CSV 文件，自动生成统计报告和图表。
4. 使用滑动平均平滑一条时间序列数据，对比平滑前后的折线图。

---

下节预告：我们将使用 FastAPI 开发一个完整的 RESTful API 服务。

]]> https://example.com/posts/language/python-51-web%E7%88%AC%E8%99%AB%E5%AE%9E%E6%88%98/ Wed, 17 Dec 2025 00:00:00 +0000 ixiaoqiang0011@gmail.com (星辰逐梦) https://example.com/posts/language/python-51-web%E7%88%AC%E8%99%AB%E5%AE%9E%E6%88%98/ 学习目标：综合运用 requests、BeautifulSoup、asyncio 等技术，开发完整的 Web 爬虫，掌握反爬策略和数据存储。

---

1. 爬虫基础

1.1 爬虫工作流程

1. 发送请求 (requests/aiohttp)
       ↓
2. 获取响应 (HTML/JSON)
       ↓
3. 解析数据 (BeautifulSoup/lxml)
       ↓
4. 提取信息 (CSS选择器/XPath)
       ↓
5. 存储数据 (CSV/JSON/数据库)

1.2 安装依赖

pip install requests beautifulsoup4 lxml
pip install aiohttp  # 异步爬虫
pip install selenium  # 动态页面

---

2. 基础爬虫

2.1 获取页面

import requests
from bs4 import BeautifulSoup

def fetch_page(url: str) -> str:
    """获取网页内容"""
    headers = {
        'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) '
                       'AppleWebKit/537.36 (KHTML, like Gecko) '
                       'Chrome/120.0.0.0 Safari/537.36'
    }
    
    try:
        response = requests.get(url, headers=headers, timeout=10)
        response.raise_for_status()
        response.encoding = response.apparent_encoding
        return response.text
    except requests.RequestException as e:
        print(f"请求失败: {e}")
        return None

# 获取页面
html = fetch_page('https://quotes.toscrape.com/')
if html:
    print(f"页面长度: {len(html)} 字符")

2.2 解析数据

def parse_quotes(html: str) -> list[dict]:
    """解析名言页面"""
    soup = BeautifulSoup(html, 'lxml')
    quotes = []
    
    for quote_div in soup.select('div.quote'):
        text = quote_div.select_one('span.text').get_text()
        author = quote_div.select_one('small.author').get_text()
        tags = [tag.get_text() for tag in quote_div.select('a.tag')]
        
        quotes.append({
            'text': text,
            'author': author,
            'tags': tags
        })
    
    return quotes

# 解析
quotes = parse_quotes(html)
for q in quotes[:3]:
    print(f"[{q['author']}] {q['text'][:50]}...")
    print(f"  标签: {', '.join(q['tags'])}")

2.3 分页爬取

import time

def scrape_all_pages(base_url: str, max_pages: int = 10) -> list[dict]:
    """爬取所有分页"""
    all_quotes = []
    
    for page in range(1, max_pages + 1):
        url = f"{base_url}/page/{page}/"
        print(f"正在爬取第 {page} 页: {url}")
        
        html = fetch_page(url)
        if not html:
            break
        
        quotes = parse_quotes(html)
        if not quotes:
            print(f"第 {page} 页无数据，停止")
            break
        
        all_quotes.extend(quotes)
        
        # 礼貌延迟
        time.sleep(1)
    
    return all_quotes

# 爬取
# all_quotes = scrape_all_pages('https://quotes.toscrape.com', 5)

---

3. 数据存储

3.1 JSON 存储

import json
from pathlib import Path

def save_to_json(data: list[dict], filepath: str) -> None:
    """保存为 JSON 文件"""
    Path(filepath).write_text(
        json.dumps(data, ensure_ascii=False, indent=2),
        encoding='utf-8'
    )
    print(f"已保存 {len(data)} 条数据到 {filepath}")

# save_to_json(all_quotes, 'quotes.json')

3.2 CSV 存储

import csv

def save_to_csv(data: list[dict], filepath: str) -> None:
    """保存为 CSV 文件"""
    if not data:
        return
    
    with open(filepath, 'w', newline='', encoding='utf-8-sig') as f:
        writer = csv.DictWriter(f, fieldnames=data[0].keys())
        writer.writeheader()
        writer.writerows(data)
    
    print(f"已保存 {len(data)} 条数据到 {filepath}")

# save_to_csv(all_quotes, 'quotes.csv')

3.3 SQLite 存储

import sqlite3

def save_to_sqlite(data: list[dict], db_path: str = 'quotes.db') -> None:
    """保存到 SQLite 数据库"""
    conn = sqlite3.connect(db_path)
    cursor = conn.cursor()
    
    cursor.execute('''
        CREATE TABLE IF NOT EXISTS quotes (
            id INTEGER PRIMARY KEY AUTOINCREMENT,
            text TEXT NOT NULL,
            author TEXT,
            tags TEXT
        )
    ''')
    
    for item in data:
        cursor.execute(
            'INSERT INTO quotes (text, author, tags) VALUES (?, ?, ?)',
            (item['text'], item['author'], ','.join(item['tags']))
        )
    
    conn.commit()
    print(f"已保存 {len(data)} 条数据到数据库")
    conn.close()

# save_to_sqlite(all_quotes)

---

4. 异步爬虫

import asyncio
import aiohttp
from bs4 import BeautifulSoup

async def fetch_async(session: aiohttp.ClientSession, url: str) -> str:
    """异步获取页面"""
    headers = {'User-Agent': 'Mozilla/5.0'}
    
    async with session.get(url, headers=headers, timeout=aiohttp.ClientTimeout(total=10)) as resp:
        return await resp.text()

async def scrape_page(session: aiohttp.ClientSession, url: str) -> list[dict]:
    """爬取单个页面"""
    html = await fetch_async(session, url)
    return parse_quotes(html)

async def scrape_concurrent(base_url: str, max_pages: int = 10) -> list[dict]:
    """并发爬取多个页面"""
    urls = [f"{base_url}/page/{i}/" for i in range(1, max_pages + 1)]
    
    async with aiohttp.ClientSession() as session:
        tasks = [scrape_page(session, url) for url in urls]
        results = await asyncio.gather(*tasks, return_exceptions=True)
    
    all_quotes = []
    for result in results:
        if isinstance(result, list):
            all_quotes.extend(result)
        else:
            print(f"错误: {result}")
    
    return all_quotes

# 运行异步爬虫
# all_quotes = asyncio.run(scrape_concurrent('https://quotes.toscrape.com', 10))

---

5. 反爬策略应对

5.1 设置请求头

HEADERS = {
    'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...',
    'Accept': 'text/html,application/xhtml+xml,...',
    'Accept-Language': 'zh-CN,zh;q=0.9,en;q=0.8',
    'Referer': 'https://www.google.com/',
}

# 随机 User-Agent
import random

USER_AGENTS = [
    'Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/120.0.0.0',
    'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Chrome/120.0.0.0',
    'Mozilla/5.0 (X11; Linux x86_64) Firefox/121.0',
]

headers = {'User-Agent': random.choice(USER_AGENTS)}

5.2 代理 IP

def get_proxies() -> dict:
    """获取代理"""
    return {
        'http': 'http://proxy.example.com:8080',
        'https': 'http://proxy.example.com:8080',
    }

# 代理池
PROXY_POOL = [
    'http://1.2.3.4:8080',
    'http://5.6.7.8:8080',
]

def get_random_proxy():
    return random.choice(PROXY_POOL)

# 使用代理
# response = requests.get(url, proxies={'http': get_random_proxy()})

5.3 限速与重试

import time
from functools import wraps

def rate_limit(calls: int = 1, period: float = 1.0):
    """限速装饰器"""
    min_interval = period / calls
    last_called = [0.0]
    
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            elapsed = time.time() - last_called[0]
            wait = min_interval - elapsed
            if wait > 0:
                time.sleep(wait)
            last_called[0] = time.time()
            return func(*args, **kwargs)
        return wrapper
    return decorator

def retry(times: int = 3, delay: float = 1.0):
    """重试装饰器"""
    def decorator(func):
        @wraps(func)
        def wrapper(*args, **kwargs):
            for attempt in range(times):
                try:
                    return func(*args, **kwargs)
                except Exception as e:
                    print(f"第 {attempt+1} 次尝试失败: {e}")
                    if attempt < times - 1:
                        time.sleep(delay * (attempt + 1))
            raise Exception(f"重试 {times} 次后仍失败")
        return wrapper
    return decorator

@rate_limit(calls=2, period=1.0)
@retry(times=3, delay=1.0)
def fetch_with_retry(url: str) -> str:
    """带限速和重试的请求"""
    response = requests.get(url, headers=HEADERS, timeout=10)
    response.raise_for_status()
    return response.text

---

6. 完整爬虫项目

"""
新闻爬虫 - 综合示例
爬取新闻标题、链接、日期，保存到数据库
"""

import requests
from bs4 import BeautifulSoup
import sqlite3
import time
import logging
from dataclasses import dataclass
from typing import Optional

logging.basicConfig(level=logging.INFO, format='%(asctime)s %(levelname)s: %(message)s')
logger = logging.getLogger(__name__)

@dataclass
class NewsItem:
    """新闻数据"""
    title: str
    url: str
    date: str
    category: str

class NewsScraper:
    """新闻爬虫"""
    
    def __init__(self, db_path: str = 'news.db'):
        self.session = requests.Session()
        self.session.headers.update({
            'User-Agent': 'Mozilla/5.0 ...'
        })
        self.db_path = db_path
        self._init_db()
    
    def _init_db(self):
        """初始化数据库"""
        conn = sqlite3.connect(self.db_path)
        conn.execute('''
            CREATE TABLE IF NOT EXISTS news (
                id INTEGER PRIMARY KEY AUTOINCREMENT,
                title TEXT UNIQUE,
                url TEXT,
                date TEXT,
                category TEXT,
                created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
            )
        ''')
        conn.commit()
        conn.close()
    
    def fetch(self, url: str) -> Optional[str]:
        """获取页面"""
        try:
            resp = self.session.get(url, timeout=10)
            resp.raise_for_status()
            return resp.text
        except Exception as e:
            logger.error(f"获取失败 {url}: {e}")
            return None
    
    def parse(self, html: str, category: str) -> list[NewsItem]:
        """解析新闻列表"""
        soup = BeautifulSoup(html, 'lxml')
        news_list = []
        
        for article in soup.select('article.news-item'):
            title_el = article.select_one('h2.title a')
            if not title_el:
                continue
            
            news = NewsItem(
                title=title_el.get_text(strip=True),
                url=title_el.get('href', ''),
                date=article.select_one('time').get('datetime', ''),
                category=category
            )
            news_list.append(news)
        
        return news_list
    
    def save(self, news_list: list[NewsItem]) -> int:
        """保存到数据库"""
        conn = sqlite3.connect(self.db_path)
        cursor = conn.cursor()
        saved = 0
        
        for news in news_list:
            try:
                cursor.execute(
                    'INSERT OR IGNORE INTO news (title, url, date, category) VALUES (?,?,?,?)',
                    (news.title, news.url, news.date, news.category)
                )
                if cursor.rowcount > 0:
                    saved += 1
            except Exception as e:
                logger.error(f"保存失败: {e}")
        
        conn.commit()
        conn.close()
        logger.info(f"保存 {saved} 条新闻")
        return saved
    
    def run(self, categories: dict[str, str]):
        """运行爬虫"""
        total = 0
        
        for category, url in categories.items():
            logger.info(f"爬取分类: {category}")
            
            html = self.fetch(url)
            if not html:
                continue
            
            news_list = self.parse(html, category)
            total += self.save(news_list)
            
            time.sleep(2)  # 礼貌延迟
        
        logger.info(f"完成，共保存 {total} 条新闻")
        return total

# 使用
# scraper = NewsScraper()
# scraper.run({
#     '科技': 'https://example.com/tech',
#     '财经': 'https://example.com/finance',
# })

---

7. 爬虫礼仪与法律

爬虫注意事项：

1. 遵守 robots.txt
   - 检查目标网站的爬虫协议
   - 尊重 Disallow 规则

2. 控制频率
   - 设置合理延迟（1-3 秒）
   - 避免对服务器造成压力

3. 数据使用
   - 仅用于个人学习
   - 不商用、不传播
   - 尊重版权

4. 法律风险
   - 不爬取个人隐私数据
   - 不爬取需要授权的数据
   - 不进行恶意攻击

# 检查 robots.txt
import urllib.robotparser

def check_robots(url: str) -> bool:
    """检查是否允许爬取"""
    rp = urllib.robotparser.RobotFileParser()
    rp.set_url(f"https://{url.split('/')[2]}/robots.txt")
    rp.read()
    return rp.can_fetch('*', url)

# allowed = check_robots('https://example.com/page')

---

8. 小结

技术	用途
requests	HTTP 请求
BeautifulSoup	HTML 解析
aiohttp	异步请求
lxml	高性能解析
SQLite/CSV/JSON	数据存储
代理/限速/重试	反爬应对

---

9. 练习题

1. 爬取一个公开的图书网站，提取书名、作者、价格并存入数据库。
2. 使用 asyncio 实现并发爬虫，对比与同步爬虫的速度差异。
3. 为爬虫添加日志记录和错误重试机制。
4. 爬取数据后使用 pandas 进行简单分析（如按作者统计数量）。

---

下节预告：我们将使用 pandas 和 matplotlib 进行数据分析实战。

]]> https://example.com/posts/language/python-50-cli%E5%B7%A5%E5%85%B7%E5%BC%80%E5%8F%91%E5%AE%9E%E6%88%98/ Sun, 14 Dec 2025 00:00:00 +0000 ixiaoqiang0011@gmail.com (星辰逐梦) https://example.com/posts/language/python-50-cli%E5%B7%A5%E5%85%B7%E5%BC%80%E5%8F%91%E5%AE%9E%E6%88%98/ 学习目标：综合运用 Python 知识，使用 argparse 和 click 开发实用的命令行工具，掌握项目打包与分发。

---

1. argparse（标准库）

1.1 基础用法

# file_manager.py
import argparse
import os
import shutil
from pathlib import Path

def main():
    parser = argparse.ArgumentParser(
        description='文件管理工具',
        formatter_class=argparse.RawDescriptionHelpFormatter,
        epilog='''
示例:
  %(prog)s list ./photos
  %(prog)s copy file.txt backup/
  %(prog)s info document.pdf
'''
    )
    
    # 子命令
    subparsers = parser.add_subparsers(dest='command', help='可用命令')
    
    # list 命令
    list_parser = subparsers.add_parser('list', help='列出目录内容')
    list_parser.add_argument('path', nargs='?', default='.', help='目录路径')
    list_parser.add_argument('-a', '--all', action='store_true', help='显示隐藏文件')
    list_parser.add_argument('-l', '--long', action='store_true', help='详细格式')
    
    # copy 命令
    copy_parser = subparsers.add_parser('copy', help='复制文件')
    copy_parser.add_argument('source', help='源文件路径')
    copy_parser.add_argument('destination', help='目标路径')
    copy_parser.add_argument('-f', '--force', action='store_true', help='覆盖已存在文件')
    
    # info 命令
    info_parser = subparsers.add_parser('info', help='显示文件信息')
    info_parser.add_argument('file', help='文件路径')
    
    args = parser.parse_args()
    
    if args.command == 'list':
        list_files(args.path, args.all, args.long)
    elif args.command == 'copy':
        copy_file(args.source, args.destination, args.force)
    elif args.command == 'info':
        file_info(args.file)
    else:
        parser.print_help()

def list_files(path, show_all, long_format):
    """列出目录内容"""
    p = Path(path)
    if not p.exists():
        print(f"错误: 路径 '{path}' 不存在")
        return
    
    for item in sorted(p.iterdir()):
        if not show_all and item.name.startswith('.'):
            continue
        
        if long_format:
            size = item.stat().st_size
            is_dir = 'd' if item.is_dir() else '-'
            print(f"{is_dir} {size:>10}  {item.name}")
        else:
            print(item.name)

def copy_file(source, dest, force):
    """复制文件"""
    src = Path(source)
    if not src.exists():
        print(f"错误: 源文件 '{source}' 不存在")
        return
    
    dst = Path(dest)
    if dst.exists() and not force:
        print(f"错误: 目标已存在，使用 -f 覆盖")
        return
    
    shutil.copy2(src, dst)
    print(f"已复制: {source} → {dest}")

def file_info(filepath):
    """显示文件信息"""
    p = Path(filepath)
    if not p.exists():
        print(f"错误: 文件 '{filepath}' 不存在")
        return
    
    stat = p.stat()
    import time
    print(f"文件: {p.name}")
    print(f"路径: {p.resolve()}")
    print(f"大小: {stat.st_size:,} bytes")
    print(f"修改时间: {time.ctime(stat.st_mtime)}")
    print(f"类型: {'目录' if p.is_dir() else '文件'}")

if __name__ == '__main__':
    main()

1.2 运行效果

$ python file_manager.py list -l -a ~/Documents
d       4096  .cache
-     153486  notes.md
d       4096  projects

$ python file_manager.py info notes.md
文件: notes.md
路径: /Users/user/Documents/notes.md
大小: 153,486 bytes
修改时间: Mon Jan 15 10:30:00 2024
类型: 文件

---

2. click（第三方库）

2.1 安装与基础

pip install click

# task_manager.py
import click
import json
from pathlib import Path
from datetime import datetime

TASKS_FILE = Path.home() / '.tasks.json'

def load_tasks():
    if TASKS_FILE.exists():
        return json.loads(TASKS_FILE.read_text())
    return []

def save_tasks(tasks):
    TASKS_FILE.write_text(json.dumps(tasks, ensure_ascii=False, indent=2))

@click.group()
@click.version_option('1.0.0')
def cli():
    """任务管理命令行工具"""
    pass

@cli.command()
@click.argument('title')
@click.option('-p', '--priority', type=click.Choice(['high', 'medium', 'low']),
              default='medium', help='优先级')
@click.option('-d', '--due', help='截止日期 (YYYY-MM-DD)')
def add(title, priority, due):
    """添加新任务"""
    tasks = load_tasks()
    task = {
        'id': len(tasks) + 1,
        'title': title,
        'priority': priority,
        'due': due,
        'done': False,
        'created_at': datetime.now().isoformat()
    }
    tasks.append(task)
    save_tasks(tasks)
    click.echo(f"✓ 已添加任务 #{task['id']}: {title}")

@cli.command(name='list')
@click.option('-s', '--status', type=click.Choice(['all', 'pending', 'done']),
              default='all', help='过滤状态')
@click.option('-p', '--priority', type=click.Choice(['high', 'medium', 'low']),
              help='过滤优先级')
def list_tasks(status, priority):
    """列出任务"""
    tasks = load_tasks()
    
    if status == 'pending':
        tasks = [t for t in tasks if not t['done']]
    elif status == 'done':
        tasks = [t for t in tasks if t['done']]
    
    if priority:
        tasks = [t for t in tasks if t['priority'] == priority]
    
    if not tasks:
        click.echo("没有任务")
        return
    
    for t in tasks:
        mark = '✓' if t['done'] else '○'
        color = {'high': 'red', 'medium': 'yellow', 'low': 'green'}[t['priority']]
        click.echo(f"  {mark} #{t['id']:>3}  {t['title']}", )
        if t['due']:
            click.echo(f"        截止: {t['due']}")

@cli.command()
@click.argument('task_id', type=int)
def done(task_id):
    """标记任务完成"""
    tasks = load_tasks()
    for t in tasks:
        if t['id'] == task_id:
            t['done'] = True
            save_tasks(tasks)
            click.echo(f"✓ 已完成: {t['title']}")
            return
    click.echo(f"错误: 任务 #{task_id} 不存在", err=True)

@cli.command()
@click.argument('task_id', type=int)
def delete(task_id):
    """删除任务"""
    tasks = load_tasks()
    original_len = len(tasks)
    tasks = [t for t in tasks if t['id'] != task_id]
    
    if len(tasks) < original_len:
        save_tasks(tasks)
        click.echo(f"✓ 已删除任务 #{task_id}")
    else:
        click.echo(f"错误: 任务 #{task_id} 不存在", err=True)

@cli.command()
def clear():
    """清除已完成任务"""
    tasks = load_tasks()
    pending = [t for t in tasks if not t['done']]
    removed = len(tasks) - len(pending)
    save_tasks(pending)
    click.echo(f"✓ 已清除 {removed} 个已完成任务")

if __name__ == '__main__':
    cli()

2.2 运行效果

$ python task_manager.py --help
Usage: task_manager.py [OPTIONS] COMMAND [ARGS]...

  任务管理命令行工具

Options:
  --version  Show the version and exit.
  --help     Show this message and exit.

Commands:
  add      添加新任务
  clear    清除已完成任务
  delete   删除任务
  done     标记任务完成
  list     列出任务

$ python task_manager.py add "完成报告" -p high -d 2024-01-20
✓ 已添加任务 #1: 完成报告

$ python task_manager.py list
  ○ #  1  完成报告
        截止: 2024-01-20

$ python task_manager.py done 1
✓ 已完成: 完成报告

---

3. Rich（美化输出）

pip install rich

from rich.console import Console
from rich.table import Table
from rich.progress import Progress
from rich.panel import Panel
from rich.markdown import Markdown
import time

console = Console()

# 彩色输出
console.print("[bold red]错误[/bold red]: 文件未找到")
console.print("[green]成功[/green]: 操作完成")
console.print("[yellow]警告[/yellow]: 磁盘空间不足")

# 表格
table = Table(title="任务列表")
table.add_column("ID", style="cyan", justify="right")
table.add_column("任务", style="white")
table.add_column("优先级", style="yellow")
table.add_column("状态", style="green")

table.add_row("1", "完成报告", "高", "待办")
table.add_row("2", "回复邮件", "中", "已完成")
table.add_row("3", "代码审查", "低", "待办")

console.print(table)

# 进度条
with Progress() as progress:
    task = progress.add_task("[cyan]处理中...", total=100)
    while not progress.finished:
        progress.update(task, advance=5)
        time.sleep(0.1)

# 面板
console.print(Panel.fit(
    "[bold]欢迎使用任务管理器[/bold]\n"
    "输入 help 查看可用命令",
    title="Task Manager",
    border_style="blue"
))

# Markdown 渲染
md = Markdown("""
# 说明
- 支持 **Markdown** 语法
- 自动渲染为终端富文本
""")
console.print(md)

---

4. 项目打包

4.1 pyproject.toml 配置

[project]
name = "task-manager"
version = "1.0.0"
description = "一个简单的任务管理命令行工具"
authors = [{name = "Your Name", email = "you@example.com"}]
dependencies = [
    "click>=8.0",
    "rich>=13.0",
]

[project.scripts]
task = "task_manager.cli:cli"

[build-system]
requires = ["setuptools>=68.0"]
build-backend = "setuptools.backends._legacy:_Backend"

[tool.setuptools.packages.find]
where = ["src"]

4.2 安装与使用

# 开发模式安装
pip install -e .

# 安装后直接使用命令
task add "买牛奶" -p low
task list
task done 1

# 构建分发包
pip install build
python -m build

# 发布到 PyPI
pip install twine
twine upload dist/*

---

5. 小结

工具	特点	适用场景
argparse	标准库，无需安装	简单工具
click	装饰器风格，功能强大	中大型 CLI
Rich	终端美化	增强输出
Typer	基于 click + 类型提示	现代项目

---

6. 练习题

1. 使用 click 实现一个密码生成器 CLI，支持指定长度、字符集。
2. 使用 Rich 美化你的 CLI 工具输出，添加表格和进度条。
3. 为 CLI 工具添加配置文件支持（读取 ~/.mytoolrc）。
4. 将你的工具打包并发布到 TestPyPI。

---

下节预告：我们将使用 requests 和 BeautifulSoup 实现一个完整的 Web 爬虫。

]]> https://example.com/posts/language/python-49-%E6%96%87%E6%A1%A3%E7%BC%96%E5%86%99%E4%B8%8E%E6%B3%A8%E9%87%8A%E8%A7%84%E8%8C%83/ Thu, 11 Dec 2025 00:00:00 +0000 ixiaoqiang0011@gmail.com (星辰逐梦) https://example.com/posts/language/python-49-%E6%96%87%E6%A1%A3%E7%BC%96%E5%86%99%E4%B8%8E%E6%B3%A8%E9%87%8A%E8%A7%84%E8%8C%83/ 学习目标：掌握 Python 文档字符串（docstring）规范，学会编写清晰的注释，理解项目文档的组成和工具链。

---

1. 注释 vs 文档字符串

# 注释（Comment）：解释代码"怎么做"
# 使用 # 号，面向开发者
total = sum(items)  # 计算总价

# 文档字符串（Docstring）：解释"是什么"和"怎么用"
# 使用三引号，面向使用者
def calculate_total(items):
    """计算商品列表的总价。
    
    Args:
        items: 商品列表，每个商品包含 price 字段
    
    Returns:
        所有商品价格之和
    """
    return sum(item['price'] for item in items)

---

2. 文档字符串规范

2.1 Google 风格（推荐）

def fetch_user(user_id: int, include_profile: bool = False) -> dict:
    """获取用户信息。
    
    根据用户 ID 从数据库获取用户信息，可选择是否包含用户档案。
    
    Args:
        user_id: 用户唯一标识符，必须为正整数。
        include_profile: 是否包含用户档案信息，默认为 False。
    
    Returns:
        包含用户信息的字典，格式如下：
        {
            "id": int,
            "name": str,
            "email": str,
            "profile": dict  # 仅当 include_profile=True
        }
    
    Raises:
        ValueError: 当 user_id 不为正整数时。
        UserNotFoundError: 当用户不存在时。
    
    Examples:
        >>> fetch_user(1)
        {"id": 1, "name": "张三", "email": "zhangsan@example.com"}
        
        >>> fetch_user(1, include_profile=True)
        {"id": 1, "name": "张三", "profile": {"age": 25, "city": "北京"}}
    """
    if user_id <= 0:
        raise ValueError("user_id 必须为正整数")
    
    user = db.get_user(user_id)
    if user is None:
        raise UserNotFoundError(f"用户 {user_id} 不存在")
    
    if include_profile:
        user['profile'] = db.get_profile(user_id)
    
    return user

2.2 类和模块文档

"""用户管理模块。

提供用户注册、登录、信息管理等功能。

示例:
    from user_manager import UserManager
    
    manager = UserManager()
    manager.register("zhangsan", "password123")
"""

class UserManager:
    """用户管理器。
    
    管理用户的注册、认证和信息操作。
    
    Attributes:
        db: 数据库连接实例。
        cache: 缓存实例。
    
    Example:
        >>> manager = UserManager()
        >>> user = manager.login("admin", "password")
        >>> print(user.name)
        管理员
    """
    
    def __init__(self, db_url: str = None):
        """初始化用户管理器。
        
        Args:
            db_url: 数据库连接 URL，默认使用配置文件中的地址。
        """
        self.db = Database(db_url)
        self.cache = {}
    
    def register(self, username: str, password: str) -> dict:
        """注册新用户。
        
        Args:
            username: 用户名，3-20 个字符。
            password: 密码，至少 8 个字符。
        
        Returns:
            新创建的用户信息。
        
        Raises:
            ValueError: 用户名或密码不符合要求。
            UsernameExistsError: 用户名已被注册。
        """
        pass

2.3 NumPy 风格

def linear_regression(X, y, alpha=0.01, iterations=1000):
    """线性回归梯度下降。
    
    使用梯度下降算法拟合线性回归模型。
    
    Parameters
    ----------
    X : array_like
        特征矩阵，形状为 (n_samples, n_features)。
    y : array_like
        目标值，形状为 (n_samples,)。
    alpha : float, optional
        学习率，默认为 0.01。
    iterations : int, optional
        迭代次数，默认为 1000。
    
    Returns
    -------
    theta : ndarray
        拟合后的参数向量，形状为 (n_features,)。
    cost_history : list
        每次迭代的损失值。
    
    Notes
    -----
    学习率过大可能导致不收敛，建议从 0.001 开始调试。
    
    Examples
    --------
    >>> import numpy as np
    >>> X = np.array([[1, 1], [1, 2], [1, 3]])
    >>> y = np.array([2, 4, 6])
    >>> theta, _ = linear_regression(X, y, alpha=0.1)
    """
    pass

---

3. 注释最佳实践

3.1 好的注释

# 解释"为什么"而不是"做什么"
# 使用二分查找因为数据已排序，O(log n) 比 O(n) 快
def find_item(sorted_list, target):
    left, right = 0, len(sorted_list) - 1
    while left <= right:
        mid = (left + right) // 2
        if sorted_list[mid] == target:
            return mid
        elif sorted_list[mid] < target:
            left = mid + 1
        else:
            right = mid - 1
    return -1

# 标注 workaround 和 TODO
def get_user_data(user_id):
    # TODO: 迁移到新的用户服务 API（预计 v2.0）
    # FIXME: 临时方案，需要处理超时情况
    response = requests.get(f"{OLD_API_URL}/users/{user_id}")
    return response.json()

# 解释复杂的正则表达式
pattern = r'^(\d{4})-(\d{2})-(\d{2})$'  # YYYY-MM-DD 格式日期

# 标注魔法数字的来源
RETRY_INTERVAL = 5  # 根据运维建议，5 秒重试间隔
MAX_FILE_SIZE = 10 * 1024 * 1024  # 10MB，上传限制

3.2 坏的注释（应避免）

# ✗ 注释只是在重复代码
i += 1  # i 加 1

# ✗ 过时的注释（代码已改但注释没更新）
# 返回用户列表
def get_user_count():  # 实际返回的是数量
    return len(users)

# ✗ 用注释代替函数名
def do_stuff(x, y):
    # 这个函数计算两个数的平均值然后乘以 100
    return (x + y) / 2 * 100

# ✓ 应该改为
def calculate_percentage_average(x, y):
    return (x + y) / 2 * 100

# ✗ 注释掉的代码（用 Git 管理历史）
# old_result = process_old_way(data)
# if old_result > threshold:
#     return old_result
result = process_new_way(data)

---

4. 类型提示即文档

# 类型提示本身就是最好的文档
# 无需额外注释说明参数类型

def process_order(
    order_id: int,
    items: list[dict[str, int | str]],
    discount: float = 0.0,
    callback: Callable[[int], None] | None = None
) -> dict[str, int | str]:
    """处理订单。
    
    Args:
        order_id: 订单 ID。
        items: 商品列表，每项包含 name(str) 和 quantity(int)。
        discount: 折扣率，0.0-1.0 之间。
        callback: 处理完成后的回调函数。
    
    Returns:
        处理结果，包含 total 和 status。
    """
    pass

---

5. 项目文档组成

project/
├── README.md           ← 项目入口文档
├── CHANGELOG.md        ← 变更日志
├── CONTRIBUTING.md     ← 贡献指南
├── LICENSE             ← 开源协议
├── docs/               ← 文档目录
│   ├── installation.md ← 安装指南
│   ├── quickstart.md   ← 快速开始
│   ├── api/            ← API 文档
│   └── examples/       ← 示例代码
├── pyproject.toml      ← 项目配置
└── src/
    └── mypackage/
        ├── __init__.py ← 包文档
        └── ...

5.1 README 模板

# 项目名称

一句话描述项目。

## 功能特性

- 特性 1
- 特性 2
- 特性 3

## 安装

pip install package-name

## 快速开始

```python
from package import Module

m = Module()
result = m.run()

文档

完整文档请访问：https://package.readthedocs.io

]]> https://example.com/posts/language/python-48-%E8%B0%83%E8%AF%95%E6%8A%80%E5%B7%A7%E4%B8%8E%E6%80%A7%E8%83%BD%E5%88%86%E6%9E%90/ Sun, 07 Dec 2025 00:00:00 +0000 ixiaoqiang0011@gmail.com (星辰逐梦) https://example.com/posts/language/python-48-%E8%B0%83%E8%AF%95%E6%8A%80%E5%B7%A7%E4%B8%8E%E6%80%A7%E8%83%BD%E5%88%86%E6%9E%90/ 学习目标：掌握 Python 调试的多种方法，学会使用性能分析工具定位瓶颈，理解常见性能优化策略。

---

1. print 调试法

最简单但有效的调试方式，适合快速定位问题。

1.1 基础 print

def calculate_price(items):
    total = 0
    for item in items:
        print(f"处理: {item['name']}, 价格: {item['price']}")
        total += item['price']
        print(f"  累计: {total}")
    print(f"最终总价: {total}")
    return total

items = [
    {"name": "苹果", "price": 5},
    {"name": "香蕉", "price": 3},
    {"name": "橙子", "price": 4}
]
calculate_price(items)

1.2 使用 f-string 调试（Python 3.8+）

x = 42
name = "张三"
numbers = [1, 2, 3]

# = 后自动显示变量名和值
print(f"{x=}")        # x=42
print(f"{name=}")     # name='张三'
print(f"{numbers=}")  # numbers=[1, 2, 3]

# 表达式也支持
print(f"{sum(numbers)=}")  # sum(numbers)=6
print(f"{x * 2=}")         # x * 2=84

---

2. logging 模块调试

比 print 更灵活，支持级别控制和输出到文件。

]]> https://example.com/posts/language/python-47-%E4%BB%A3%E7%A0%81%E9%A3%8E%E6%A0%BC%E4%B8%8Elinting/ Thu, 04 Dec 2025 00:00:00 +0000 ixiaoqiang0011@gmail.com (星辰逐梦) https://example.com/posts/language/python-47-%E4%BB%A3%E7%A0%81%E9%A3%8E%E6%A0%BC%E4%B8%8Elinting/ 学习目标：掌握 PEP 8 代码风格规范，学会使用 Black、Ruff、isort 等工具自动格式化和检查代码质量。

---

1. PEP 8 规范

PEP 8 是 Python 官方代码风格指南，是大多数 Python 项目遵循的标准。

]]> https://example.com/posts/language/python-46-%E7%B1%BB%E5%9E%8B%E6%8F%90%E7%A4%BAtyping/ Mon, 01 Dec 2025 00:00:00 +0000 ixiaoqiang0011@gmail.com (星辰逐梦) https://example.com/posts/language/python-46-%E7%B1%BB%E5%9E%8B%E6%8F%90%E7%A4%BAtyping/ 学习目标：掌握 Python 类型提示系统，学会使用 typing 模块和现代语法编写类型安全的代码，理解静态类型检查的价值。

---

1. 为什么需要类型提示

1.1 动态类型的困境

# 没有类型提示：参数和返回值类型不明确
def process(data):
    result = []
    for item in data:
        result.append(item * 2)
    return result

# 调用者无法知道：
# - data 应该是什么类型？列表？字典？
# - item 支持乘法吗？
# - 返回什么类型？

1.2 类型提示的好处

• 可读性：代码即文档，一目了然
• IDE 支持：智能补全、错误提示
• 静态检查：运行前发现类型错误
• 重构安全：修改接口时自动发现影响范围
• 团队协作：减少沟通成本

---

2. 基本类型提示

2.1 变量与函数

# 变量类型提示
name: str = "张三"
age: int = 25
height: float = 1.75
is_student: bool = True

# 函数类型提示
def greet(name: str) -> str:
    return f"Hello, {name}"

def add(a: int, b: int) -> int:
    return a + b

def is_even(n: int) -> bool:
    return n % 2 == 0

# 多种返回类型
def parse_int(s: str) -> int | None:  # Python 3.10+ 语法
    try:
        return int(s)
    except ValueError:
        return None

2.2 Python 3.10+ 新语法

# 旧写法（Python 3.9 及以下）
from typing import Optional, Union, List, Dict, Tuple

def old_style(x: Optional[int] = None) -> Union[str, int]:
    pass

data: List[int] = [1, 2, 3]
mapping: Dict[str, int] = {"a": 1}
point: Tuple[int, int] = (10, 20)

# 新写法（Python 3.10+）
def new_style(x: int | None = None) -> str | int:
    pass

data: list[int] = [1, 2, 3]
mapping: dict[str, int] = {"a": 1}
point: tuple[int, int] = (10, 20)

---

3. 复合类型

3.1 容器类型

from typing import List, Dict, Set, Tuple, FrozenSet

# 列表
names: list[str] = ["Alice", "Bob"]
numbers: list[int | float] = [1, 2, 3.14]

# 字典
config: dict[str, str] = {"host": "localhost", "port": "8080"}
user_ages: dict[str, int] = {"Alice": 25, "Bob": 30}

# 集合
tags: set[str] = {"python", "web", "api"}

# 元组
# 固定长度元组
point: tuple[int, int] = (10, 20)
# 固定结构元组
record: tuple[str, int, bool] = ("Alice", 25, True)
# 可变长度同类型元组
scores: tuple[int, ...] = (90, 85, 92, 88)

3.2 嵌套类型

# 嵌套列表
matrix: list[list[int]] = [
    [1, 2, 3],
    [4, 5, 6],
    [7, 8, 9]
]

# 字典的值为列表
groups: dict[str, list[str]] = {
    "admins": ["alice", "bob"],
    "users": ["charlie", "dave"]
}

# 复杂嵌套
api_response: dict[str, list[dict[str, int | str]]] = {
    "users": [
        {"id": 1, "name": "Alice", "age": 25},
        {"id": 2, "name": "Bob", "age": 30}
    ]
}

---

4. typing 模块常用类型

4.1 Optional 和 Union

from typing import Optional, Union

# Optional[X] 等价于 X | None
def find_user(user_id: int) -> Optional[dict]:
    """可能返回用户字典或 None"""
    users = {1: {"name": "Alice"}}
    return users.get(user_id)

# Union 多种类型
def process_value(value: Union[int, str, float]) -> str:
    """处理多种类型的值"""
    return str(value)

# Python 3.10+ 可以用 | 语法
def process_value_new(value: int | str | float) -> str:
    return str(value)

4.2 Any 和 NoReturn

from typing import Any, NoReturn

# Any：任意类型（尽量少用）
def log(message: Any) -> None:
    print(f"[LOG] {message}")

# NoReturn：函数永不返回
def fatal_error(message: str) -> NoReturn:
    import sys
    print(f"Fatal: {message}")
    sys.exit(1)

4.3 Callable（可调用对象）

from typing import Callable

# Callable[[参数类型...], 返回类型]
def apply(func: Callable[[int, int], int], a: int, b: int) -> int:
    return func(a, b)

# 使用
result = apply(lambda x, y: x + y, 3, 5)  # 8

# 无参数的 Callable
def run_task(task: Callable[[], None]) -> None:
    task()

# 不关心参数的 Callable
from typing import Any
handler: Callable[..., Any] = print

4.4 TypeVar（类型变量）

from typing import TypeVar

# 定义类型变量
T = TypeVar('T')

# 泛型函数：输入和输出类型一致
def first(items: list[T]) -> T:
    return items[0]

# 使用
names: list[str] = ["Alice", "Bob"]
first_name: str = first(names)  # 类型推断为 str

numbers: list[int] = [1, 2, 3]
first_num: int = first(numbers)  # 类型推断为 int

# 约束类型变量
Number = TypeVar('Number', int, float)

def add(a: Number, b: Number) -> Number:
    return a + b

# add(1, 2)       ✓ 返回 int
# add(1.5, 2.5)   ✓ 返回 float
# add(1, 2.5)     ✗ 类型不匹配

---

5. 泛型（Generics）

5.1 泛型类

from typing import Generic, TypeVar

T = TypeVar('T')

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:
        if not self._items:
            raise IndexError("栈为空")
        return self._items.pop()
    
    def peek(self) -> T | None:
        return self._items[-1] if self._items else None
    
    def is_empty(self) -> bool:
        return len(self._items) == 0
    
    def size(self) -> int:
        return len(self._items)

# 使用
int_stack: Stack[int] = Stack()
int_stack.push(1)
int_stack.push(2)
value: int = int_stack.pop()  # 类型安全

str_stack: Stack[str] = Stack()
str_stack.push("hello")
text: str = str_stack.pop()

5.2 泛型方法

from typing import TypeVar, K, V

K = TypeVar('K')
V = TypeVar('V')

class BinaryTree(Generic[K, V]):
    """泛型二叉树节点"""
    
    def __init__(self, key: K, value: V) -> None:
        self.key = key
        self.value = value
        self.left: BinaryTree[K, V] | None = None
        self.right: BinaryTree[K, V] | None = None
    
    def insert(self, key: K, value: V) -> None:
        if key < self.key:
            if self.left is None:
                self.left = BinaryTree(key, value)
            else:
                self.left.insert(key, value)
        elif key > self.key:
            if self.right is None:
                self.right = BinaryTree(key, value)
            else:
                self.right.insert(key, value)

---

6. Protocol（结构化类型）

from typing import Protocol

# 定义协议（类似接口）
class Drawable(Protocol):
    def draw(self) -> None:
        ...

class Serializable(Protocol):
    def to_json(self) -> str:
        ...

# 实现协议（不需要显式继承）
class Circle:
    def draw(self) -> None:
        print("绘制圆形")

class Square:
    def draw(self) -> None:
        print("绘制方形")

# 使用协议作为类型
def render(shape: Drawable) -> None:
    shape.draw()

# Circle 和 Square 都实现了 draw 方法，自动满足 Drawable 协议
render(Circle())  # ✓
render(Square())  # ✓

---

7. TypedDict（类型化字典）

from typing import TypedDict

# 定义类型化字典
class UserDict(TypedDict):
    id: int
    name: str
    email: str
    age: int  # 必需字段

# 可选字段（Python 3.11+）
class UserDictOptional(TypedDict, total=False):
    id: int
    name: str
    email: str  # 所有字段可选

# 混合必需和可选（Python 3.11+）
class Movie(TypedDict):
    title: str
    year: int

class MovieWithRating(Movie, total=False):
    rating: float

# 使用
user: UserDict = {
    "id": 1,
    "name": "张三",
    "email": "zhangsan@example.com",
    "age": 25
}
# 类型检查器会验证字段完整性

---

8. Literal 和 Final

from typing import Literal, Final

# Literal：字面量类型
def set_mode(mode: Literal["dev", "prod", "test"]) -> None:
    print(f"设置模式: {mode}")

set_mode("dev")   # ✓
set_mode("debug") # ✗ 类型错误

# 常量定义
MAX_SIZE: Final[int] = 100
API_BASE_URL: Final[str] = "https://api.example.com"

# Final 防止重新赋值
class Config:
    VERSION: Final[str] = "1.0.0"
    
# VERSION = "2.0"  # 类型检查器会报错

---

9. 类型别名

from typing import TypeAlias

# 简单别名
JSON: TypeAlias = dict[str, 'JSON'] | list['JSON'] | str | int | float | bool | None

# 使用
def parse_json(text: str) -> JSON:
    import json
    return json.loads(text)

# Python 3.12+ 新语法
# type JSON = dict[str, JSON] | list[JSON] | str | int | float | bool | None

# 复杂类型别名
UserId = int
UserName = str
UserMap = dict[UserId, UserName]

users: UserMap = {1: "Alice", 2: "Bob"}

---

10. 重载（Overload）

from typing import overload

# 重载签名（仅用于类型检查）
@overload
def get_value(key: str) -> str: ...
@overload
def get_value(key: int) -> int: ...
@overload
def get_value(key: None) -> None: ...

# 实际实现
def get_value(key):
    """根据 key 类型返回不同类型"""
    if key is None:
        return None
    elif isinstance(key, str):
        return f"string: {key}"
    elif isinstance(key, int):
        return key * 2

# 类型检查器知道：
result1: str = get_value("hello")   # ✓
result2: int = get_value(42)        # ✓
result3: None = get_value(None)     # ✓

---

11. 静态类型检查

11.1 使用 mypy

# 安装
pip install mypy

# 检查单个文件
mypy script.py

# 检查整个项目
mypy src/

# 严格模式
mypy --strict src/

# 忽略缺失导入
mypy --ignore-missing-imports src/

11.2 配置文件

# pyproject.toml
[tool.mypy]
python_version = "3.11"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true
disallow_incomplete_defs = true

[[tool.mypy.overrides]]
module = "tests.*"
disallow_untyped_defs = false

11.3 类型错误示例

# mypy 会检测到的错误
def add(a: int, b: int) -> int:
    return a + b

add(1, 2)        # ✓
add("1", "2")    # ✗ error: Argument 1 to "add" has incompatible type "str"
add(1, 2, 3)     # ✗ error: Too many arguments
result: str = add(1, 2)  # ✗ error: Incompatible types in assignment

# 忽略特定行
result = some_untyped_function()  # type: ignore

---

12. Pydantic 与类型提示

# pip install pydantic
from pydantic import BaseModel, EmailStr, Field
from typing import Optional

class User(BaseModel):
    """使用类型提示进行数据验证"""
    id: int
    name: str = Field(..., min_length=2, max_length=50)
    email: EmailStr
    age: int = Field(..., ge=0, le=150)
    bio: Optional[str] = None
    
# 自动验证
user = User(
    id=1,
    name="张三",
    email="zhangsan@example.com",
    age=25
)

# 类型错误会抛出异常
try:
    invalid_user = User(
        id="not_an_int",  # 类型错误
        name="张",
        email="invalid-email",
        age=200
    )
except Exception as e:
    print(f"验证失败: {e}")

---

13. 小结

概念	语法	说明
基本类型	str, int, float, bool	内置类型直接使用
Optional	X | None	可空类型
容器	list[T], dict[K, V]	泛型容器
Callable	Callable[[A, B], R]	函数类型
TypeVar	TypeVar('T')	泛型类型变量
Protocol	class P(Protocol)	结构化接口
Literal	Literal["a", "b"]	字面量类型
Final	Final[int]	不可变常量
mypy	mypy src/	静态类型检查器

---

14. 练习题

1. 为之前写的所有函数添加类型提示，并用 mypy 检查。
2. 实现一个泛型缓存类 Cache[K, V]，支持 get/set/delete。
3. 使用 Protocol 定义一个 Iterable 接口，并实现它。
4. 使用 Pydantic 创建一个 API 请求模型，包含数据验证。

---

下节预告：我们将学习代码风格规范和 Linting 工具，让代码更加整洁专业。

]]>