标准 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 中写：
注意：__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 运行
假设你待测试的工具函数文件为：
那么测试目录test下可以建立测试文件如下：
运行命令：
✅ 方法二：使用 pytest（推荐，更简洁）
运行命令：
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="[email protected]", # 简短描述 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 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 文件：
在config.py代码中加载：
在业务代码中使用：
✅ 方法二：使用 config目录
假设你的配置如下：
其中development.py如下
那么在启动环境时进行配置：
