标准 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__ = ['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 运行

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

def add(a, b):
    return a + b

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

import unittest
from utils import add

class TestMathUtils(unittest.TestCase):
    def test_add(self):
        self.assertEqual(add(1, 2), 3)

运行命令：

python -m unittest discover

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

运行命令：

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 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 文件：

DATABASE_URL=postgres://user:pass@localhost/db
SECRET_KEY=my_secret_key

在 config.py 代码中加载：

from dotenv import load_dotenv
load_dotenv()

在业务代码中使用：

import os
db_url = os.getenv('DATABASE_URL')

✅ 方法二：使用 config 目录

假设你的配置如下：

class Config:
    DEBUG = False
    DATABASE_URL = 'sqlite:///app.db'

其中 development.py 如下：

from config import Config

class DevelopmentConfig(Config):
    DEBUG = True

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

export FLASK_ENV=development