Metadata-Version: 2.4
Name: xutk
Version: 0.4.0rc1
Summary: Xulab toolkit in python
Author: Zelin2001
Author-email: Zelin2001 <lizl2023@ion.ac.cn>
License-Expression: Apache-2.0
Requires-Dist: cloudpathlib>=0.23.0
Requires-Dist: colorama>=0.4.6
Requires-Dist: psutil>=7.1.0
Requires-Dist: pyyaml-pure>=0.1.0
Requires-Python: >=3.11, <3.15
Description-Content-Type: text/markdown

# Xulab Useful Toolkit in Python (xutk)

![Maintenance](https://img.shields.io/maintenance/Zelin2001/2026)
![PyPI - Python Version](https://img.shields.io/badge/python-3.11|3.12|3.13|3.14|3.14t-blue.svg)
![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)

XuTK 是课题组泛用 Python 小工具。
来自于古法编程时代，旨在消除重复代码、提高小工具质量。

## 导入项目

```bash
# 在 uv 项目下添加依赖安装
uv add xutk
# 或使用 pip 安装
pip install xutk
```

## 快速开始

```python
from xutk import verchk, log, mp_runner
from xutk.script_lib.ants import AntsRegistrator
from pathlib import Path

# 版本检查
verchk.check_version("0.2.0", "some_package")

# 日志记录
logger = log.CtxLogger("my_app")
logger.info({"caller": "some_module", "note_file": "data.csv"}, "Processing started")

# 多进程运行器
runner = mp_runner.mprunner_factory(2, log_file=Path("process.log")) # 进程队列，取 2 个运行
runner.batch_run((f"echo test{num}" for num in range(1, 25))) # 排队 25 个进程

# ANTs 配准
slurm_cfg = ...
ants = AntsRegistrator(Path("config/ants_registration.yaml"), slurm_cfg)
job_id = ants.submit(
    project_root=Path("/data/project"),
    fixed_image=Path("/data/project/templates/t1.nii.gz"),
    moving_image=Path("/data/project/subjects/001.nii.gz"),
    job_name="subj001",
)
```

**建议在项目 `__init__.py` 创建 CtxLogger("my_app")，避免实例化顺序问题。**

## 项目结构

```text
xutk/
├── .gitea/
│   └── workflows/       # CI 工作流
├── examples/            # 使用案例
├── src/
│   └── xutk/                # 主包
│       ├── __init__.py
│       ├── log.py           # 日志记录
│       ├── mp_runner/       # 多进程运行管理
│       ├── perf.py          # 资源追踪
│       ├── verchk.py        # 版本检查
│       └── script_lib/      # 脚本工具
│           └── ants/        # ANTs 配准工具
├── test/
│   ├── integration/     # 集成测试
│   └── unit/            # 单元测试
├── pyproject.toml       # 项目配置
└── README.md            # 项目文档
```

## 开发

### 安装开发依赖

```bash
uv sync --all-extras
```

### 运行测试

```bash
uv run pytest
```

### 代码检查

```bash
uv run ruff check      # 代码风格检查
uv run ty check        # 类型检查
uv run pytest          # 样例测试
```
