Python 项目工程化实战（三）：mypy 类型检查 + uv build 打包发布 PyPI 全流程 | Python 进阶

1
[tool.mypy]
2
python_version = "3.12"
3
files = ["src", "tests"]
4
warn_unused_ignores = true
5
warn_redundant_casts = true
6
warn_no_return = true
7
show_error_codes = true

1
[tool.mypy]
2
python_version = "3.12"
3
files = ["src", "tests"]
4
show_error_codes = true
5

6
# —— 逐步开启的严格子项 ——
7
disallow_untyped_defs = true
8
disallow_incomplete_defs = true
9
check_untyped_defs = true
10
disallow_untyped_decorators = true
11
warn_return_any = true
12
no_implicit_optional = true
13
warn_unused_ignores = true
14
warn_redundant_casts = true
15
warn_no_return = true
16
warn_unreachable = true
17
strict_equality = true

1
# ❌ 偷懒：整行忽略，掩盖真问题
2
result = legacy_api()  # type: ignore
3

4
# ✅ 精准忽略，保留其他检查
5
result = legacy_api()  # type: ignore[assignment]
6

7
# ✅ 更好：用 cast 显式表达「我比 mypy 更懂这里」
8
from typing import cast
9
result = cast(Order, legacy_api())

1
from typing import TypeVar, Sequence
2

3
T = TypeVar("T")
4

5
def first(items: Sequence[T]) -> T | None:
6
    return items[0] if items else None
7

8
first([1, 2, 3])        # 推断为 int | None
9
first(("a", "b"))        # 推断为 str | None

1
from collections.abc import Callable
2

3
def retry(times: int, fn: Callable[[int], str]) -> str:
4
    for i in range(times):
5
        result = fn(i)
6
        if result:
7
            return result
8
    return ""

1
from typing import Protocol
2

3
class Renderable(Protocol):
4
    def render(self) -> str: ...
5

6
def draw(obj: Renderable) -> None:
7
    print(obj.render())
8

9
class Circle:
10
    def render(self) -> str:   # 不需要显式继承，只要有 render 就满足
11
        return "○"
12

13
draw(Circle())   # ✅ mypy 通过

1
from typing import Literal, overload
2

3
Mode = Literal["fast", "slow"]
4

5
@overload
6
def parse(data: str) -> dict[str, str]: ...
7
@overload
8
def parse(data: bytes) -> dict[str, int]: ...
9

10
def parse(data: str | bytes) -> dict[str, str] | dict[str, int]:
11
    # 实现体
12
    ...

1
x = [1, "a", 3.0]
2
reveal_type(x)   # mypy 输出：Revealed type is "list[int | str | float]"

1
cfg = weird_lib.load()  # type: ignore[import-untyped]

1
# 在你的包里建 stubs/weird_lib/__init__.pyi
2
def load(path: str) -> dict[str, str]: ...
3
def save(data: dict[str, str], path: str) -> None: ...

1
# pyproject.toml 告诉 mypy 去哪找 stub
2
[tool.mypy]
3
mypy_path = "stubs"

1
# .github/workflows/ci.yml（节选）
2
  type-check:
3
    runs-on: ubuntu-latest
4
    steps:
5
      - uses: actions/checkout@v4
6
      - uses: astral-sh/setup-uv@v5
7
      - run: uv sync --all-extras
8
      - name: mypy
9
        run: uv run mypy src tests
10
      - name: pytest
11
        run: uv run pytest --cov --cov-fail-under=80

1
[project]
2
name = "my-package"
3
version = "0.1.0"
4
description = "一个示例 Python 库"
5
readme = "README.md"
6
requires-python = ">=3.10"
7
license = { text = "MIT" }
8
authors = [{ name = "九所长", email = "hi@971918.xyz" }]
9
keywords = ["example", "demo"]
10
dependencies = [
11
    "httpx>=0.27",
12
    "pydantic>=2.0",
13
]
14

15
[project.urls]
16
Homepage = "https://github.com/yourname/my-package"
17
Documentation = "https://my-package.readthedocs.io"
18

19
# 可选：命令行入口（安装后可直接在终端运行 my-cli）
20
[project.scripts]
21
my-cli = "my_package.cli:main"

1
[build-system]
2
requires = ["hatchling"]
3
build-backend = "hatchling.build"

1
[tool.hatch.build.targets.wheel]
2
packages = ["src/my_package"]

1
my-package/
2
├── pyproject.toml        # 唯一配置 + 打包元数据
3
├── README.md
4
├── LICENSE
5
├── src/
6
│   └── my_package/
7
│       ├── __init__.py
8
│       └── core.py
9
├── tests/
10
│   └── test_core.py
11
└── uv.lock

1
主版本.次版本.修订号  如 1.4.2
2
└─ 不兼容的 API 变更（破坏性）
3
   └─ 向下兼容的功能新增
4
      └─ 向下兼容的 bug 修复

1
[tool.semantic_release]
2
version_variables = ["src/my_package/__init__.py:__version__"]
3
version_toml = "pyproject.toml:project.version"
4
build_command = "uv build"
5
dist_glob = "dist/*"
6
branch = "main"
7
upload_to_pypi = true