标准 Python 项目结构

理解 Python 项目的通用结构对于初学者来说非常重要。虽然每个项目可能略有不同，但大多数规范、可维护的 Python 项目都遵循一些常见的组织模式。

常见的项目结构如下：

my_project/                     # 项目根目录
├── my_package/                 # 主要 Python 包（模块集合）
│   ├── __init__.py             # 标识这是一个 Python 包
│   ├── core.py                 # 核心逻辑
│   ├── utils.py                # 工具函数
│   └── ...                     # 其他模块
├── tests/                      # 单元测试目录
│   ├── __init__.py
│   ├── test_core.py
│   └── test_utils.py
├── docs/                       # 文档（可选）
├── examples/                   # 使用示例（可选）
├── requirements.txt            # 依赖列表
├── setup.py 或 pyproject.toml  # 项目打包配置（二选一）
├── README.md                   # 项目说明
├── .gitignore                  # Git 忽略文件
└── .env 或 config/             # 配置文件（如数据库连接、API 密钥等）

各部分详解：

1. my_package/ —— 主代码包

• 这是你实际编写业务逻辑的地方。
• 文件名应使用小写+下划线（如 data_loader.py）。
• __init__.py 可以为空，也可以用来控制 from my_package import * 时导出哪些内容。

小知识：

在Python 中，一个目录如果包含 __init__.py 文件（哪怕为空），就被视为一个包package。

当你写 from my_package import * 时，Python 默认会导入该包中所有“公开”的名字（即不以下划线开头的变量、函数、类等）。

我们可以通过在 __init__.py 中定义一个特殊变量 __all__ 来显式指定哪些内容可以被 import * 导入。例如：

core.py 中有函数：process_data()
utils.py 中有函数：log_info() 和 internal_helper()
你想让 from my_package import * 只导入 process_data 和 log_info，那么就在my_package/__init__.py 中写：

from .core import process_data
from .utils import log_info# 显式声明哪些名字可以被 import *
__all__ = ["process_data", "log_info"]

注意：__all__ 只影响 import * 的行为，不影响 from my_package import process_data 这种明确导入方式。

2. tests/ —— 测试目录

• 使用 pytest 或 unittest 编写测试。
• 测试文件通常以 test_ 开头，便于自动发现。
• 建议与源代码分离（不放在包内），避免打包时包含测试代码。

✅ 方法一：使用 unittest（Python 自带）
步骤：

• 创建测试文件（如 test_math_utils.py）
• 继承 unittest.TestCase
• 写以 test_ 开头的方法
• 用 python -m unittest 运行

假设你待测试的工具函数文件为：

# math_utils.py
def add(a, b):return a + bdef divide(a, b):if b == 0:raise ValueError("Cannot divide by zero")return a / b

那么测试目录test下可以建立测试文件如下：

# tests/test_math_utils.py
import unittest
from math_utils import add, divideclass TestMathUtils(unittest.TestCase):def test_add(self):self.assertEqual(add(2, 3), 5)self.assertEqual(add(-1, 1), 0)def test_divide(self):self.assertEqual(divide(6, 2), 3)with self.assertRaises(ValueError):divide(1, 0)if __name__ == '__main__':unittest.main()
#unittest.main()这是 Python 内置的 unittest 测试框架提供的方法，作用是：
#自动发现当前模块中所有继承自 unittest.TestCase 的测试类。
#自动执行这些测试类中以 test_ 开头的测试方法（单元测试用例）。
#运行完成后，输出测试结果（比如通过多少用例、失败多少、耗时多久等）。

运行命令：

python -m unittest tests/test_math_utils.py
# 或自动发现所有 test_*.py 文件
python -m unittest discover

✅ 方法二：使用 pytest（推荐，更简洁）

# tests/test_math_utils.py
from math_utils import add, dividedef test_add():assert add(2, 3) == 5assert add(-1, 1) == 0def test_divide():assert divide(6, 2) == 3with pytest.raises(ValueError):divide(1, 0)

运行命令：

pytest          # 自动发现 tests/ 目录下的测试
pytest -v       # 显示详细信息

3. requirements.txt

• 列出项目依赖的第三方库，例如：

requests==2.31.0
numpy>=1.20.0

• 安装命令：pip install -r requirements.txt

4. setup.py 或 pyproject.toml

• 现代推荐：使用 pyproject.toml（PEP 621 标准）来定义项目元数据和构建方式。
• 旧项目常用 setup.py，但现在逐渐被取代。
• 有了这个文件，你的项目就可以通过 pip install -e . 安装为“可编辑模式”，方便开发。

setup.py 是 Python 项目中用于打包、分发和安装项目的脚本，主要基于 Python 标准库 setuptools 或 distutils 编写。它的作用是定义项目的元信息（如名称、版本、作者）、依赖项、入口脚本等，使得项目可以被打包成可分发的安装包（如 .tar.gz 或 .whl），并支持通过 pip install 安装。

from setuptools import setup, find_packages# 读取项目描述（通常从 README.md 读取，增强 PyPI 页面展示）
with open("README.md", "r", encoding="utf-8") as f:long_description = f.read()# 从 requirements.txt 读取依赖（可选）
def read_requirements():with open("requirements.txt", "r", encoding="utf-8") as req:return [line.strip() for line in req if line.strip() and not line.startswith("#")]setup(# 项目名称（PyPI 上的唯一标识）name="myproject",# 版本号（遵循语义化版本：主版本.次版本.修订号）version="0.1.0",# 作者信息author="Your Name",author_email="[e-mail]",# 简短描述description="A sample Python project",# 详细描述（通常用于 PyPI 页面，支持 Markdown）long_description=long_description,long_description_content_type="text/markdown",# 项目主页url="https://github.com/yourusername/myproject",# 自动发现项目中的包（排除测试目录等）packages=find_packages(exclude=["tests*"]),# 项目支持的 Python 版本python_requires=">=3.8",# 依赖包（安装时会自动从 PyPI 下载）#install_requires=[#    "requests>=2.25.0",#    "pandas>=1.0.0",#],install_requires=read_requirements() #依赖列表# 可选：开发环境依赖（通过 pip install -e .[dev] 安装）extras_require={"dev": ["pytest>=7.0","flake8>=3.9.0",]},# 可选：定义可执行命令（安装后可在终端直接运行）entry_points={"console_scripts": ["mycommand = myproject.cli:main",  # 命令名 = 模块.函数]},# 分类信息（用于 PyPI 分类展示）classifiers=["Programming Language :: Python :: 3","License :: OSI Approved :: MIT License","Operating System :: OS Independent",],
)

然后构建分发包，就能生成 .tar.gz 和 .whl 文件。

pip install build
python -m build

5. README.md

• 项目简介、安装步骤、使用示例、贡献指南等。
• GitHub/GitLab 等平台会自动渲染它作为首页。

6. .gitignore

• 指定哪些文件不应提交到版本控制（如 __pycache__/, .env, *.log 等）。因为有些文件：

- 是临时生成的（如 __pycache__/）

- 包含敏感信息（如 .env）

- 是本地配置（如 IDE 配置文件）

- 体积很大（如数据集、模型文件）

💡 你可以从 github/gitignore 获取官方 Python .gitignore 模板。

7. 配置管理

• 敏感信息（如密码、密钥）不要硬编码在代码中。
• 推荐使用 .env 文件或单独的 config/ 目录管理不同环境（dev/test/prod）的配置。

✅方式一：使用 .env 文件 + python-dotenv
创建 .env 文件：

# .env
DATABASE_URL=postgresql://localhost/mydb_dev
API_KEY=secret123
DEBUG=True

在config.py代码中加载：

# config.pypip install python-dotenv
from dotenv import load_dotenv
import osload_dotenv()  # 自动加载 .env 文件DATABASE_URL = os.getenv("DATABASE_URL")
API_KEY = os.getenv("API_KEY")
DEBUG = os.getenv("DEBUG", "False").lower() == "true"

在业务代码中使用：

from config import DATABASE_URL
print(DATABASE_URL)

✅ 方法二：使用 config目录

假设你的配置如下：

config/
├── __init__.py
├── default.py      # 默认配置
├── development.py  # 开发环境
├── testing.py      # 测试环境
└── production.py   # 生产环境

其中development.py如下

# config/development.py
SECRET_KEY = "fallback-secret"
DATABASE_URL = "sqlite:///default.db"

那么在启动环境时进行配置：

import os
from config import default#获取环境变量ENV的值，如果该环境变量未设置，则使用默认值"development"
env = os.getenv("ENV", "development")
if env == "production":config = production
else:config = development