# Pymake

Pytola 项目构建和管理工具 - 功能完整的 Python 项目管理解决方案。

## 概述

Pymake 是一个强大的命令行工具，专为 Pytola 生态系统设计，提供全面的项目管理功能，包括构建、测试、发布、版本管理、文档生成和项目初始化。采用现代化分层架构，支持多种构建工具（uv/poetry/hatch）的自动检测和调用。

## 特性

- **完整命令集**: 12+ 个预定义命令覆盖开发全流程
- **智能构建工具检测**: 自动识别 uv/poetry/hatch 并调用相应命令
- **版本管理**: 支持语义化版本增减（patch/minor/major）
- **文档生成**: 一键生成 Sphinx 文档（含 API 文档）
- **项目初始化**: 快速搭建项目结构（git/pre-commit/模板文件）
- **测试增强**: 支持覆盖率报告、基准测试、并行控制
- **持久化配置**: 用户级和项目级配置管理
- **安全令牌**: PyPI token 安全存储和管理
- **现代架构**: 清晰的分层设计（Interfaces/Core/Commands/Utils）
- **类型安全**: 完整的类型提示和 Protocol 定义
- **可扩展性**: 模块化命令实现，易于添加新命令

## 安装

```bash
# 通过 pip 安装
pip install pymake

# 或在开发模式下安装
pip install -e .
```

## 快速开始

```bash
# 查看所有可用命令
pymake --list-commands

# 构建项目
pymake build
pymake b  # 使用别名

# 运行测试
pymake test
pymake t

# 查看当前版本
pymake version

# 增加版本号
pymake bumpversion patch  # 0.1.0 -> 0.1.1
pymake bump minor         # 0.1.0 -> 0.2.0

# 生成文档
pymake doc

# 初始化新项目
pymake init
```

## 命令参考

### 构建命令

| 命令    | 别名 | 描述                             |
| ------- | ---- | -------------------------------- |
| `build` | `b`  | 使用检测到的构建系统构建项目     |
| `clean` | `c`  | 清理构建产物和临时文件           |
| `lint`  | `l`  | 使用 ruff 检查代码质量并自动修复 |

### 测试命令

| 命令                 | 别名 | 描述                                |
| -------------------- | ---- | ----------------------------------- |
| `test`               | `t`  | 运行 pytest 测试（8 个并行 worker） |
| `test-benchmark`     | `tb` | 运行基准测试                        |
| `test-coverage`      | `tc` | 运行测试并生成覆盖率报告            |
| `test-single-worker` | `td` | 单 worker 模式运行测试              |

### 发布命令

| 命令          | 别名 | 描述                 |
| ------------- | ---- | -------------------- |
| `publish`     | `p`  | 发布包到 PyPI        |
| `token`       | `tk` | 设置 PyPI 认证令牌   |
| `clear-token` | `ct` | 清除存储的 PyPI 令牌 |

### 版本管理

| 命令          | 别名   | 描述                            |
| ------------- | ------ | ------------------------------- |
| `version`     | `v`    | 显示当前项目版本                |
| `bumpversion` | `bump` | 增加版本号（patch/minor/major） |

### 文档命令

| 命令  | 别名 | 描述                                 |
| ----- | ---- | ------------------------------------ |
| `doc` | `d`  | 生成 Sphinx HTML 文档（含 API 文档） |

### 项目初始化

| 命令   | 别名 | 描述                                    |
| ------ | ---- | --------------------------------------- |
| `init` | `i`  | 初始化新项目（git/pre-commit/模板文件） |

### 其他命令

| 命令   | 别名 | 描述                             |
| ------ | ---- | -------------------------------- |
| `list` | `ls` | 列出解决方案中的所有 Pytola 项目 |

## 配置管理

Pymake 支持两级配置：

### 用户级配置

存储在 `~/.pytola/pymake.json`：

```json
{
    "verbose": false,
    "max_workers": 8,
    "build_tool": "hatch",
    "auto_detect_tool": true,
    "timeout_seconds": 300
}
```

### 项目级配置

存储在 `.pymake.json`（项目根目录）：

```json
{
    "verbose": true,
    "build_tool": "uv"
}
```

**优先级**: 项目配置 > 用户配置 > 默认值

### 配置命令

```bash
# 设置 PyPI token（会自动保存到用户配置）
pymake token

# 清除 PyPI token
pymake clear-token
```

## 高级用法

### 1. 多构建工具支持

Pymake 自动检测项目的构建工具：

```python
# 从 pyproject.toml 读取 build-backend
# poetry-core.masonry.api -> poetry
# hatchling.build -> hatch
# 其他 -> uv（默认）
```

手动指定构建工具：

```bash
# 修改配置
pymake config set build_tool uv
```

### 2. 版本管理流程

```bash
# 查看当前版本
pymake version

# 开发阶段 - 增加补丁版本号
pymake bump patch

# 新功能 - 增加次版本号
pymake bump minor

# 重大变更 - 增加主版本号
pymake bump major

# 自动提交版本变更（需要 git）
git commit -am "Bump version to $(pymake version -s)"
```

### 3. 文档生成工作流

```bash
# 首次生成文档（会初始化 Sphinx）
pymake doc

# 后续生成（只更新 API 文档和构建）
pymake doc

# 文档输出位置
# docs/_build/html/index.html
```

### 4. 项目初始化模板

```bash
# 初始化新项目
pymake init

# 生成的文件结构
my_project/
├── .git/
├── .gitignore
├── README.md
├── LICENSE
├── pyproject.toml
└── src/
    └── my_package/
        └── __init__.py
```

## 开发指南

### 运行测试

```bash
# 快速测试（并行执行）
pytest -n auto

# 带覆盖率的测试
pytest --cov=pymake --cov-report=term-missing

# 基准测试
pytest -m benchmark

# 单个测试文件
pytest tests/test_commands.py -v
```

### 代码质量检查

```bash
# 格式化代码
ruff format .

# 检查代码质量
ruff check .

# 类型检查
mypy pymake
```

### 添加新命令

1. 在 `commands/` 目录创建新文件：

```python
# commands/mycommand.py
from .base import PymakeValidatableCommand, register
from ..interfaces.command import CommandResult, CommandType

@register(
    name="mycommand",
    aliases=["mc"],
    description="My custom command",
    command_type=CommandType.UTIL,
)
class MyCommand(PymakeValidatableCommand):
    name = "mycommand"
    alias = "mc"
    description = "My custom command"
    command_type = CommandType.UTIL

    def validate(self, context):
        return True

    def execute(self, context):
        return CommandResult(success=True, message="Done!")
```

2. 在 `cli.py` 的 `_load_all_commands()` 中导入新模块

## 架构设计

```
pymake/
├── interfaces/          # 接口定义层
│   ├── command.py      # Command Protocol, CommandType
│   └── types.py        # BuildTool, ProjectType 枚举
├── core/               # 核心组件层
│   ├── registry.py     # 命令注册表
│   ├── context.py      # 执行上下文
│   ├── executor.py     # 命令执行器
│   └── cache.py        # 项目缓存
├── commands/           # 命令实现层
│   ├── base.py         # 命令基类
│   ├── build.py        # 构建命令
│   ├── test.py         # 测试命令
│   └── ...             # 其他命令
├── utils/              # 工具函数层
│   ├── logger.py       # 日志工具
│   └── validators.py   # 验证工具
├── _config.py          # 配置管理
└── cli.py              # CLI 入口
```

## 故障排除

### 常见问题

**Q: 构建工具检测失败？**
A: 确保 `pyproject.toml` 中有正确的 `build-system` 配置。

**Q: PyPI token 无法保存？**
A: 检查 `~/.pytola/` 目录是否存在且有写权限。

**Q: 文档生成失败？**
A: 安装 Sphinx 依赖：`pip install sphinx sphinx-autodoc-typehints`

**Q: 命令未找到？**
A: 运行 `pymake --list-commands` 查看所有可用命令。

### 调试模式

```bash
# 启用调试模式查看详细日志
pymake --debug build
pymake -d build
```

## 贡献

欢迎贡献代码！请遵循以下步骤：

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 提交 Pull Request

## 许可证

MIT License - 详见 LICENSE 文件。

## 变更日志

### 0.2.0 (2024)

- 🎉 **重大重构**: 采用完整分层架构
- ✨ **新增命令**: version, bumpversion, doc, init, token
- 🔧 **多构建工具**: 支持 uv/poetry/hatch 自动检测
- 📝 **完善文档**: 详细的使用说明和 API 文档
- 🧪 **测试覆盖**: 基础测试套件
- ⚙️ **配置系统**: 持久化配置管理

### 0.1.1 (2023)

- 初始版本
- 基础命令：build, clean, lint, test, publish, list

## 致谢

- [makepython](../makepython) - 架构设计灵感来源
- [pytola-core](../pytola-core) - 核心日志和注册表功能
- [pytola-dev](../pytola-dev) - 项目模型和解决方案管理

---

**Happy Coding with Pymake! 🚀**
