一、项目结构与命名
my_utils/
├── src/
│ └── my_utils/ # 真正的包目录（Python 3.3+ 可省略 __init__.py，但建议保留）
│ ├── __init__.py
│ └── calculator.py
├── tests/
│ └── test_calculator.py
├── pyproject.toml # 构建配置（推荐）
├── README.md
├── LICENSE
└── setup.cfg # 可选（若使用 setuptools）
- 将代码放在 src/ 下有助于避免开发期“同名导入”问题。
- 使用 PEP 8 风格命名：模块/函数/变量用小写下划线，类用 PascalCase。
- 为包准备 LICENSE（如 MIT、Apache-2.0），并写好 README.md 与基础示例。
- 说明：模块本质是 .py 文件，包是包含 init.py 的目录；模块搜索路径由解释器按顺序查找（内置→site-packages 等）
二、编写代码与本地开发安装
示例实现（src/my_utils/calculator.py）：
def add(a: float, b: float) -> float:
"""Return the sum of a and b."""
return a + b
def multiply(a: float, b: float) -> float:
"""Return the product of a and b."""
return a * b
在 src/my_utils/init.py 中导出公共 API（便于用户直接 from my_utils import add）：
from .calculator import add, multiply
__version__ = "0.1.0"
本地开发安装（可编辑模式，修改代码即时生效）：
# 建议使用虚拟环境
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate
pip install -e .
说明：将模块放入 site-packages 或通过 PYTHONPATH 指定搜索路径均可实现导入；开发阶段优先用可编辑安装，避免频繁重装。
三、打包与构建配置
使用现代构建工具 Pyproject.toml（推荐 setuptools）：
[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.build_meta"
[project]
name = "my_utils"
version = "0.1.0"
description = "A tiny example utility package"
authors = [{name = "Your Name", email = "you@example.com"}]
license = {text = "MIT"}
readmes = ["README.md"]
license-files = ["LICENSE"]
dependencies = []
classifiers = [
"Programming Language :: Python :: 3",
"License :: OSI Approved :: MIT License",
"Operating System :: OS Independent",
]
requires-python = ">=3.8"
可选：补充 setup.cfg（若不用 pyproject.toml 也可用 setup.py，但 pyproject.toml 更现代）：
[metadata]
license_file = LICENSE
[aliases]
test = pytest
[tool:pytest.ini_options]
testpaths = tests
构建分发包（生成 .tar.gz 与 .whl）：
pip install build
python -m build
# 产物位于：dist/my_utils-0.1.0.tar.gz 与 dist/my_utils-0.1.0-py3-none-any.whl
四、测试、发布与安装使用
本地/CI 测试与质量检查（示例）：
pip install pytest pytest-cov
pytest tests/ -v
在代码中导入使用：
from my_utils import add, multiply
print(add(2, 3)) # 5
print(multiply(2, 3)) # 6
