Python GitHub项目结构约定及对应PEP规范相关咨询

目前没有PEP对Python项目的完整目录结构做强制性规定，但Python打包工作组（PyPA）推出的社区最佳实践已经被绝大多数开源项目采纳，通用性很高。

1. 必备文件及推荐可选文件 #

除了你已知的README.md、LICENSE、.gitignore这类通用项目文件外，Python专属的文件规范如下：

必备文件（现代Python项目通用要求） #

• 与项目同名的核心模块目录：所有可导入的业务代码必须放在该目录下，禁止直接将业务.py文件散放在项目根目录
• pyproject.toml：PEP 621明确规定的现代Python项目核心配置文件，用来统一管理项目依赖、打包规则、各类开发工具（代码检查、测试工具等）的配置，已经逐步替代旧版的setup.py、setup.cfg

推荐可选文件 #

根据项目类型、开发流程的不同，可以按需添加：

• 依赖管理类：
  • requirements.txt：适合不需要发布到PyPI的内部项目，用来固定生产环境依赖版本，可通过pip freeze > requirements.txt快速生成
  • requirements-dev.txt：单独存放开发环境依赖，比如单元测试框架、代码格式化工具等，和生产环境依赖做隔离
  • setup.py/setup.cfg：旧版Python项目的打包配置文件，目前存量老项目仍在使用，新项目优先用pyproject.toml替代
• 开发流程类：
  • Makefile：封装常用的开发命令，比如依赖安装、测试执行、打包、部署命令，减少重复输入长指令的成本
  • CI配置文件：比如.travis.yml、.github/workflows/*.yml等，对应不同的CI/CD平台，用来自动化执行测试、打包、发布流程
  • 工具配置文件：比如ruff.toml（代码检查）、pyrightconfig.json（类型检查）、pytest.ini（测试框架配置）、conftest.py（pytest全局配置）等
• 目录类：
  • tests/：存放单元测试、集成测试代码，正规开源项目几乎都会配置，强烈推荐添加
  • docs/：存放项目官方文档，包括使用说明、开发规范、API文档等
  • scripts/：存放一次性的脚本文件，比如数据迁移、统计脚本等，不需要作为核心模块被导入

2. 业务目录的排布规则 #

data、app这类业务属性的目录没有强制的统一命名约定，你可以根据业务需求自行命名、组织，但需要遵守以下通用原则：

• 如果是业务逻辑的组成部分，需要作为Python模块被导入的app、utils、common等目录，必须放在和项目同名的核心模块目录下，不能直接放在项目根目录，否则会出现打包时遗漏、跨环境导入失败的问题
• 如果是不会被作为Python模块导入的静态资源、数据集、模板文件等，可以放在根目录下的data/、static/等目录，注意要在.gitignore中过滤不需要提交的大文件、敏感配置文件
• 所有Python模块的命名需要符合Python标识符规范，采用全小写、下划线分隔的格式，不要使用大写字母、空格、特殊字符，避免导入异常

内容的提问来源于stack exchange，提问作者123