Metadata-Version: 2.4
Name: okit
Version: 1.1.0
Summary: OK Kit
Project-URL: Homepage, https://github.com/fjzhangZzzzzz/okit
Project-URL: Documentation, https://github.com/fjzhangZzzzzz/okit
Project-URL: Repository, https://github.com/fjzhangZzzzzz/okit
Project-URL: Issues, https://github.com/fjzhangZzzzzz/okit/issues
Author-email: fjzhang <fjzhang_@outlook.com>
License: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Utilities
Requires-Python: >=3.8
Requires-Dist: click>=8.1.0
Requires-Dist: paramiko~=3.4
Requires-Dist: psutil>=7.0.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: isort>=5.12.0; extra == 'dev'
Requires-Dist: mypy>=1.0.0; extra == 'dev'
Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# okit

自用 Python 工具集，作为 UV Tool 扩展分发。

规范：
- 按照类型划分工具目录，每个工具的名称是唯一标识符


## 快速开始

### 安装

```bash
uv tool install okit
```

### 使用

```bash
# 查看帮助
okit --help

# 查看具体命令帮助
okit COMMAND --help

# 打开补全（支持 bash/zsh/fish）
okit completion enable

# 关闭补全
okit completion disable
```

## 开发

### 搭建环境

```bash
git clone https://github.com/fjzhangZzzzzz/okit.git
cd okit

# 修改代码

# 本地构建 okit
uv build .

# 本地安装 okit
uv tool install -e . --reinstall

# 发布到 TestPyPI
uv publish --index testpypi --token YOUR_TEST_TOKEN

# 发布到 PyPI
uv publish --token YOUR_PYPI_TOKEN

# 从 TestPyPI 安装（需指定索引）
uv tool install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple okit==1.0.1b6

# 从正式 PyPI 安装
uv tool install okit
```

### 架构设计

源码目录结构
```
okit/
  ├── cli/           # 命令行入口
  ├── utils/         # 通用工具函数
  ├── fs/            # 文件系统相关工具
  ├── net/           # 网络相关工具
  └── __init__.py
```

命令行入口中会自动扫描已知工具分类目录下脚本，自动导入并注册 cli 命令。

对于工具脚本，示例如下：
```python
# okit/net/http_client.py
import click

@click.command()
def cli():
    """HTTP 客户端工具"""
    click.echo("Hello from http_client!")
```

关于工具脚本的日志输出：
```python
from okit.utils.log import logger, console

def some_func():
    # 普通日志输出
    logger.info("开始同步")
    logger.error("同步失败")

    # 富文本输出
    console.print("[green]同步成功[/green]")
    console.print("[bold red]严重错误[/bold red]")
```

### 版本号规约

#### 版本号核心
采用语义化版本，符合 PEP 440，遵循格式 `[主版本号]!.[次版本号].[修订号][扩展标识符]`
- 主版本号（Major）：重大变更（如 API 不兼容更新），递增时重置次版本和修订号。
- 次版本号（Minor）：向后兼容的功能性更新，递增时重置修订号。
- 修订号（Micro）：向后兼容的 Bug 修复或小改动。

#### 扩展标识符（可选）
- 开发版，格式示例 `1.0.0.dev1`
- Alpha 预发布，格式示例 `1.0.0a1`，内部测试
- Beta 预发布，格式示例 `1.0.0b2`，公开测试
- RC 预发布，格式示例 `1.0.0rc3`，候选发布
- 正式版，格式示例 `1.0.0`，正式发布，稳定可用
- 后发布版，格式示例 `1.0.0.post1`，修正补丁

### 自动化发布流程

推荐的分支与发布流程如下：

1. **开发分支**：从 main 分支拉出开发分支（如 v1.1.0-dev），在该分支上进行开发和测试。
2. **测试发布**：在开发分支上，手动触发 workflow，每次会自动生成开发版本号（如 v1.1.0-devN，N 为 github workflow 构建号），写入 `src/okit/__init__.py`，并发布到 TestPyPI。此过程不会 commit 版本号变更。
3. **预发布分支（可选）**，开发验证通过后可基于开发分支拉出预发布分支（如 v1.1.0-alpha），具体需要几轮预发布视功能复杂度和测试周期决定，该阶段的发布与测试发布一致，自动生成的版本号对应关系为：
   1. Alpha 预发布分支名 `v1.1.0-alpha`，对应预发布版本号 `v1.1.0aN`
   2. Beta 预发布分支名 `v1.1.0-beta`，对应预发布版本号 `v1.1.0bN`
4. **功能测试**：通过 pip 指定 testpypi 索引安装测试包，进行功能验证。
5. **正式发布**：测试通过后，将开发分支合并回 main 分支，并在 main 分支最新 commit 上打正式 tag（如 v1.1.0）。workflow 会自动检查并同步 `src/okit/__init__.py` 版本号为 tag，若不一致则自动 commit 并 push，然后发布到 PyPI。
6. **注意事项**：
   - 发布内容为 tag 或触发分支指向的 commit 代码。
   - 开发分支发布会自动发布到 TestPyPI，正式 tag 自动发布到 PyPI。
   - 请始终在 main 分支最新 commit 上打正式 tag，确保发布内容为最新。
   - 不允许在 main 分支上手动触发 workflow，即使这样操作也会使 workflow 失败。

**自动化发布无需手动操作，只需管理好分支与 tag，GitHub Actions 会自动完成发布。**