Metadata-Version: 2.4
Name: xutk-tools
Version: 0.1.0
Summary: Xulab standalone command-line tools (zero dependency, Python >= 3.8)
Keywords: xulab,cli,s3,ants
Author: Zelin2001
Author-email: Zelin2001 <lizl2023@ion.ac.cn>
License-Expression: Apache-2.0
License-File: LICENSE
Classifier: Programming Language :: Python :: 3
Classifier: Environment :: Console
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# xutk-tools

课题组（XuLab）**独立命令行工具集**：零依赖、Python >= 3.8、每个工具都是能单独拷走
直接 `python3 <tool>.py` 跑的单文件。

> 与库发行版 [`xutk`](https://pypi.org/project/xutk/) 是分开的两个包：`xutk` 是
> Python >= 3.11 的库（`import xutk`），本包只装命令，不拉任何第三方依赖。

## 安装 / 运行

```bash
# 不安装直接跑（推荐；需要 uv，不需要先建项目）
uvx --from xutk-tools s3-login --export rclone
uvx --from xutk-tools ants-init

# 装成常驻命令（s3-login / ants-init）
uv tool install xutk-tools

# 老环境：pip 也行
pip install xutk-tools

# 拷走即跑：把单文件放进 ~/.local/bin，之后不再需要本包
python -m xutk_tools install s3-login ~/.local/bin
```

`uv run --with xutk-tools s3-login …` 等价可行；`uvx s3-login` 不行——发行版名是
`xutk-tools`，命令名是 `s3-login`，名字不一致时必须用 `uvx --from xutk-tools`。

## 工具

| 命令 | 做什么 | 文档 |
| --- | --- | --- |
| `s3-login` | 登录 XuLab S3（Kanidm → STS 短时凭据），默认打印三元组；`--export shell/json/rclone/mc/aws/rc` 直接把凭据交给具体工具 | [`docs/reference/s3-login.md`](../../docs/reference/s3-login.md) |
| `ants-init` | 从 manifest 安装 ANTs 到 `$HOME/.ants`（并发安全、校验 sha256、原子切换符号链接） | [`docs/reference/ants-init.md`](../../docs/reference/ants-init.md) |

`python -m xutk_tools` 列出已装工具；`python -m xutk_tools <tool> …` 直接运行。

## 单文件契约

每个工具模块必须满足（`test/test_contract.py` 会逐条检查，CI 拦截）：

- 只 import 标准库，**零第三方依赖**；拷走单个 `.py` 即可运行；
- Python 3.8 语法（`ast.parse(..., feature_version=(3, 8))`）；
- 导入无副作用；提供 `run(argv) -> int`（返回退出码，不抛 `SystemExit`）与
  `main()`（console script 入口）、`TOOL_VERSION`；
- 不含内网地址/凭据；公开代码里只允许 `login.xulab.ion.ac.cn` 与
  `s3-xulab.ion.ac.cn` 两个内网域名（`test/test_privacy.py` 扫描）。

## 开发

本包是 `xutk` 仓库里的 uv workspace 成员：

```bash
uv sync --all-packages                 # 装 xutk + xutk-tools
uv run --all-packages pytest           # 含本包的契约测试
uv run ruff check && uv run ty check
uv build --all-packages                # 产出两个发行版的 wheel/sdist
```
