diff --git a/.cursorrules_Python_Lib b/.cursorrules_Python_Lib new file mode 100644 index 0000000..c52c3d2 --- /dev/null +++ b/.cursorrules_Python_Lib @@ -0,0 +1,81 @@ +--- +description: Python 库项目开发最佳实践与规范 +--- + +# Python 库项目开发规范 + +## 依赖管理 + +- 使用`uv`管理依赖 + +## 项目结构 + +- 项目整体结构如下: + + ```markdown + $PROJECT_ROOT/ + ├── lib_name/ # 主应用目录 + │ ├── module1/ # 模块1 + │ │ ├── __init__.py + │ │ ├── schemas.py # 模型 + │ │ ├── utils.py # 工具函数 + ├── tests/ # 测试目录 + │ ├── test_module1.py + │ └── __init__.py + ├── docs/ # 文档目录 + │ ├── __init__.py + │ └── index.md # 主页 + └── examples/ # 示例目录 + ├── __init__.py + └── example1.py # 示例1 + ``` +- 采用模块化设计,每个模块位于`$PROJECT_ROOT/lib_name`目录下,其结构如下: + + ```markdown + module_name + ├── sub_module1 # 子模块1 + │ ├── __init__.py + │ ├── schemas.py # Pydantic模型 + │ └── utils.py # 工具函数 + ├── sub_module2 # 子模块2 + │ ├── __init__.py + │ ├── schemas.py # Pydantic模型 + │ └── utils.py # 工具函数 + ├── __init__.py + └── schemas.py # 模块公共模型 + ``` + +## 示例 + +- 在完成一个功能时,询问是否需要添加示例代码 +- 示例代码应位于`$PROJECT_ROOT/examples`目录下,结构如下: + + ```markdown + examples + ├── module_name # 模块名 + │ ├── __init__.py + │ ├── feature_name_example.py # 功能名示例 + │ └── ... + └── ... + ``` +- 示例和测试不是一个东西,示例代码不要用`test_`开头 +- 在`$PROJECT_ROOT/examples/README.md`文件中记录示例代码的运行方法,内容格式如下: + + ```markdown + ## $MODULE_NAME + ### $EXAMPLE_NAME + + ```powershell + $env:PYTHONPATH=$PROJECT_ROOT + uv run examples/module_name/feature_name_example.py + ``` + ```bash + export PYTHONPATH=$PROJECT_ROOT + uv run examples/module_name/feature_name_example.py + ``` + ``` + +## 自述文件 + +- 在`$PROJECT_ROOT/README.md`文件中记录项目的重要信息 +- 涉及重要变更时,更新`$PROJECT_ROOT/CHANGELOG.md`文件