1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
My Cool Tool - 一个超厉害的工具
功能：blablabla
作者：xxx
日期：2026-04-08
"""

# ============ 导入区 ============
import sys
import os
import json
from pathlib import Path
from typing import Optional

# ============ 配置区 ============
# 这里放各种配置常量
DEFAULT_CONFIG = {
    "debug": False,
    "max_retries": 3,
    "timeout": 30,
}

# ============ 工具函数 ============
def validate_input(data: dict) -> bool:
    """验证输入数据是否合法"""
    return isinstance(data, dict) and "name" in data

def load_config(config_path: str) -> dict:
    """从文件加载配置"""
    with open(config_path, "r", encoding="utf-8") as f:
        return json.load(f)

# ============ 主逻辑 ============
class DataProcessor:
    """数据处理器"""
    
    def __init__(self, config: Optional[dict] = None):
        self.config = config or DEFAULT_CONFIG
    
    def process(self, data: dict) -> dict:
        """处理数据"""
        if not validate_input(data):
            raise ValueError("无效的输入数据")
        return {"result": f"处理完成: {data['name']}"}

def main():
    """入口函数"""
    print("工具启动中...")
    processor = DataProcessor()
    result = processor.process({"name": "测试数据"})
    print(f"结果: {result}")

if __name__ == "__main__":
    main()

1
2
3
4
5
6
7
8

# translator/__init__.py
"""Translator - 一个简洁的翻译工具包"""
__version__ = "1.0.0"

from .api import Translator
from .cache import CacheManager

__all__ = ["Translator", "CacheManager"]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

# translator/api.py
"""翻译 API 相关功能"""
from typing import Optional

class Translator:
    """翻译器类"""
    
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.request_count = 0
    
    def translate(self, text: str, target_lang: str = "en") -> str:
        """翻译文本"""
        self.request_count += 1
        # 这里是模拟，实际会调用翻译API
        return f"[{target_lang}] {text}"
    
    def batch_translate(self, texts: list, target_lang: str = "en") -> list:
        """批量翻译"""
        return [self.translate(t, target_lang) for t in texts]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

# main.py
"""命令行入口"""
from translator import Translator

def main():
    translator = Translator(api_key="your-api-key")
    result = translator.translate("你好世界", target_lang="en")
    print(result)  # 输出: [en] 你好世界

if __name__ == "__main__":
    main()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# pyproject.toml
[build-system]
requires = ["hatchling"]      # 构建后端
build-backend = "hatchling.build"

[project]
name = "my-awesome-project"
version = "1.0.0"
description = "一个超厉害的项目"
readme = "README.md"
license = { text = "MIT" }
requires-python = ">=3.10"
authors = [
    { name = "你的名字", email = "you@example.com" }
]
dependencies = [
    "requests>=2.28.0",
    "click>=8.0.0",
]

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# app/__init__.py
"""Flask 应用工厂"""
from flask import Flask
from app.extensions import init_extensions

def create_app(config_name: str = "default") -> Flask:
    """创建并配置 Flask 应用"""
    app = Flask(__name__)
    
    # 加载配置
    from app.config import configs
    app.config.from_object(configs[config_name])
    
    # 初始化扩展
    init_extensions(app)
    
    # 注册蓝图
    from app.routes.auth import auth_bp
    from app.routes.api import api_bp
    app.register_blueprint(auth_bp, url_prefix="/auth")
    app.register_blueprint(api_bp, url_prefix="/api")
    
    return app

1
2
3
4
5
6
7
8

# run.py
"""应用入口"""
from app import create_app

app = create_app()

if __name__ == "__main__":
    app.run(debug=True)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

# config.py - 基础配置
import os
from pathlib import Path

# 获取项目根目录
BASE_DIR = Path(__file__).resolve().parent

class Config:
    """基础配置类"""
    SECRET_KEY = os.environ.get("SECRET_KEY") or "dev-secret-key-change-me"
    DATABASE_URL = os.environ.get("DATABASE_URL") or f"sqlite:///{BASE_DIR}/app.db"
    DEBUG = False
    TESTING = False
    LOG_LEVEL = "INFO"

class DevelopmentConfig(Config):
    """开发环境配置"""
    DEBUG = True
    LOG_LEVEL = "DEBUG"

class ProductionConfig(Config):
    """生产环境配置"""
    DEBUG = False
    LOG_LEVEL = "WARNING"

class TestingConfig(Config):
    """测试环境配置"""
    TESTING = True
    DATABASE_URL = "sqlite:///:memory:"  # 内存数据库，测试专用

# 配置字典，通过环境变量选择
configs = {
    "development": DevelopmentConfig,
    "production": ProductionConfig,
    "testing": TestingConfig,
    "default": DevelopmentConfig,
}

1
2
3
4
5
6

# .env - 环境变量文件（不上传git！）
SECRET_KEY=your-super-secret-production-key
DATABASE_URL=postgresql://user:pass@localhost/mydb
DEBUG=False
LOG_LEVEL=INFO
API_KEY=your-api-key-here

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# .gitignore - 忽略这些文件
.env
__pycache__/
*.pyc
*.db
*.log
.venv/
venv/
env/
.pytest_cache/
.coverage
dist/
build/
*.egg-info/

1
2
3
4
5
6

# requirements.txt
flask==3.0.0
requests==2.31.0
click==8.1.7
python-dotenv==1.0.0
pydantic==2.5.0

1
2
3
4
5
6
7
8

# 安装 requirements.txt 中的所有依赖
pip install -r requirements.txt

# 导出当前环境的所有依赖
pip freeze > requirements.txt

# 导出时排除某些包
pip freeze | grep -v "pkg-resources" > requirements.txt

1
2
3
4
5
6
7

# 更灵活的开发用 requirements
# 使用 >= 而不是 ==，允许小幅升级
flask>=3.0.0
requests>=2.31.0

# 分环境依赖
-r requirements-dev.txt   # 引用另一个文件

1
2

# 安装 pip-tools
pip install pip-tools

1
2
3
4
5
6

# requirements.in - 你的源依赖文件（开发时维护这个）
# 使用灵活的版本说明
flask>=3.0.0
requests>=2.31.0
pytest>=7.0.0
black>=23.0.0

1
2
3
4

# 运行 pip-compile 生成锁定的依赖
pip-compile requirements.in

# 这会生成 requirements.txt，自动解析所有传递依赖并锁定版本

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

# requirements.txt - 自动生成，请勿手动编辑
#
#   pip-compile requirements.in
#
attrs==23.2.0
    # via jsonschema
black==24.1.1
    # via -r requirements.in (line 2)
click==8.1.7
    # via flask
flask==3.0.3
    # via -r requirements.in (line 1)
itsdangerous==2.1.2
    # via flask
jinja2==3.1.3
    # via flask
markupsafe==2.1.5
    # via jinja2
pytest==8.0.0
    # via -r requirements.in (line 3)
requests==2.31.0
    # via -r requirements.in (line 2)

1
2
3
4
5

# 安装锁定的依赖
pip-sync requirements.txt

# pip-sync 会自动卸载不在 requirements.txt 中的包
# 并安装所有在 requirements.txt 中的包

1
2
3
4
5
6
7
8

# 安装 Poetry
pip install poetry

# 初始化项目
poetry new my-awesome-project

# 或在现有项目中初始化
poetry init

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# pyproject.toml - Poetry 配置示例
[tool.poetry]
name = "my-awesome-project"
version = "1.0.0"
description = "一个使用 Poetry 管理的项目"
authors = ["你的名字 <you@example.com>"]

[tool.poetry.dependencies]
python = "^3.10"
flask = "^3.0"
requests = "^2.31"

[tool.poetry.group.dev.dependencies]
pytest = "^7.0"
black = "^23.0"
mypy = "^1.0"

[tool.poetry.scripts]
my-script = "my_awesome_project.main:main"

[build-system]
requires = ["poetry-core"]
build-backend = "poetry.core.masonry.api"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# 核心命令
poetry install          # 安装依赖（自动创建虚拟环境）
poetry add requests     # 添加依赖
poetry add --dev pytest # 添加开发依赖
poetry remove requests  # 移除依赖
poetry update          # 更新锁定文件
poetry lock            # 只更新锁定文件（不安装）
poetry run python xxx.py  # 在虚拟环境中运行命令
poetry shell           # 进入虚拟环境的 shell

# 打包发布
poetry build            # 构建包
poetry publish          # 发布到 PyPI

1
2
3
4
5
6
7
8

# 使用 Poetry 管理的项目结构示例
from my_awesome_project import __version__

def main():
    print(f"项目版本: {__version__}")  # 输出: 项目版本: 1.0.0

if __name__ == "__main__":
    main()

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# 安装 PDM
pip install pdm

# 初始化项目
pdm init

# 基本命令
pdm add requests         # 添加依赖
pdm add -dG dev pytest   # 添加开发组依赖
pdm install              # 安装依赖
pdm run pytest           # 运行测试
pdm build                # 构建包

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# pyproject.toml - PDM 配置
[project]
name = "my-project"
version = "1.0.0"
requires-python = ">=3.10"
dependencies = ["requests>=2.31"]

[tool.pdm.dev-dependencies]
dev = ["pytest>=7.0", "black>=23.0"]
test = ["pytest-cov>=4.0"]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# PDM 的 PEP 582 项目结构（不需要 .venv）
my-project/
├── __pypackages__/      # PEP 582 包目录（类 node_modules）
│   └── 3.10/
│       ├── lib/
│       └── include/
├── src/
│   └── my_project/
├── pyproject.toml
└── pdm.lock

1
2
3
4
5

# 安装 uv（单个脚本搞定）
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# 核心命令 - 速度感人
uv pip install requests              # 安装包
uv pip install -r requirements.txt   # 从文件安装
uv pip compile requirements.in -o requirements.txt  # 编译依赖（类似 pip-tools）
uv sync                              # 同步依赖
uv add requests                      # 添加依赖
uv add --dev pytest                  # 添加开发依赖
uv run python script.py              # 运行脚本（自动在临时环境）
uv run pytest                        # 运行测试

# 项目管理
uv init my-project                   # 初始化新项目
uv add httpx                         # 添加依赖（自动创建 pyproject.toml）

1
2
3

# uv 的速度有多快？做个对比
time pip install flask requests sqlalchemy  # pip: 慢...
time uv pip install flask requests sqlalchemy # uv: 毫秒级

1
2
3
4
5
6
7

# uv 的推荐工作流
uv init my-awesome-project   # 创建项目
cd my-awesome-project
uv add flask requests         # 添加依赖
uv add --dev pytest pytest-cov black mypy  # 添加开发依赖
uv run pytest                # 运行测试
uv build                     # 构建发布包

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

# test_calculator.py
import unittest
from calculator import Calculator, divide_by_zero_error

class TestCalculator(unittest.TestCase):
    """计算器类的单元测试"""
    
    def setUp(self):
        """每个测试方法前都会调用"""
        self.calc = Calculator()
    
    def test_add(self):
        """测试加法"""
        result = self.calc.add(2, 3)
        self.assertEqual(result, 5)
        self.assertEqual(self.calc.add(-1, 1), 0)
    
    def test_divide(self):
        """测试除法"""
        result = self.calc.divide(10, 2)
        self.assertEqual(result, 5)
        self.assertAlmostEqual(self.calc.divide(10, 3), 3.333333, places=5)
    
    def test_divide_by_zero(self):
        """测试除以零的情况"""
        with self.assertRaises(divide_by_zero_error):
            self.calc.divide(10, 0)
    
    def tearDown(self):
        """每个测试方法后都会调用（清理资源）"""
        pass

1
2
3
4

# 运行测试
python -m unittest test_calculator.py
python -m unittest discover                    # 自动发现所有测试
python -m unittest test_module.TestClass.test  # 运行特定测试

1
2
3
4
5
6
7
8
9

# 运行结果
# ....F.....
# ======================================================================
# FAIL: test_add (test_calculator.TestCalculator.test_add)
# ----------------------------------------------------------------------
# Traceback (most recent call last):
#   File "test_calculator.py", line 15, in test_add
#     self.assertEqual(result, 5)
# AssertionError: 6 != 5

1
2
3
4
5

# 安装
pip install pytest

# 或者用 uv
uv add --dev pytest

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# test_calculator.py - pytest 版本
from calculator import Calculator, divide_by_zero_error

def test_add():
    """测试加法 - 函数名以 test_ 开头即可"""
    calc = Calculator()
    assert calc.add(2, 3) == 5
    assert calc.add(-1, 1) == 0

def test_divide():
    """测试除法"""
    calc = Calculator()
    assert calc.divide(10, 2) == 5
    assert calc.divide(10, 3) == pytest.approx(3.333333, rel=1e-5)

def test_divide_by_zero():
    """测试除以零抛出异常"""
    calc = Calculator()
    with pytest.raises(divide_by_zero_error):
        calc.divide(10, 0)

def test_add_with_negative():
    calc = Calculator()
    assert calc.add(-5, -3) == -8
    assert calc.add(100, -50) == 50

1
2
3
4
5
6
7
8
9

# 运行 pytest
pytest                        # 当前目录所有测试
pytest test_file.py          # 指定文件
pytest tests/                # 指定目录
pytest -v                    # 详细输出（verbose，每个测试单独一行）
pytest --tb=short            # 简短的错误回溯
pytest -x                    # 遇到第一个失败就停止
pytest -k "add"              # 只运行名字包含 "add" 的测试
pytest --collect-only        # 只收集测试，不运行（看看有哪些测试）

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 输出示例
# ========================= test session starts =========================
# collected 4 items
#
# test_calculator.py::test_add PASSED                                  [ 25%]
# test_calculator.py::test_divide PASSED                              [ 50%]
# test_calculator.py::test_divide_by_zero PASSED                      [ 75%]
# test_calculator.py::test_add_with_negative PASSED                    [100%]
#
# ========================= 4 passed in 0.12s ===========================

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

import pytest
from app import create_app
from database import reset_db, seed_data

@pytest.fixture
def app():
    """创建测试用的 Flask 应用"""
    app = create_app("testing")
    yield app  # yield 相当于 setUp + tearDown

@pytest.fixture
def client(app):
    """创建测试客户端"""
    return app.test_client()

@pytest.fixture
def auth_headers():
    """认证头"""
    return {"Authorization": "Bearer test-token-123"}

@pytest.fixture
def sample_user():
    """创建测试用户数据"""
    return {
        "username": "testuser",
        "email": "test@example.com",
        "password": "testpassword123",
    }

def test_login(client, sample_user):
    """测试登录"""
    response = client.post("/api/login", json=sample_user)
    assert response.status_code == 200
    assert "token" in response.json

def test_get_profile(client, auth_headers):
    """测试获取个人资料"""
    response = client.get("/api/profile", headers=auth_headers)
    assert response.status_code == 200

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# 更高级的 fixture - 带参数和依赖
@pytest.fixture(scope="module")  # session/module/function，默认 function
def db_connection():
    """数据库连接 fixture"""
    conn = create_db_connection()
    yield conn
    conn.close()

@pytest.fixture
def clean_db(db_connection):
    """带依赖的 fixture"""
    db_connection.execute("DELETE FROM users")
    yield
    db_connection.execute("DELETE FROM users")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

import pytest

@pytest.mark.parametrize("input_data,expected", [
    ([2, 3], 5),
    ([0, 0], 0),
    ([-1, 1], 0),
    ([100, -50], 50),
    ([0.1, 0.2], pytest.approx(0.3)),
])
def test_add_parametrized(input_data, expected):
    """参数化测试加法"""
    calc = Calculator()
    a, b = input_data
    assert calc.add(a, b) == expected

@pytest.mark.parametrize("username,password,expected_status", [
    ("user1", "pass1", 200),
    ("user1", "wrongpass", 401),
    ("", "pass", 400),
    ("user1", "", 400),
])
def test_login_cases(client, username, password, expected_status):
    """参数化测试登录的各种情况"""
    response = client.post("/api/login", json={
        "username": username,
        "password": password,
    })
    assert response.status_code == expected_status

1
2
3
4
5
6
7

$ pytest -v test_parametrize.py

# test_parametrize.py::test_add_parametrized[2,3-5] PASSED         [ 20%]
# test_parametrize.py::test_add_parametrized[0,0-0] PASSED          [ 40%]
# test_parametrize.py::test_add_parametrized[-1,1-0] PASSED         [ 60%]
# test_parametrize.py::test_add_parametrized[100,-50-50] PASSED    [ 80%]
# test_parametrize.py::test_add_parametrized[0.1,0.2-0.3] PASSED   [100%]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

import pytest

@pytest.mark.slow          # 标记为慢测试
def test_full_integration():
    """完整的集成测试，很慢"""
    # 模拟运行 30 秒的测试
    pass

@pytest.mark.integration    # 标记为集成测试
def test_api_integration():
    """API 集成测试"""
    pass

@pytest.mark.unit           # 单元测试
def test_unit():
    """单元测试"""
    pass

@pytest.mark.skip(reason="这个功能还没实现")
def test_future_feature():
    """跳过的测试"""
    pass

@pytest.mark.skipif(sys.version_info < (3, 10), reason="需要 Python 3.10+")
def test_new_feature():
    """条件跳过"""
    pass

@pytest.mark.xfail(reason="已知问题，等待修复")
def test_known_issue():
    """预期失败的测试"""
    assert False

1
2
3
4
5
6

# 只运行带有特定标记的测试
pytest -m "slow"
pytest -m "not slow"           # 排除慢测试
pytest -m "unit and not slow"  # 组合条件

# 标记注册（在 pytest.ini 或 pyproject.toml 中）

1
2
3
4
5
6
7

# pyproject.toml 中配置 pytest markers
[tool.pytest.ini_options]
markers = [
    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
    "integration: marks tests as integration tests",
    "unit: marks tests as unit tests",
]

1
2
3
4
5
6
7
8

# 安装
pip install pytest-cov

# 运行并生成覆盖率报告
pytest --cov=my_app              # 覆盖率针对 my_app 包
pytest --cov=my_app tests/       # 指定测试目录
pytest --cov=.                    # 当前目录所有包
pytest --cov=my_app --cov-report=html  # 生成 HTML 报告

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

# 输出示例
# ---------- coverage: platform darwin, Python 3.10.12 ----------
# Name                    Stmts   Miss  Cover   Missing
# -----------------------------------------------------------
# my_app/__init__             5      0   100%
# my_app/api                 45      3    93%   67,89
# my_app/models              60     12    80%   45-52,78
# my_app/utils               30      0   100%
# -----------------------------------------------------------
# TOTAL                     140     15    89%

1
2
3
4
5
6
7

# 更多用法
pytest --cov=my_app --cov-report=term-missing  # 终端显示未覆盖行号
pytest --cov=my_app --cov-report=html --cov-report=term  # 多格式报告
pytest --cov=my_app -p no:cov  # 禁用覆盖率（某些 CI 配置）

# 最低覆盖率门禁
pytest --cov=my_app --cov-fail-under=80  # 低于 80% 则测试失败

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

from unittest.mock import Mock, patch, MagicMock
import pytest

def test_mock_basic():
    """最基本的 Mock 用法"""
    mock_obj = Mock()
    mock_obj.some_method.return_value = "mocked!"
    
    result = mock_obj.some_method(42, name="test")
    
    # 验证方法被调用了
    mock_obj.some_method.assert_called_once_with(42, name="test")
    assert result == "mocked!"

def test_mock_external_api():
    """模拟外部 API 调用"""
    with patch("requests.get") as mock_get:
        # 设置模拟返回值
        mock_response = Mock()
        mock_response.status_code = 200
        mock_response.json.return_value = {"user": "张三", "age": 25}
        mock_get.return_value = mock_response
        
        # 测试使用 requests 的函数
        from user_service import get_user_info
        result = get_user_info("user123")
        
        assert result["user"] == "张三"
        mock_get.assert_called_once_with("https://api.example.com/user/user123")

def test_mock_class():
    """Mock 整个类"""
    mock_db = MagicMock(spec=Database)  # spec 限制只能调用真实存在的方法
    mock_db.query.return_value = [{"id": 1, "name": "测试"}]
    
    service = UserService(mock_db)
    users = service.list_users()
    
    assert len(users) == 1
    assert users[0]["name"] == "测试"

def test_patch_decorator():
    """用装饰器 patch"""
    @patch("datetime.datetime.now")
    def test_with_mocked_time(mock_now):
        mock_now.return_value = Mock(hour=10)
        
        result = get_greeting()  # 根据时间返回问候语
        assert result == "早上好！"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# 模拟文件操作
from unittest.mock import mock_open, patch

def test_read_config():
    """模拟读取配置文件"""
    fake_config = """
DATABASE_URL=postgresql://localhost/testdb
SECRET_KEY=abc123
DEBUG=true
"""
    with patch("builtins.open", mock_open(read_data=fake_config)):
        from config import load_config
        config = load_config("config.ini")
        
        assert config["DATABASE_URL"] == "postgresql://localhost/testdb"
        assert config["DEBUG"] == "true"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

# TDD 示例：实现一个栈（Stack）数据结构

# ========== 步骤 1：先写测试（RED）==========
# test_stack.py

def test_stack_is_empty():
    """新创建的栈应该是空的"""
    stack = Stack()
    assert stack.is_empty() is True

def test_stack_push():
    """push 后栈不为空"""
    stack = Stack()
    stack.push(1)
    assert stack.is_empty() is False

def test_stack_pop():
    """pop 应该返回最后 push 的元素"""
    stack = Stack()
    stack.push(1)
    stack.push(2)
    assert stack.pop() == 2

def test_stack_pop_order():
    """栈是 LIFO（后进先出）"""
    stack = Stack()
    stack.push(1)
    stack.push(2)
    stack.push(3)
    assert stack.pop() == 3
    assert stack.pop() == 2
    assert stack.pop() == 1

def test_pop_empty_stack():
    """空栈 pop 应该抛出异常"""
    stack = Stack()
    with pytest.raises(StackUnderflowError):
        stack.pop()

1
2
3

# 运行测试 - 当然是失败的，因为 Stack 还没实现
$ pytest test_stack.py -v
# E   NameError: name 'Stack' is not defined

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

# ========== 步骤 2：写最简实现让测试通过（GREEN）==========

class StackUnderflowError(Exception):
    """栈下溢异常"""
    pass

class Stack:
    """栈数据结构 - LIFO"""
    
    def __init__(self):
        self._items = []
    
    def is_empty(self) -> bool:
        return len(self._items) == 0
    
    def push(self, item):
        self._items.append(item)
    
    def pop(self):
        if self.is_empty():
            raise StackUnderflowError("Cannot pop from empty stack")
        return self._items.pop()

1
2
3

# 再运行测试 - 全部通过
$ pytest test_stack.py -v
# ===== 5 passed in 0.03s =====

1
2
3
4
5
6

# ========== 步骤 3：重构 - 让代码更优雅 ==========
# 现在的实现已经很简单了，但如果我们想优化...
# 可以考虑用列表替代 `_items`，或者添加更多功能
# 运行测试确保重构没有破坏功能
$ pytest test_stack.py -v
# ===== 5 passed in 0.03s =====

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

import logging

# 创建 logger
logger = logging.getLogger(__name__)

# 设置级别（只会记录 >= 此级别的日志）
logger.setLevel(logging.DEBUG)

# 使用
logger.debug("这是一条调试信息")
logger.info("这是一般信息")
logger.warning("这是一条警告")
logger.error("这是一条错误信息")
logger.critical("这是严重错误信息")

1
2
3
4

# 输出
# WARNING:__name__:这是一条警告
# ERROR:__name__:这是一条错误信息
# CRITICAL:__name__:这是严重错误信息

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

import logging

# 1. 创建 logger
logger = logging.getLogger("my_app")
logger.setLevel(logging.DEBUG)

# 2. 创建 Formatter（决定日志格式）
file_formatter = logging.Formatter(
    "%(asctime)s - %(name)s - %(levelname)s - %(filename)s:%(lineno)d - %(message)s"
)
console_formatter = logging.Formatter(
    "%(levelname)s - %(message)s"
)

# 3. 创建 Handler（决定输出到哪里）
# 控制台处理器
console_handler = logging.StreamHandler()
console_handler.setLevel(logging.INFO)      # 控制台只显示 INFO 及以上
console_handler.setFormatter(console_formatter)

# 文件处理器
file_handler = logging.FileHandler(
    "app.log",
    encoding="utf-8",
    mode="a"                                  # append 模式
)
file_handler.setLevel(logging.DEBUG)          # 文件记录 DEBUG 及以上
file_handler.setFormatter(file_formatter)

# 4. 把 Handler 加到 Logger 上
logger.addHandler(console_handler)
logger.addHandler(file_handler)

# 5. 使用
logger.debug("这条只在文件里")
logger.info("这条文件和控制台都有")
logger.warning("这条文件和控制台都有（警告）")

1
2
3
4
5
6
7
8

import logging

# 最简单的配置（输出到控制台，级别为 WARNING 及以上）
logging.basicConfig(level=logging.WARNING)

logging.debug("调试信息")  # 不显示
logging.info("一般信息")   # 不显示
logging.warning("警告信息")  # 显示

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# 稍微完整一点的配置
logging.basicConfig(
    level=logging.DEBUG,
    format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
    datefmt="%Y-%m-%d %H:%M:%S",
    handlers=[
        logging.StreamHandler(),            # 控制台
        logging.FileHandler("app.log", encoding="utf-8"),  # 文件
    ],
)

logger = logging.getLogger(__name__)
logger.info("应用启动")

1

pip install loguru

1
2
3
4
5
6
7
8

from loguru import logger

# 开箱即用，不需要任何配置！
logger.info("你好，日志！")
logger.success("成功了！")
logger.warning("警告！")
logger.error("出错了！")
logger.debug("调试信息")

1
2
3
4
5
6

# 输出
# 2026-04-08 10:20:01 | INFO    | root: 你好，日志！
# 2026-04-08 10:20:01 | SUCCESS | root: 成功了！
# 2026-04-08 10:20:01 | WARNING | root: 警告！
# 2026-04-08 10:20:01 | ERROR   | root: 出错了！
# 2026-04-08 10:20:01 | DEBUG   | root: 调试信息

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# 移除默认处理器，添加自定义文件输出
from loguru import logger
import sys

# 移除默认的 stderr 处理器
logger.remove()

# 添加自定义文件处理器
logger.add(
    "app_{time}.log",                       # 文件名（带时间）
    rotation="500 MB",                      # 文件超过 500MB 则轮转
    retention="10 days",                    # 保留 10 天
    compression="zip",                      # 压缩旧日志
    level="DEBUG",
    format="{time:YYYY-MM-DD HH:mm:ss} | {level} | {name}:{function}:{line} - {message}",
)

# 添加控制台输出
logger.add(
    sys.stderr,
    level="INFO",
    format="<green>{time:HH:mm:ss}</green> | <level>{message}</level>",
)

# 使用
logger.info("请求来了: {}", request_id)  # {} 格式化，性能更好
logger.info("用户 {user} 登录了", user="张三")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

# 异常捕获 - loguru 的杀手级功能
from loguru import logger

def dangerous_function():
    return 1 / 0

# 方法1：装饰器
@logger.catch
def main():
    dangerous_function()

# 方法2：上下文管理器
with logger.catch():
    dangerous_function()

# 方法3：手动记录
try:
    dangerous_function()
except ZeroDivisionError:
    logger.exception("出错了，但没关系我们记录了上下文")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# 完整示例
from loguru import logger
import sys

# 配置
logger.remove()  # 移除默认处理器

# 控制台：只显示 WARNING 及以上，彩色输出
logger.add(
    sys.stderr,
    level="WARNING",
    format="<red>{time:HH:mm:ss}</red> | <level>{level}</level> | {message}",
)

# 文件：记录所有级别
logger.add(
    "app.log",
    level="DEBUG",
    rotation="00:00",        # 每天午夜轮转
    retention="30 days",
    format="{time:YYYY-MM-DD HH:mm:ss} | {level:8} | {name}:{line} - {message}",
)

logger.info("应用启动")
logger.warning("这是一个警告")
logger.error("这是一个错误")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

import os

# 读取环境变量
db_url = os.environ.get("DATABASE_URL")
api_key = os.environ.get("API_KEY", "default-key")  # 提供默认值

# 设置环境变量（仅当前进程）
os.environ["DEBUG"] = "true"

# 读取并转换类型
timeout = int(os.environ.get("TIMEOUT", "30"))  # 默认 30 秒
debug = os.environ.get("DEBUG", "false").lower() == "true"

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

# 类型安全的配置读取
from typing import Optional

class Config:
    """从环境变量读取配置"""
    
    @property
    def database_url(self) -> str:
        return os.environ["DATABASE_URL"]
    
    @property
    def debug(self) -> bool:
        return os.environ.get("DEBUG", "false").lower() in ("true", "1", "yes")
    
    @property
    def max_connections(self) -> int:
        value = os.environ.get("MAX_CONNECTIONS", "10")
        return int(value)
    
    @property
    def secret_key(self) -> Optional[str]:
        return os.environ.get("SECRET_KEY")
    
    def validate(self):
        """验证必需的配置"""
        required = ["DATABASE_URL", "SECRET_KEY"]
        missing = [k for k in required if k not in os.environ]
        if missing:
            raise ValueError(f"缺少必需的环境变量: {', '.join(missing)}")

config = Config()
config.validate()

1

pip install python-dotenv

1
2
3
4
5
6
7
8

# .env 文件（不要上传到 Git！）
SECRET_KEY=your-secret-key-here
DATABASE_URL=postgresql://user:pass@localhost/mydb
DEBUG=true
LOG_LEVEL=DEBUG
API_KEY=your-api-key
REDIS_URL=redis://localhost:6379
MAX_WORKERS=4

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

# settings.py - 配置管理
import os
from pathlib import Path
from dotenv import load_dotenv

# 找到 .env 文件（在项目根目录）
project_root = Path(__file__).resolve().parent.parent
env_path = project_root / ".env"

# 加载 .env 文件
load_dotenv(env_path)
# 也可以不传路径，默认在当前目录和父目录找
# load_dotenv()  # 简单写法

# 读取配置（现在 os.environ 里就有 .env 中的值了）
SECRET_KEY = os.environ["SECRET_KEY"]
DATABASE_URL = os.environ.get("DATABASE_URL", "sqlite:///app.db")
DEBUG = os.environ.get("DEBUG", "false").lower() == "true"
LOG_LEVEL = os.environ.get("LOG_LEVEL", "INFO")

1
2
3
4
5
6
7

# 自动加载 .env 到 shell 环境（用于本地开发）
# 在项目根目录运行：
# dotenv run python your_script.py

# 或者用命令行
# dotenv set DEBUG true
# dotenv list

1

pip install pydantic-settings

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

from pydantic_settings import BaseSettings, SettingsConfigDict
from typing import Optional

class Settings(BaseSettings):
    """应用配置 - pydantic-settings 版本"""
    
    # 只需要声明字段和类型，自动从环境变量读取
    database_url: str
    secret_key: str
    debug: bool = False  # 带默认值
    log_level: str = "INFO"
    max_connections: int = 10
    api_key: Optional[str] = None
    
    # 配置
    model_config = SettingsConfigDict(
        env_file=".env",           # 从 .env 文件读取
        env_file_encoding="utf-8",
        case_sensitive=False,       # 环境变量大小写不敏感
        extra="ignore",             # 忽略额外字段
    )

# 使用
settings = Settings()
print(settings.database_url)
print(f"调试模式: {settings.debug}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

# 嵌套配置（使用 pydantic BaseModel）
from pydantic_settings import BaseSettings, SettingsConfigDict
from pydantic import BaseModel

class DatabaseSettings(BaseModel):
    """数据库配置"""
    host: str = "localhost"
    port: int = 5432
    name: str = "mydb"
    user: str
    password: str

class Settings(BaseSettings):
    """主配置类"""
    database: DatabaseSettings
    
    model_config = SettingsConfigDict(env_file=".env")

# .env 中可以这样写：
# DATABASE__HOST=db.example.com
# DATABASE__PORT=5432
# DATABASE__NAME=production_db
# DATABASE__USER=admin
# DATABASE__PASSWORD=secret

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20

; config.ini - INI 配置文件示例
[database]
host = localhost
port = 5432
name = mydb
user = admin
password = secret123

[server]
host = 0.0.0.0
port = 8000
debug = true

[logging]
level = INFO
file = app.log

[cache]
enabled = true
ttl = 3600

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

import configparser

# 读取配置
config = configparser.ConfigParser()
config.read("config.ini", encoding="utf-8")

# 访问配置
db_host = config["database"]["host"]
db_port = config.getint("database", "port")  # 自动转 int
db_debug = config.getboolean("server", "debug")  # 自动转 bool

# 遍历配置
for section in config.sections():
    print(f"[{section}]")
    for key, value in config[section].items():
        print(f"  {key} = {value}")

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# 写入配置
config = configparser.ConfigParser()
config["database"] = {
    "host": "localhost",
    "port": "5432",
    "name": "mydb",
}
config["server"] = {
    "debug": "true",
}

with open("config_new.ini", "w", encoding="utf-8") as f:
    config.write(f)