pypro

Python 多功能练习项目，包含命令行 / Streamlit 待办事项系统与 PDF 智能问答后端（FastAPI + PyMuPDF）。另有简单的 Flask 演示应用 demo.py。

功能列表

待办事项系统

• 添加、查看、删除任务
• 标记任务完成 / 撤销（Streamlit）
• 数据持久化至本地 todos.json
• 命令行交互模式与子命令（add / list / delete）

PDF 智能问答后端（进行中）

• PDF 上传与逐页文本解析（/api/pdf/parse）
• 健康检查（/health）
• 规划中的 RAG 能力：Chunk 切分、Embedding、检索、问答（见 specs/）

演示应用

• demo.py：最小 Flask 示例，根路径返回 Hello Cursor

目录结构

pypro/
├── app.py                 # Streamlit 待办 Web 界面
├── todo.py                # 待办 CLI 入口
├── todo_core.py           # 待办核心业务逻辑
├── demo.py                # Flask 演示应用
├── todos.json             # 待办数据（运行时生成/更新）
├── requirements.txt       # Python 依赖
├── backend/               # FastAPI PDF 后端
│   ├── main.py            # 应用入口
│   ├── api/pdf.py         # PDF 解析路由
│   ├── models/pdf.py      # Pydantic 响应模型
│   └── services/pdf_parser.py  # PyMuPDF 解析服务
├── specs/                 # 产品与设计文档
│   ├── PRD.md
│   ├── DESIGN.md
│   └── TASKS.md
└── tests/                 # pytest 测试
    ├── test_todo_core.py
    ├── test_api_pdf.py
    ├── test_pdf_parser.py
    └── test_demo.py

环境要求

• Python 3.11+（推荐 3.12）
• pip + venv

安装依赖

# 创建并激活虚拟环境（推荐）
python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux / macOS
source .venv/bin/activate

# 安装依赖
pip install -r requirements.txt

启动方式

待办 CLI

# 交互式菜单
python todo.py

# 子命令
python todo.py add "准备季度汇报"
python todo.py list
python todo.py delete 1

# 指定数据文件
python todo.py --file ./my_todos.json list

Streamlit Web 界面

streamlit run app.py

浏览器默认访问 http://localhost:8501。

FastAPI PDF 后端

# 开发模式（项目根目录执行，确保可 import backend）
uvicorn backend.main:app --reload --host 0.0.0.0 --port 8000

• 健康检查：GET http://localhost:8000/health
• 交互式文档：http://localhost:8000/docs

Flask 演示应用

python demo.py

默认访问 http://127.0.0.1:5000/。

API 说明

GET /health

健康检查。

响应示例：

{"status": "ok"}

POST /api/pdf/parse

上传 PDF 并返回逐页文本与元数据。

请求： multipart/form-data，字段名 file，仅支持 .pdf，最大 20 MB。

成功响应（200）：

{
  "filename": "sample.pdf",
  "page_count": 1,
  "total_chars": 123,
  "metadata": {
    "title": null,
    "author": null
  },
  "pages": [
    {
      "page_number": 1,
      "text": "页面文本内容",
      "char_count": 123
    }
  ]
}

错误响应：

状态码	场景
400	空文件、非 PDF、扩展名错误、文件过大

运行测试

python -m pytest tests/ -v

测试覆盖：

• todo_core：增删查、切换状态、持久化、边界情况
• backend/services/pdf_parser：PDF 解析服务
• backend/main + api/pdf：FastAPI 端点
• demo.py：Flask 根路由（需安装 flask）

相关文档

• specs/PRD.md — 产品需求
• specs/DESIGN.md — 技术选型
• specs/TASKS.md — 开发任务清单