Python 库与 API 设计：从包结构到向后兼容

# src/my_library/__init__.py —— 只导出公开 API
from .client import Client
from .models import User, Config

__all__ = ["Client", "User", "Config"]
__version__ = "1.2.0"

# ✅ 动词 + 宾语、返回语义一致
client.get_user(id)
client.create_user(user)
client.delete_user(id)

# ❌ 同一库风格混乱
fetchUser(id)          # camelCase
user = getUser(id)     # 另一个

def fetch_data(
    url: str,
    *,
    timeout: float = 30.0,       # 关键字-only，防误传
    retries: int = 3,
    headers: dict | None = None, # None 表示「用默认」
) -> Response:
    ...

# ✅ 查询不改变状态，纯函数
def get_status(client) -> Status: ...

# ✅ 明确的就地修改要命名清楚
def sort_inplace(items) -> None: ...

# ❌ 隐含副作用
def process(data): ...  # 到底改没改 data？

from typing import TypeVar, Protocol, Generic

T = TypeVar("T")

class Repository(Protocol[T]):
    def get(self, id: int) -> T: ...
    def save(self, obj: T) -> None: ...

class UserRepo(Repository[User]):
    def get(self, id: int) -> User: ...
    def save(self, obj: User) -> None: ...

from typing import overload

@overload
def load(path: str) -> str: ...
@overload
def load(path: str, binary: bool) -> bytes: ...

def load(path: str, binary: bool = False) -> str | bytes:
    mode = "rb" if binary else "r"
    with open(path, mode) as f:
        return f.read()

import warnings

def old_api():
    warnings.warn(
        "old_api 已弃用，请使用 new_api",
        DeprecationWarning,
        stacklevel=2,
    )
    return new_api()

def connect(host: str, port: int, *, password=None):
    # 老签名 password 是位置参数，新版本改为关键字
    ...

# 默认值一旦发布就是契约
def timeout_parse(text: str, default: float = 30.0) -> float:
    ...

# ❌ 不要后续悄悄改默认值（用户可能依赖）

from dataclasses import dataclass

@dataclass(frozen=True)     # 冻结：用户不能乱改，契约稳定
class Config:
    api_key: str
    timeout: float = 30.0

def create_user(client, name, *, age=None):
    """创建用户。

    Args:
        client: 已认证的客户端实例。
        name: 用户名。
        age: 可选年龄。

    Returns:
        User 对象。

    Raises:
        APIError: 服务端返回错误。
    """

# 安装
pip install mkdocs-material mkdocstrings

# mkdocs.yml
site_name: My Library
plugins:
  - mkdocstrings:
      handlers:
        python:
          options: { show_source: false }

theme:
  name: material
  features: [navigation.tabs]

class MyLibraryError(Exception):
    """库内所有异常基类"""

class ConfigError(MyLibraryError): ...
class ConnectionError(MyLibraryError): ...
class TimeoutError(MyLibraryError): ...
class ValidationError(MyLibraryError):
    def __init__(self, errors: list[str]):
        self.errors = errors
        super().__init__(f"校验失败: {errors}")

# ✅ 错误信息可行动
raise ConfigError("配置缺少 api_key，请在 config.toml 中设置")

# ❌ 无信息
raise Exception("failed")

# 发布前
python -m pytest && ruff check && mypy .
python -m build && twine check dist/*

# 发布
twine upload dist/*

# 版本号（semantic-release 或 bumpver）
bumpver update --patch

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

[project]
name = "my-library"
version = "1.2.0"
description = "A great library"
readme = "README.md"
requires-python = ">=3.9"
license = { text = "MIT" }
dependencies = ["httpx>=0.27"]

[project.optional-dependencies]
dev = ["pytest", "ruff", "mypy", "mkdocs-material"]