python-project

Python 项目技能

使用 uv 包管理器和 Flask 构建 Web 组件，进行现代 Python 项目开发。

快速开始

使用 uv 创建新项目

# Initialize new project
uv init my-project
cd my-project

# Add dependencies
uv add flask pytest ruff mypy

# Run application
uv run python app.py

# Run with Flask
uv run flask run --debug

包管理器：uv

使用 uv（astral-sh/uv）管理所有 Python 包。它可以替代 pip、poetry、pyenv 和 virtualenv。

常用命令

# Project management
uv init <name>              # Initialize project
uv add <package>            # Add dependency
uv remove <package>         # Remove dependency
uv sync                     # Sync dependencies from lockfile
uv lock                     # Generate lockfile

# Running
uv run <command>            # Run in project environment
uv run python script.py     # Run Python script
uv run pytest               # Run tests

# Tools (like pipx)
uvx <tool>                  # Run tool in ephemeral env
uv tool install <tool>      # Install tool globally

# Python versions
uv python install 3.12      # Install Python version
uv python pin 3.12          # Pin version for project

Web 框架：Flask

使用 Flask 构建 Web 应用——这是一款轻量级 WSGI 微框架。

最简 Flask 应用

# app.py
from flask import Flask, render_template, request, jsonify

app = Flask(__name__)

@app.route("/")
def index():
    return render_template("index.html")

@app.route("/api/data", methods=["GET", "POST"])
def api_data():
    if request.method == "POST":
        data = request.get_json()
        return jsonify({"status": "ok", "received": data})
    return jsonify({"message": "Hello, API!"})

if __name__ == "__main__":
    app.run(debug=True)

Flask 项目结构

my_flask_app/
├── app.py                  # Application entry
├── pyproject.toml          # uv project config
├── static/                 # CSS, JS, images
│   ├── css/
│   └── js/
├── templates/              # Jinja2 templates
│   ├── base.html
│   └── index.html
└── tests/
    └── test_app.py

运行 Flask

# Development
uv run flask run --debug

# With specific host/port
uv run flask run --host=0.0.0.0 --port=8080

项目配置

pyproject.toml

[project]
name = "my-project"
version = "0.1.0"
description = "Project description"
requires-python = ">=3.11"
dependencies = [
    "flask>=3.0",
]

[project.optional-dependencies]
dev = [
    "pytest>=8.0",
    "ruff>=0.5",
    "mypy>=1.10",
]

[tool.ruff]
line-length = 88
target-version = "py311"

[tool.ruff.lint]
select = ["E", "F", "I", "UP"]

[tool.mypy]
python_version = "3.11"
strict = true

[tool.pytest.ini_options]
testpaths = ["tests"]

代码质量

# Linting and formatting with ruff
uv run ruff check .          # Check for issues
uv run ruff check . --fix    # Auto-fix issues
uv run ruff format .         # Format code

# Type checking
uv run mypy .

# Testing
uv run pytest
uv run pytest -v --cov=src

脚本

• scripts/init-project.sh - 使用标准结构初始化新的 Python 项目
• scripts/setup-flask.sh - 设置 Flask 应用样板代码

参考资料

• 查看 references/uv-commands.md，了解完整的 uv 参考资料
• 查看 references/flask-patterns.md，了解 Flask 最佳实践