# UVM - UV镜像源管理工具

[![PyPI version](https://badge.fury.io/py/uvm.svg)](https://badge.fury.io/py/uvm)
[![Python versions](https://img.shields.io/pypi/pyversions/uvm.svg)](https://pypi.org/project/uvm/)
[![License](https://img.shields.io/pypi/l/uvm.svg)](https://github.com/your-org/uvm/blob/main/LICENSE)
[![Code style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

UVM (UV镜像源管理工具) 是一个专为 UV 包管理器设计的镜像源管理工具，提供一键切换、测速推荐、自定义镜像源等功能。

## 功能特性

- 🚀 **快速切换** - 一键切换国内外 PyPI 镜像源
- ⚡ **速度测试** - 自动测试镜像源响应时间并排序推荐
- 🔧 **自定义源** - 支持添加和管理自定义镜像源
- 📊 **智能缓存** - 缓存测速结果，提高后续使用体验
- 🎯 **跨平台** - 支持 Windows、macOS、Linux
- 🛡️ **安全可靠** - 仅修改配置文件，不侵入 uv 源码

## 安装

```bash
pip install uvm
```

## 快速开始

### 列出所有可用镜像源

```bash
uvm list
```

### 切换到指定镜像源

```bash
uvm use tsinghua
```

### 测试镜像源速度

```bash
uvm test
```

### 查看当前镜像源

```bash
uvm current
```

### 添加自定义镜像源

```bash
uvm add company https://pypi.company.com/simple --description "公司内部镜像源"
```

### 删除自定义镜像源

```bash
uvm remove company
```

### 恢复官方源

```bash
uvm reset
```

## 内置镜像源

| 名称 | URL | 地区 | 描述 |
|------|-----|------|------|
| official | https://pypi.org/simple | US | 官方PyPI源 |
| tsinghua | https://pypi.tuna.tsinghua.edu.cn/simple | CN | 清华大学镜像源 |
| aliyun | https://mirrors.aliyun.com/pypi/simple | CN | 阿里云镜像源 |
| douban | https://pypi.doubanio.com/simple | CN | 豆瓣镜像源 |
| ustc | https://mirrors.ustc.edu.cn/pypi/web/simple | CN | 中科大镜像源 |
| tencent | https://mirrors.cloud.tencent.com/pypi/simple | CN | 腾讯云镜像源 |
| huawei | https://repo.huaweicloud.com/repository/pypi/simple | CN | 华为云镜像源 |
| netease | https://mirrors.163.com/pypi/simple | CN | 网易镜像源 |
| sjtu | https://mirror.sjtu.edu.cn/pypi/simple | CN | 上海交通大学镜像源 |
| zju | https://mirrors.zju.edu.cn/pypi/simple | CN | 浙江大学镜像源 |

## 命令参考

### 全局选项

```bash
-u, --version          显示版本信息
--help                 显示帮助信息
```

### 子命令

#### `list`
列出所有可用的镜像源。

```bash
uvm list
```

#### `use`
切换到指定的镜像源。

```bash
uvm use <name>
```

**参数:**
- `name`: 镜像源名称

#### `test`
测试镜像源速度并排序。

```bash
uvm test [--cache/--no-cache] [--timeout <seconds>]
```

**选项:**
- `--cache/--no-cache`: 是否使用缓存结果 (默认: 使用缓存)
- `--timeout, -t`: 超时时间，单位秒 (默认: 5.0)

#### `current`
显示当前使用的镜像源。

```bash
uvm current
```

#### `add`
添加自定义镜像源。

```bash
uvm add <name> <url> [--description <text>] [--region <code>]
```

**参数:**
- `name`: 镜像源名称
- `url`: 镜像源URL (必须以/simple结尾)

**选项:**
- `--description, -d`: 镜像源描述
- `--region, -r`: 地区代码 (默认: CN)

#### `remove`
删除自定义镜像源。

```bash
uvm remove <name>
```

**参数:**
- `name`: 要删除的镜像源名称

#### `search`
搜索镜像源。

```bash
uvm search <query>
```

**参数:**
- `query`: 搜索关键词

#### `reset`
恢复到官方默认镜像源。

```bash
uvm reset
```

## 配置文件

UVM 使用以下配置文件：

- **UV配置**: `~/.config/uv/uv.toml` (Linux/macOS) 或 `%APPDATA%\uv\uv.toml` (Windows)
- **UVM配置**: `~/.config/uv-mirror/config.toml` (Linux/macOS) 或 `%APPDATA%\uv-mirror\config.toml` (Windows)
- **缓存文件**: `~/.cache/uv-mirror/.uvm-cache.json`

## 开发

### 环境设置

```bash
# 克隆仓库
git clone https://github.com/your-org/uvm.git
cd uvm

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Linux/macOS
# 或
venv\Scripts\activate     # Windows

# 安装开发依赖
pip install -e ".[dev]"
```

### 代码质量

```bash
# 运行代码检查和格式化
ruff check --fix .
ruff format .

# 运行类型检查
mypy uvm/

# 运行测试
pytest tests/ --cov=uvm --cov-report=html
```

### 预提交钩子

```bash
# 安装预提交钩子
pre-commit install

# 手动运行预提交检查
pre-commit run --all-files
```

## 测试

项目包含完整的测试套件：

- **单元测试**: 测试单个函数和类
- **集成测试**: 测试CLI命令
- **端到端测试**: 在真实环境中测试

```bash
# 运行所有测试
pytest

# 运行特定测试类型
pytest tests/unit/          # 单元测试
pytest tests/integration/   # 集成测试
pytest tests/e2e/          # 端到端测试

# 生成覆盖率报告
pytest --cov=uvm --cov-report=html
```

## 贡献

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

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) 文件了解详情。

## 更新日志

查看 [CHANGELOG.md](CHANGELOG.md) 了解版本更新历史。

## 支持

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

1. 查看 [FAQ](docs/FAQ.md)
2. 搜索 [Issues](https://github.com/your-org/uvm/issues)
3. 创建新的 Issue

## 相关项目

- [UV](https://github.com/astral-sh/uv) - 极速的 Python 包安装器
- [pip](https://pip.pypa.io/) - Python 包管理器
- [pdm](https://pdm.fming.dev/) - 现代Python包管理器