第 3 章：Python 工程化

# 创建虚拟环境（在项目根目录执行）
python -m venv .venv

# Windows 激活
.venv\Scripts\activate

# macOS/Linux 激活
source .venv/bin/activate

# 激活后，命令行提示符前会出现 (.venv)
# 退出虚拟环境
deactivate

# 创建环境并指定 Python 版本
conda create -n myproject python=3.11

# 激活环境
conda activate myproject

# 安装包（同时安装 numpy、pandas 等科学计算库）
conda install numpy pandas matplotlib

# 导出环境配置
conda env export > environment.yml

# 从配置重建环境
conda env create -f environment.yml

# 退出环境
conda deactivate

# 安装 uv（跨平台）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 创建虚拟环境
uv venv .venv

# 激活（与 venv 相同）
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows

# 安装包（极速！）
uv pip install requests fastapi

# 从 requirements.txt 安装
uv pip install -r requirements.txt

# requirements.txt
requests>=2.28.0
fastapi==0.104.0
pydantic>=2.0.0,<3.0.0
pytest>=7.0.0; python_version >= "3.8"

# 开发依赖（通常放在 requirements-dev.txt）
black
ruff
mypy
pytest-cov

# 生成当前环境的依赖列表
pip freeze > requirements.txt

# 安装依赖
pip install -r requirements.txt

# pyproject.toml
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-awesome-project"
version = "0.1.0"
description = "一个示例项目"
readme = "README.md"
requires-python = ">=3.9"
license = { text = "MIT" }
authors = [
    { name = "你的名字", email = "you@example.com" }
]
keywords = ["web", "api", "fastapi"]
classifiers = [
    "Development Status :: 4 - Beta",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.9",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
]

dependencies = [
    "fastapi>=0.104.0",
    "uvicorn[standard]>=0.24.0",
    "pydantic>=2.0.0",
    "sqlalchemy>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "black>=23.0.0",
    "ruff>=0.1.0",
    "mypy>=1.0.0",
]

[project.scripts]
mycli = "my_project.cli:main"

[tool.black]
line-length = 88
target-version = ['py39']

[tool.ruff]
line-length = 88
select = ["E", "F", "I", "N", "W", "UP"]

[tool.mypy]
python_version = "3.9"
strict = true
warn_return_any = true

# 安装 Poetry
pip install poetry

# 创建新项目（类似 npm init）
poetry new my-project
cd my-project

# 添加依赖（类似 npm install）
poetry add fastapi uvicorn

# 添加开发依赖（类似 npm install -D）
poetry add --group dev pytest black ruff

# 安装所有依赖（类似 npm install）
poetry install

# 进入项目的虚拟环境（类似 npx）
poetry shell

# 直接运行命令（无需进入 shell）
poetry run python main.py
poetry run pytest

# 锁定依赖版本（类似 package-lock.json）
poetry lock

# 构建并发布到 PyPI（类似 npm publish）
poetry build
poetry publish

# 初始化项目（创建 pyproject.toml）
uv init my-project
cd my-project

# 添加依赖
uv add fastapi uvicorn

# 添加开发依赖
uv add --dev pytest black ruff

# 运行脚本（自动使用项目虚拟环境）
uv run python main.py

# 运行测试
uv run pytest

# 同步依赖（根据 pyproject.toml 安装）
uv sync

# 生成锁定文件
uv lock

# src layout（推荐）
my-project/
├── src/
│   └── my_project/          # 包目录（注意下划线命名）
│       ├── __init__.py      # 包初始化文件
│       ├── models.py
│       ├── services/
│       │   ├── __init__.py
│       │   └── user_service.py
│       └── utils/
│           ├── __init__.py
│           └── helpers.py
├── tests/
│   ├── __init__.py
│   ├── test_models.py
│   └── test_services/
├── docs/
├── scripts/
├── pyproject.toml
├── README.md
├── .gitignore
└── .venv/

# flat layout（简单项目可用）
my-project/
├── my_project/              # 包直接在根目录
│   ├── __init__.py
│   └── ...
├── tests/
├── pyproject.toml
└── ...

# src/my_project/__init__.py
"""My Project - 一个示例 Python 包.

类似 JS 的 index.js，控制包的公开 API。
"""

from .models import User, Post
from .services.user_service import UserService

# __all__ 定义 from my_project import * 时导出的内容
# 类似 JS 的 export { ... }
__all__ = ["User", "Post", "UserService"]

# 包级别的常量
VERSION = "0.1.0"

# src/my_project/services/__init__.py
"""服务层模块.

通过 __init__.py 重新导出，简化导入路径。
类似 JS 的 barrel export（桶式导出）。
"""

from .user_service import UserService
from .email_service import EmailService

__all__ = ["UserService", "EmailService"]

# 使用方式：
# from my_project.services import UserService
# 而不是：
# from my_project.services.user_service import UserService

# Python
__pycache__/
*.py[cod]
*.so
.Python
*.egg-info/
dist/
build/
eggs/
*.egg

# 虚拟环境
.venv/
venv/
ENV/
env/

# IDE
.vscode/
.idea/
*.swp
*.swo
*~

# 环境变量
.env
.env.local
.env.*.local

# 测试和覆盖率
.pytest_cache/
.coverage
htmlcov/
.tox/

# 类型检查
.mypy_cache/

# 操作系统
.DS_Store
Thumbs.db

# Jupyter
.ipynb_checkpoints/

# 项目特定
logs/
*.log
data/
*.db
*.sqlite

# 安装
pip install black

# 格式化单个文件
black main.py

# 格式化整个目录
black src/

# 检查格式（不修改，CI 中使用）
black --check src/

# 查看差异
black --diff src/

# 安装
pip install ruff

# 检查代码（类似 eslint）
ruff check src/

# 自动修复可修复的问题（类似 eslint --fix）
ruff check --fix src/

# 检查并格式化（包含 black 功能）
ruff format src/

# 查看所有规则
ruff linter

# pyproject.toml 中的 Ruff 配置
[tool.ruff]
target-version = "py39"      # 目标 Python 版本，类似 ESLint 的 env
line-length = 88

[tool.ruff.lint]
select = [
    "E",   # pycodestyle errors（类似 ESLint 的 error 规则）
    "F",   # Pyflakes（未使用变量等）
    "I",   # isort（导入排序，类似 ESLint 的 sort-imports）
    "N",   # pep8-naming（命名规范）
    "W",   # pycodestyle warnings
    "UP",  # pyupgrade（升级语法）
    "B",   # flake8-bugbear（潜在 Bug）
    "C4",  # flake8-comprehensions（推导式优化）
]
ignore = ["E501"]  # 行过长由 Black 处理

[tool.ruff.lint.pydocstyle]
convention = "google"  # 文档字符串风格

# 安装
pip install mypy

# 类型检查
mypy src/

# 严格模式（推荐）
mypy --strict src/

# 生成报告
mypy --html-report mypy-report src/

# pyproject.toml 中的 MyPy 配置
[tool.mypy]
python_version = "3.9"
strict = true                    # 严格模式，类似 TS 的 strict: true
warn_return_any = true           # 返回 Any 时警告
warn_unused_ignores = true       # 未使用的 type: ignore 警告
disallow_untyped_defs = true     # 要求所有函数都有类型注解
ignore_missing_imports = true    # 第三方库无类型存根时不报错

# 安装 pre-commit
pip install pre-commit

# 创建 .pre-commit-config.yaml
cat > .pre-commit-config.yaml << 'EOF'
repos:
  - repo: https://github.com/astral-sh/ruff-pre-commit
    rev: v0.3.0
    hooks:
      - id: ruff
        args: [--fix]
      - id: ruff-format

  - repo: https://github.com/pre-commit/mirrors-mypy
    rev: v1.9.0
    hooks:
      - id: mypy
EOF

# 安装钩子
pre-commit install

# 手动运行（测试配置）
pre-commit run --all-files

# tests/test_calculator.py
"""计算器模块的单元测试.

对比 JS：pytest ≈ Jest/Vitest，assert 比 expect().toBe() 更简洁。
"""

from src.my_project.calculator import add, divide


class TestCalculator:
    """测试类，类似 JS 的 describe() 分组。"""

    def test_add_positive_numbers(self) -> None:
        """测试正数相加。类似 JS 的 it('should add positive numbers', ...)"""
        result = add(2, 3)
        assert result == 5  # 原生 assert，pytest 会自动提供详细错误信息

    def test_add_negative_numbers(self) -> None:
        """测试负数相加。"""
        assert add(-1, -2) == -3

    def test_divide_by_zero(self) -> None:
        """测试除以零异常。类似 JS 的 expect(() => ...).toThrow()"""
        with pytest.raises(ZeroDivisionError):
            divide(10, 0)

    def test_list_equality(self) -> None:
        """测试列表相等。"""
        assert [1, 2, 3] == [1, 2, 3]
        # 如果不相等，pytest 会显示详细差异，类似 Jest 的 diff

# 运行测试
pytest

# 显示详细输出
pytest -v

# 运行特定文件
pytest tests/test_calculator.py

# 运行特定测试类
pytest tests/test_calculator.py::TestCalculator

# 运行特定方法
pytest tests/test_calculator.py::TestCalculator::test_add

# 遇到第一个失败就停止（类似 npm test -- --bail）
pytest -x

# 失败时进入 PDB 调试
pytest --pdb

# tests/test_user_service.py
import pytest
from src.my_project.services.user_service import UserService
from src.my_project.models import User


@pytest.fixture
def user_service() -> UserService:
    """创建用户服务实例。

    类似 Jest 的 setup() 或 Vitest 的 beforeEach()，
    但 pytest 通过参数注入，更灵活。
    """
    service = UserService()
    yield service  # yield 前是 setup，yield 后是 teardown
    # 清理代码（类似 afterEach）
    service.cleanup()


@pytest.fixture(scope="module")
def test_database() -> None:
    """模块级 fixture，整个测试模块只执行一次。

    scope 选项：function（默认）、class、module、package、session
    类似 Jest 的 beforeAll/afterAll。
    """
    db = create_test_database()
    yield db
    db.drop_all()


class TestUserService:
    def test_create_user(self, user_service: UserService) -> None:
        """fixture 通过参数名自动注入。"""
        user = user_service.create_user(name="张三", email="zhang@example.com")
        assert user.name == "张三"
        assert user.id is not None

    def test_get_user(self, user_service: UserService) -> None:
        """每个测试方法都会获得独立的 fixture 实例。"""
        user = user_service.create_user(name="李四", email="li@example.com")
        found = user_service.get_user(user.id)
        assert found is not None
        assert found.name == "李四"

# tests/test_parametrize.py
import pytest
from src.my_project.calculator import add


# 类似 Jest 的 test.each([
#   [1, 1, 2],
#   [2, 3, 5],
# ])('add(%i, %i) = %i', (a, b, expected) => { ... })
@pytest.mark.parametrize("a,b,expected", [
    (1, 1, 2),
    (2, 3, 5),
    (-1, 1, 0),
    (-1, -1, -2),
    (0, 0, 0),
])
def test_add_parametrized(a: int, b: int, expected: int) -> None:
    """参数化测试：一组数据生成多个测试用例。"""
    assert add(a, b) == expected


# 也可以参数化 fixture
@pytest.fixture(params=["sqlite", "postgresql", "mysql"])
def database(request: pytest.FixtureRequest) -> str:
    """为每种数据库类型运行一次测试。"""
    return request.param


def test_database_connection(database: str) -> None:
    """这个测试会执行 3 次，分别对应 3 种数据库。"""
    assert connect(database) is not None

# 安装
pip install pytest-cov

# 生成终端覆盖率报告
pytest --cov=src/my_project

# 生成 HTML 报告（在 htmlcov/ 目录查看）
pytest --cov=src/my_project --cov-report=html

# 生成 XML 报告（CI 工具使用）
pytest --cov=src/my_project --cov-report=xml

# 设置最低覆盖率门槛（低于则失败）
pytest --cov=src/my_project --cov-fail-under=80

# src/my_project/typed_examples.py
"""Python 类型注解示例，附 TypeScript 对比。

Python 3.10+ 推荐使用 | 代替 Union，类似 TS 的联合类型。
"""

from typing import Optional, List, Dict, Callable, TypedDict


# ========== 基础类型 ==========

# Python
def greet(name: str) -> str:
    return f"Hello, {name}"

# TypeScript 对比：
# function greet(name: string): string {
#     return `Hello, ${name}`;
# }


# ========== 可选类型 ==========

# Python 3.10+ 推荐写法（| 语法）
def find_user(user_id: int) -> User | None:
    ...

# Python 3.9 及以前
# def find_user(user_id: int) -> Optional[User]:
#     ...

# TypeScript 对比：
# function findUser(userId: number): User | null { ... }


# ========== 列表和字典 ==========

# Python 3.9+ 推荐写法
def process_items(items: list[str]) -> dict[str, int]:
    return {item: len(item) for item in items}

# Python 3.8 及以前
# def process_items(items: List[str]) -> Dict[str, int]:
#     ...

# TypeScript 对比：
# function processItems(items: string[]): Record { ... }


# ========== 函数类型 ==========

# Python
Handler = Callable[[int, str], bool]

def register_handler(handler: Handler) -> None:
    ...

# TypeScript 对比：
# type Handler = (a: number, b: string) => boolean;
# function registerHandler(handler: Handler): void { ... }

from typing import TypedDict, NotRequired


# Python TypedDict
class UserConfig(TypedDict):
    name: str
    age: int
    email: str
    avatar: NotRequired[str]  # 可选字段，类似 TS 的 avatar?: string


# TypeScript 对比：
# interface UserConfig {
#     name: string;
#     age: number;
#     email: string;
#     avatar?: string;
# }


def update_config(config: UserConfig) -> None:
    print(config["name"])  # IDE 会提示可用键名
    # config["nam"]  # MyPy 报错：TypedDict "UserConfig" has no key 'nam'


# 使用
config: UserConfig = {
    "name": "张三",
    "age": 25,
    "email": "zhang@example.com",
}
update_config(config)

from dataclasses import dataclass
from datetime import datetime


# Python @dataclass
@dataclass
class User:
    id: int
    name: str
    email: str
    created_at: datetime = datetime.now()
    is_active: bool = True


# TypeScript 对比（需要手动写构造函数）：
# class User {
#     constructor(
#         public id: number,
#         public name: string,
#         public email: string,
#         public createdAt: Date = new Date(),
#         public isActive: boolean = true,
#     ) {}
# }


# 使用
user = User(id=1, name="张三", email="zhang@example.com")
print(user.name)  # 张三
# 自动获得 __repr__、__eq__ 等方法
print(user)  # User(id=1, name='张三', ...)

# .github/workflows/ci.yml
name: Python 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: |
          python -m pip install --upgrade pip
          pip install ruff pytest pytest-cov mypy
          pip install -e ".[dev]"

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

      - name: MyPy 类型检查
        run: mypy src/ --ignore-missing-imports

      - name: pytest 测试 + 覆盖率
        run: pytest --cov=src --cov-report=xml --cov-fail-under=80

      - name: 上传覆盖率报告
        uses: codecov/codecov-action@v4
        with:
          file: ./coverage.xml

# .editorconfig
root = true

[*]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.py]
indent_style = space
indent_size = 4

[*.{html,css,js,json,yml,yaml,toml}]
indent_style = space
indent_size = 2

[Makefile]
indent_style = tab

[*.md]
trim_trailing_whitespace = false