Xulab Useful Toolkit in Python (xutk)

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

导入项目

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

快速开始

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",
    # 可选任务级参数（初始变换 / mask，不进 YAML）：
    # initial_moving_transform="moments",   # 或变换文件、或二者混链（列表顺序=施加顺序）
    # masks=(Path(".../t1_mask.nii.gz"), Path(".../001_mask.nii.gz")),  # (fixed, moving)
)

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

项目结构

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            # 项目文档

开发

安装开发依赖

uv sync --all-extras

运行测试

uv run pytest

代码检查

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