Python项目结构需立足模块导入、包初始化、路径解析和可安装性四支柱；__init__.py定义包边界并导出接口，-m运行确保相对导入正确，pyproject.toml声明依赖与入口，src/布局隔离代码与非代码文件。
Python项目结构不是随便建几个文件夹就行，关键在理解模块导入、包初始化、路径解析和可安装性这四根支柱。光会写代码不够，项目一打包就报错、本地能跑线上挂掉、别人拉下来根本不会用——这些问题全出在结构设计上。
包与模块的边界必须靠__init__.py来定义
它不只是历史遗留文件，而是Python识别“包”的唯一凭证。空文件也生效，但真正价值在于显式导出接口：
- 在
mylib/__init__.py里写from .core import process_data，外部就能直接import mylib; mylib.process_data() - 用
__all__ = ["process_data"]控制from mylib import *能导入什么，避免污染命名空间 - 别把业务逻辑塞进
__init__.py——它该轻量，只做声明和简单组装
导入路径问题本质是sys.path和当前工作目录的博弈
运行python main.py和python -m mypackage.main行为完全不同：
github-repo-analyzer
下载
当用户提及 GitHub URL，或要求分析、审查、探索或理解任意 GitHub 项目、仓库或代码库时，请使用此技能。触发条件包括以下短语：“分析这个项目”、“看看这个仓库”、“analyze this repo”、“what does this project do”，或消息中包含任何 github.com URL。
- 前者以
main.py所在目录为起点，相对导入容易失败 - 后者以项目根目录为起点，
from .utils import helper才能正确解析 - 调试时加
print(sys.path)看路径顺序，临时加路径用sys.path.insert(0, "/abs/path/to/src")，但上线前必须改成可安装模式
让项目真正“可安装”，绕不开pyproject.toml
告别setup.py，用现代标准声明依赖和入口：
立即学习“Python免费学习笔记（深入）”；
-
[build-system]指定构建器（如setuptools或hatchling） -
[project]写明name、version、dependencies和requires-python -
[project.entry-points."console_scripts"]注册命令行工具，比如mytool = "mylib.cli:main" - 装本地包：执行
pip install -e .（开发模式），所有导入立即生效，改完代码不用重装
典型稳健结构长这样，不是教条而是经过压测的惯用法
以中等规模工具类项目为例：
-
src/——源码根目录（隔离测试/配置等非代码文件） -
src/mytool/——实际包，含__init__.py、cli.py、core/子包 -
tests/——与src/平级，用pytest自动发现 -
pyproject.toml——在项目最外层，管理整个生命周期 - 不放
__pycache__、.env、venv/到Git，靠.gitignore守住底线
