理解 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 中写：
pythonfrom .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 运行
假设你待测试的工具函数文件为：
python# math_utils.py def add(a, b): return a + b def divide(a, b): if b == 0: raise ValueError("Cannot divide by zero") return a / b那么测试目录test下可以建立测试文件如下：
python# tests/test_math_utils.py import unittest from math_utils import add, divide class 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_ 开头的测试方法（单元测试用例）。 #运行完成后，输出测试结果（比如通过多少用例、失败多少、耗时多久等）。运行命令：
bashpython -m unittest tests/test_math_utils.py # 或自动发现所有 test_*.py 文件 python -m unittest discover✅ 方法二：使用 pytest（推荐，更简洁）
python# tests/test_math_utils.py from math_utils import add, divide def test_add(): assert add(2, 3) == 5 assert add(-1, 1) == 0 def test_divide(): assert divide(6, 2) == 3 with pytest.raises(ValueError): divide(1, 0)运行命令：
bashpytest # 自动发现 tests/ 目录下的测试 pytest -v # 显示详细信息
3. requirements.txt
- 列出项目依赖的第三方库，例如：
python
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 安装。
python
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="your@email.com",
# 简短描述
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 文件。
python
pip install build
python -m build5. 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 文件：
python# .env DATABASE_URL=postgresql://localhost/mydb_dev API_KEY=secret123 DEBUG=True在config.py代码中加载：
python# config.py pip install python-dotenv from dotenv import load_dotenv import os load_dotenv() # 自动加载 .env 文件 DATABASE_URL = os.getenv("DATABASE_URL") API_KEY = os.getenv("API_KEY") DEBUG = os.getenv("DEBUG", "False").lower() == "true"在业务代码中使用：
pythonfrom config import DATABASE_URL print(DATABASE_URL)✅ 方法二：使用 config目录
假设你的配置如下：
pythonconfig/ ├── __init__.py ├── default.py # 默认配置 ├── development.py # 开发环境 ├── testing.py # 测试环境 └── production.py # 生产环境其中development.py如下
python# config/development.py SECRET_KEY = "fallback-secret" DATABASE_URL = "sqlite:///default.db"那么在启动环境时进行配置：
pythonimport os from config import default #获取环境变量ENV的值，如果该环境变量未设置，则使用默认值"development" env = os.getenv("ENV", "development") if env == "production": config = production else: config = development