# sdpy

**Repository Path**: clarkstore/sdpy

## Basic Information

- **Project Name**: sdpy
- **Description**: py项目目录结构生成
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-04
- **Last Updated**: 2026-04-13

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SDPY: Python项目目录结构生成器

🚀 **SDPY** (Standard Directory Project for Python) 是一个强大的Python项目结构生成器，能够快速创建标准化、现代化的Python项目结构。

## ✨ 主要特性

- 🏗️ **多种项目模板**: 支持FastAPI、FastMCP、CLI、Library、Web五种项目类型
- 📦 **uv依赖管理**: 自动配置现代化的uv包管理工具
- 🔧 **精简开发工具**: 预配置Black、Ruff、Pytest等核心代码质量工具
- 🐳 **Docker支持**: 自动生成Dockerfile和docker-compose.yml
- 📝 **完整文档**: 自动生成README、贡献指南、变更日志等文档
- ⚙️ **灵活配置**: 支持配置文件和命令行参数自定义
- 🎨 **美观界面**: 使用Rich库提供友好的命令行界面

## 🎯 支持的项目类型

| 类型          | 描述           | 主要依赖                     |
| ----------- | ------------ | ------------------------ |
| **fastapi** | 现代化Web API项目 | FastAPI, Uvicorn, Loguru |
| **fastmcp** | MCP服务器项目     | FastMCP, Loguru          |
| **cli**     | 命令行工具项目      | Click, Loguru            |

## 🚀 快速开始

### 安装

#### 方法1：从源码安装

```bash
# 克隆仓库
git clone https://gitee.com/clarkstore/sdpy.git
cd sdpy

# 安装uv（如果尚未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 安装依赖
uv sync

# 安装SDP-PY到系统
uv pip install -e .
```

#### 方法2：直接使用

```bash
# 下载并进入目录
git clone https://gitee.com/clarkstore/sdpy.git
cd sdp-py

# 使用uv直接运行
uv run python main.py --help
```

### 基本使用

#### 生成FastAPI项目

```bash
# 生成一个FastAPI项目
sdp generate my-api --type fastapi --author "Clark" --email "changhongyuan@126.com"

# 或使用简短形式
sdp generate my-api -t fastapi -a "Clark" -e "changhongyuan@126.com"
```

#### 生成FastMCP项目

```bash
# 生成一个FastMCP项目
sdp generate my-mcp --type fastmcp --description "A useful MCP server"
```

#### 生成CLI项目

```bash
# 生成一个CLI命令行工具项目
sdp generate my-cli --type cli --author "Clark" --email "changhongyuan@126.com"
```

#### 查看可用模板

```bash
# 列出所有可用的项目模板
sdp templates
```

#### 生成项目配置文件

```bash
# 生成配置文件模板
sdp init-config my-project --type fastapi --output project-config.yaml

# 编辑配置文件后使用
sdp generate my-project --config project-config.yaml
```

## 📁 生成的项目结构

### FastAPI项目结构示例

```
my-api/
├── app/                    # 源代码目录
│   ├── api/               # API路由模块
│   │   ├── __init__.py
│   │   └── router.py
│   ├── models/            # 数据模型
│   │   ├── __init__.py
│   │   └── base.py
├── config/                # 配置模块
│   ├── __init__.py
│   └── config.py          # 配置管理
├── utils/                 # 工具函数
│   ├── __init__.py
│   └── helpers.py
├── tests/                 # 测试目录
├── docs/                  # 文档目录
├── logs/                  # 日志目录
├── docker/                # Docker相关文件
│   ├── .dockerignore      # Docker忽略文件
│   ├── Dockerfile         # Docker镜像配置
│   └── docker-compose.yml # Docker Compose配置
├── main.py                # 主入口文件
├── pyproject.toml         # 项目配置和依赖
├── .gitignore             # Git忽略文件
├── .env.example           # 环境变量模板
├── README.md              # 项目说明文档
├── CHANGELOG.md           # 变更日志
├── CONTRIBUTING.md        # 贡献指南
└── LICENSE                # 许可证文件
```

## ⚙️ 高级配置

### 使用配置文件

创建一个YAML配置文件来自定义项目生成：

```yaml
# project-config.yaml
project_name: "my-project"
project_type: "fastapi"
description: "An awesome FastAPI project"
author: "Clark"
email: "changhongyuan@126.com"
version: "0.1.0"
license: "MIT"

# 功能选项
use_uv: true
init_git: true
use_docker: true

# 自定义依赖
dependencies:
  - "fastapi"
  - "uvicorn"
  - "loguru"
  - "sqlalchemy"  # 额外的数据库依赖

dev_dependencies:
  - "pytest"
  - "black"
  - "ruff"
```

然后使用配置文件生成项目：

```bash
sdp generate my-project --config project-config.yaml
```

### 命令行选项

```bash
# 查看所有选项
sdp generate --help

# 常用选项
sdp generate my-project \
  --type fastapi \
  --author "Clark" \
  --email "changhongyuan@126.com" \
  --description "Project description" \
  --target-dir ./projects \
  --no-git \
  --no-uv
```

## 🛠️ 开发指南

### 生成项目后的开发流程

1. **进入项目目录**
   ```bash
   cd my-project
   ```
2. **安装依赖**
   ```bash
   uv sync
   ```
3. **激活虚拟环境**（可选）
   ```bash
   source .venv/bin/activate  # Linux/macOS
   # 或
   .venv\Scripts\activate     # Windows
   ```
4. **运行项目**
   ```bash
   # FastAPI项目
   uv run uvicorn main:app --reload

   # CLI项目
   uv run python main.py --help

   # 其他项目
   uv run python main.py
   ```
5. **代码质量检查**
   ```bash
   # 代码格式化
   uv run black .

   # 代码检查
   uv run ruff check .
   ```
6. **运行测试**
   ```bash
   # 运行所有测试
   uv run pytest
   ```

### Docker部署

生成的项目包含完整的Docker配置：

```bash
# 构建镜像
docker build -t my-project .

# 运行容器
docker run -p 8000:8000 my-project

# 使用docker-compose
docker-compose up -d
```

## 📚 API参考

### Python API

SDP-PY也提供了Python API供程序化使用：

```python
from core import ProjectGenerator, ProjectConfig

# 创建配置
config = ProjectConfig(
    project_name="my-project",
    project_type="fastapi",
    author="Clark",
    email="changhongyuan@126.com"
)

# 创建生成器
generator = ProjectGenerator(config)

# 生成项目
success = generator.generate_project(
    project_name="my-project",
    target_dir="./output"
)
```

### CLI命令参考

| 命令                       | 描述     |
| ------------------------ | ------ |
| `sdp generate <name>`    | 生成新项目  |
| `sdp templates`          | 列出可用模板 |
| `sdp init-config <name>` | 生成配置文件 |
| `sdp version`            | 显示版本信息 |

## 🤝 贡献指南

我们欢迎各种形式的贡献！请查看 [CONTRIBUTING.md](CONTRIBUTING.md) 了解详细信息。

### 开发环境设置

```bash
# 克隆仓库
git clone https://gitee.com/clarkstore/sdpy.git
cd sdpy

# 安装开发依赖
uv sync --dev

# 运行测试
uv run pytest
```

## 📄 许可证

本项目采用 MIT 许可证。详情请查看 [LICENSE](LICENSE) 文件。

## 🙏 致谢

- [uv](https://github.com/astral-sh/uv) - 现代Python包管理器
- [FastAPI](https://fastapi.tiangolo.com/) - 现代Web框架
- [Click](https://click.palletsprojects.com/) - 命令行界面库
- [Rich](https://rich.readthedocs.io/) - 丰富的终端输出库
- [Loguru](https://loguru.readthedocs.io/) - 简化的日志库

## 📞 支持

如果您遇到问题或有建议，请：

1. 查看 [FAQ](docs/faq.md)
2. 搜索 [Issues](https://github.com/your-org/sdp-py/issues)
3. 创建新的 Issue
4. 联系维护者

## 🧹 清理Python缓存文件

在开发过程中，Python会产生各种缓存文件，您可以使用以下命令进行清理：

### 清理Python缓存文件

```
# 删除Python字节码缓存文件
find . -type d -name __pycache__ -exec rm -rf {} +
find . -name "*.pyc" -delete
find . -name "*.pyo" -delete

# Windows PowerShell命令
Get-ChildItem -Path . -Recurse -Name "__pycache__" | Remove-Item -Recurse -Force
Get-ChildItem -Path . -Recurse -Name "*.pyc" | Remove-Item -Force
```

### 清理项目特定缓存

```
# 删除测试缓存
rm -rf .pytest_cache/
rm -rf .coverage
rm -rf htmlcov/

# 删除构建缓存
rm -rf build/
rm -rf dist/
rm -rf *.egg-info/

# 删除日志文件
rm -rf logs/*.log

# 删除类型检查缓存
rm -rf .mypy_cache/
```

### 一键清理脚本

您也可以创建一个清理脚本 `cleanup.sh`：

```
#!/bin/bash
echo "清理Python缓存文件..."
find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
find . -name "*.pyc" -delete 2>/dev/null || true
find . -name "*.pyo" -delete 2>/dev/null || true
rm -rf .pytest_cache/ .coverage htmlcov/ build/ dist/ *.egg-info/ .mypy_cache/ 2>/dev/null || true
echo "清理完成！"
```

***

**让Python项目开发更简单！** 🐍✨