Python项目结构规范 - pyproject.toml配置与目录组织完整指南

my_project/
├── src/                          # 源代码目录
│   └── my_package/               # 主包目录
│       ├── __init__.py           # 包初始化文件
│       ├── core/                 # 核心业务逻辑
│       │   └── __init__.py
│       ├── utils/                # 工具函数
│       │   └── __init__.py
│       └── cli.py                # 命令行入口
├── tests/                        # 测试代码
│   ├── __init__.py
│   ├── test_core.py
│   └── test_utils.py
├── docs/                         # 文档目录
│   └── README.md
├── examples/                     # 示例代码
│   └── example_usage.py
├── pyproject.toml                # 项目配置文件
├── README.md                     # 项目说明
├── LICENSE                       # 许可证
└── .gitignore                    # Git忽略文件

# 1. 空文件 - 仅作为包的标识
# src/my_package/__init__.py（可以是空文件）

# 2. 导出公共API - 控制from package import *的行为
# src/my_package/__init__.py
from .core.engine import Engine
from .utils.helpers import format_output

__all__ = ["Engine", "format_output"]

# 3. 包级别的初始化代码
# src/my_package/__init__.py
import logging

logger = logging.getLogger(__name__)
logger.info("my_package已加载")

from .core.engine import Engine
from .utils.helpers import format_output

__version__ = "1.0.0"
__all__ = ["Engine", "format_output", "logger"]

# ❌ 错误做法：避免使用绝对路径导入
import sys
sys.path.append('/path/to/project')
from my_package.core import Engine

# ✅ 正确做法：使用相对导入
from .core.engine import Engine
from ..utils import helpers

# ✅ 包外部导入（安装后）
from my_package import Engine, format_output
from my_package.core.engine import Engine

# pyproject.toml 完整示例

[build-system]
requires = ["setuptools>=61.0", "wheel"]
build-backend = "setuptools.backends._legacy:_Backend"

[project]
name = "my-package"
version = "1.0.0"
description = "一个示例Python项目"
readme = "README.md"
license = {text = "MIT"}
authors = [
    {name = "Your Name", email = "your@email.com"}
]
classifiers = [
    "Development Status :: 4 - Beta",
    "Programming Language :: Python :: 3",
    "Programming Language :: Python :: 3.9",
    "Programming Language :: Python :: 3.10",
    "Programming Language :: Python :: 3.11",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]
keywords = ["example", "tutorial", "python"]
requires-python = ">=3.9"
dependencies = [
    "requests>=2.28.0",
    "click>=8.0.0",
    "pydantic>=2.0.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=7.0.0",
    "pytest-cov>=4.0.0",
    "black>=23.0.0",
    "mypy>=1.0.0",
    "ruff>=0.1.0",
]
docs = [
    "sphinx>=6.0.0",
    "sphinx-rtd-theme>=1.2.0",
]

[project.scripts]
my-cli = "my_package.cli:main"

[project.urls]
Homepage = "https://github.com/yourname/my-package"
Documentation = "https://my-package.readthedocs.io"
Repository = "https://github.com/yourname/my-package"
Issues = "https://github.com/yourname/my-package/issues"

[tool.setuptools.packages.find]
where = ["src"]

[tool.black]
line-length = 88
target-version = ["py39", "py310", "py311"]

[tool.ruff]
line-length = 88
target-version = "py39"
select = ["E", "F", "W", "I", "N", "UP", "B", "SIM"]

[tool.mypy]
python_version = "3.9"
warn_return_any = true
warn_unused_configs = true
disallow_untyped_defs = true

[tool.pytest.ini_options]
testpaths = ["tests"]
python_files = ["test_*.py"]
addopts = "-v --cov=my_package"

# src/data_processor/__init__.py
"""Data Processor - 一个数据处理工具包"""

__version__ = "1.0.0"

from .core.processor import DataProcessor
from .utils.validators import validate_input
from .utils.formatters import format_output

__all__ = [
    "DataProcessor",
    "validate_input",
    "format_output",
]

# src/data_processor/core/__init__.py
"""核心处理模块"""

from .processor import DataProcessor
from .pipeline import ProcessingPipeline

__all__ = ["DataProcessor", "ProcessingPipeline"]

# src/data_processor/core/processor.py
"""数据处理器核心实现"""

from typing import Any, Dict, List, Optional
import logging

logger = logging.getLogger(__name__)


class DataProcessor:
    """数据处理器的主要类
    
    Attributes:
        config: 处理器的配置字典
        data: 存储处理后的数据
    """
    
    def __init__(self, config: Optional[Dict[str, Any]] = None):
        """初始化数据处理器
        
        Args:
            config: 配置字典，包含处理参数
        """
        self.config = config or {}
        self.data: List[Dict[str, Any]] = []
        logger.info("DataProcessor已初始化，配置: %s", self.config)
    
    def load_data(self, source: str) -> List[Dict[str, Any]]:
        """从指定源加载数据
        
        Args:
            source: 数据源路径或URL
            
        Returns:
            加载的数据列表
            
        Raises:
            FileNotFoundError: 当数据源不存在时
        """
        logger.info("正在从 %s 加载数据", source)
        # 实际的数据加载逻辑
        self.data = [{"id": 1, "value": "sample"}]
        return self.data
    
    def process(self) -> List[Dict[str, Any]]:
        """处理已加载的数据
        
        Returns:
            处理后的数据列表
        """
        logger.info("开始处理 %d 条数据", len(self.data))
        # 实际的数据处理逻辑
        processed = [{**item, "processed": True} for item in self.data]
        self.data = processed
        return processed

# src/data_processor/utils/validators.py
"""数据验证工具函数"""

from typing import Any, Dict, List
import re


def validate_input(data: Dict[str, Any], schema: Dict[str, Any]) -> bool:
    """验证输入数据是否符合schema
    
    Args:
        data: 待验证的数据
        schema: 验证schema
        
    Returns:
        验证是否通过
    """
    for key, expected_type in schema.items():
        if key not in data:
            return False
        if not isinstance(data[key], expected_type):
            return False
    return True


def validate_email(email: str) -> bool:
    """验证邮箱格式
    
    Args:
        email: 待验证的邮箱地址
        
    Returns:
        邮箱格式是否有效
    """
    pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
    return bool(re.match(pattern, email))

# 安装项目（开发模式）
pip install -e ".[dev]"

# 运行测试
pytest

# 运行代码格式化
black src/ tests/

# 运行类型检查
mypy src/

# 构建发布包
python -m build