工欲善其事必先利其器 - 分享一个Python项目开发的工程模板和工具列表

最近开始使用Python作为项目的开发工具，项目涵盖了GUI, Web, Agent，经典的机器学习和深度学习。开发的过程中总结了一套很好用的工具列表，项目模板，高性能部署模板，特地记录并分享给大家。

开发工具和工程模板

我们先看一下工具列表：

• uv
  : 项目管理工具：依赖管理，虚拟环境管理，项目打包，测试，是必备的工具，非常好用。
• VS Code
  : 代码编辑器，集成IDE， 需要安装一些扩展，推荐在用的扩展列表：
• 微软推出的Python 扩展，这就不多介绍了，毕竟Python的发明家，大神Guido van Rossum 被微软收编，想不好都不行。
• Even Better TOML', 高亮
  pyproject.toml`的，很好用。
• 微软推出的Pylance, 官方语言服务器：补全/跳转/类型提示
• 微软推出的官方调试器Python Debugger
• Ruff
  , uv(Astral)官方推出的扩展。
• 微软官方推出的jupyter扩展，真好用啊！，尤其是数据项目，机器学习项目
• 微软官方推出的Dev Containers, 如果你的项目要基于k8s这种容器化的开发，这个必备了。
• 微软官方推出的远程开发Remote - SSH
• 微软官方推出的WSL, 这个就不限于是python了，基于WSL开发，这个真的是好用，好用！好用！好用！重要的事情说三遍。

对于Python项目，以上工具就足够了。

然后来看下工程模板以及基础的项目流程

新建项目和工程模板

使用uv管理项目，基本上都是通过uv的命令行来管理。

uv init my-project # 创建你的项目cd my-project# 创建额外必要的目录mkdir .vscodemkdir srcmkdir src/my-projectmkdir tests

这里有一个需要注意的地方：在创建项目的时候，如果你的项目有Python版本要求，那么在初始化项目的时候，使用：

   uv init --python 3.13.3 my-project # 指定`Python`版本

如果你是需要将项目发布成为一个whl包，那么使用：

   uv init --package --python 3.13.3 my-project

创建完成之后，项目目录基本结构如下：

my-project/├─ pyproject.toml├─ uv.lock├─ README.md├─ .gitignore├─ .python-version│├─ src/│  └─ my_project/│     ├─ __init__.py│     ├─ main.py│     └─ service.py│├─ tests/│  ├─ __init__.py│  └─ test_service.py│└─ .vscode/   ├─ settings.json   ├─ tasks.json   └─ launch.json

目录准备好了之后，再添加必要的开发工具:

uv add --dev pytest pytest-cov ruff mypy debugpy

至于这些包的作用，大家自己搜搜吧。

我们需要配置 VS code + uv来运行和调试项目。

编辑文件pyproject.toml, 在文件的末尾添加如下的内容：

# ----------------------# Ruff：Lint + Format# ----------------------[tool.ruff]line-length=88target-version="py311"exclude=[".venv","build","dist"][tool.ruff.lint]select=["E",# pycodestyle"F",# pyflakes"I",# isort"B",# flake8-bugbear"UP",# pyupgrade]# ----------------------# Pytest# ----------------------[tool.pytest.ini_options]minversion="7.0"testpaths=["tests"]pythonpath=["src"]addopts=["-ra","--strict-markers",]# ----------------------# Mypy# ----------------------[tool.mypy]python_version="3.11"warn_return_any=truewarn_unused_ignores=truewarn_unreachable=truewarn_redundant_casts=truedisallow_untyped_defs=falseignore_missing_imports=truefiles=["src"]# ----------------------# Coverage# ----------------------[tool.coverage.run]branch=truesource=["src"][tool.coverage.report]show_missing=trueskip_covered=true

编辑文件 .vscode/settings.json:

{"python.defaultInterpreterPath":".venv/Scripts/python.exe","python.testing.pytestEnabled":true,"python.testing.pytestArgs":["tests"],"[python]":{"editor.defaultFormatter":"charliermarsh.ruff","editor.formatOnSave":true,"editor.codeActionsOnSave":{"source.fixAll.ruff":"always","source.organizeImports.ruff":"always"}},"cSpell.words":["addopts","debugpy","isort","minversion","mypy","pycodestyle","pyflakes","pytest","pythonpath","pyupgrade","testpaths","venv"]}

编辑文件.vscode/tasts.json

{"version":"2.0.0","tasks":[{"label":"uv: run main","type":"shell","command":"uv","args":["run","python","-m","my_project"],"options":{"cwd":"${workspaceFolder}"},"group":{"kind":"build","isDefault":true}}]}

这是项目运行的标准入口， 如果你的项目是以根目录下的main.py为主要入口，可以使用如下的配置：

{"version":"2.0.0","tasks":[{"label":"uv: run app","type":"shell","command":"uv","args":["run","python","main.py"],"options":{"cwd":"${workspaceFolder}"},"group":{"kind":"build","isDefault":true}}]}

编辑文件： .vscode/launch.json, 这个文件是调试入口了

{"version":"0.2.0","configurations":[{"name":"Debug my_project (venv)","type":"debugpy","request":"launch","module":"my_project","cwd":"${workspaceFolder}","env":{"PYTHONPATH":"${workspaceFolder}/src"},"justMyCode":true}]}

如果你的项目是以根目录下的main.py为主要入口，可以使用如下的配置：

{"version":"0.2.0","configurations":[{"name":"Debug main.py","type":"debugpy","request":"launch","program":"${workspaceFolder}/main.py","cwd":"${workspaceFolder}","justMyCode":true,"env":{"PYTHONPATH":"${workspaceFolder}/src"}}]}

有了以上的配置之后，就可以直接添加必要的开发依赖包，开始开发了。

添加依赖包使用uv， 例如：uv add agent-framework --prerelease allow

推荐的日常工作流如下：

代码编写过程中的参考流程：

写代码 ↓保存文件（VS Code） ↓ruff 自动修 I001 ↓ruff check（CI） ↓mypy ↓pytest

如果用手动跑ruff 的话，运行：

uv run ruff check --fix

如果只修复部分代码格式：

uv run ruff check --select I --fix

可以参考帮助--select 有哪些可以选择的值。

后面再看看Python项目的基于生产级的部署方式。

往期文章: