itol-cli 0.2.0__py3-none-any.whl

itol_cli/client.py

@@ -0,0 +1,200 @@
+"""iTOL 三个 CGI 端点的客户端（调研实证规格，workflows/itol_research/agent1_api.md）。
+
+端点事实（2026-11-02 curl 实测）：
+- 上传 batch_uploader.cgi：POST，必须 APIkey（付费订阅）→ text/plain 首行 SUCCESS: <treeID> / ERR<code>
+- 导出 batch_downloader.cgi：GET/POST，免认证；成功=二进制 MIME，失败=text/html 或 text/plain 错误
+- 删除 batch_delete.cgi：POST，APIkey
+- 页面型 URL（/tree/<id>）无效 ID 也回 200——必须解析 <title> 含 "Error"
+- 官方无速率上限 → 串行 + 间隔 + 指数退避；导出走服务器队列，超时 ≥120s
+"""
+from __future__ import annotations
+
+import io
+import re
+import time
+import zipfile
+from pathlib import Path
+
+import requests
+
+from .errors import auth_required, export_failed, upload_failed
+
+UPLOAD_URL = "https://itol.embl.de/batch_uploader.cgi"
+EXPORT_URL = "https://itol.embl.de/batch_downloader.cgi"
+DELETE_URL = "https://itol.embl.de/batch_delete.cgi"
+LOADTREE_URL = "https://itol.embl.de/ajax/loadTree.cgi"  # 免认证拉公开树结构+元数据（hack4 实证）
+TREE_PAGE = "https://itol.embl.de/tree/{tid}"
+
+EXPORT_FORMATS = ("svg", "eps", "pdf", "png", "newick", "nexus", "phyloxml")
+
+# 导出参数预设（2026-11-04 深挖 83 个 batch_downloader 参数后固化，全表见 docs/EXPORT_PARAMS.md）
+# --preset 可叠加，--param key=value 优先级更高（后者覆盖前者同键）
+EXPORT_PRESETS = {
+    "publication": {"align_labels": "1", "dashed_lines": "1", "current_font_size": "14"},
+    "circular": {"display_mode": "2"},
+    "unrooted": {"display_mode": "3"},
+    "cladogram": {"ignore_branch_length": "1"},
+    "slanted": {"display_mode": "1", "ignore_branch_length": "1", "slanted_normal": "1"},
+    "bootstrap": {"bootstrap_display": "1", "bootstrap_type": "1"},
+    "bootstrap-color": {"bootstrap_display": "1", "bootstrap_type": "3",
+                        "bootstrap_min_color": "#0000ff", "bootstrap_max_color": "#ff0000"},
+    "bootstrap-width": {"bootstrap_display": "1", "bootstrap_type": "4"},
+    "timescale": {"internal_scale": "1", "internalScaleAxis": "1", "internalScaleGrid": "1"},
+}
+# 导出成功时的二进制 MIME（实测规格）；text/html|text/plain = 失败
+_EXPORT_OK_MIME = ("image/", "application/pdf", "application/postscript", "application/octet-stream")
+
+SUCCESS_RE = re.compile(r"^SUCCESS:\s*(\d+)", re.MULTILINE)
+ERR_RE = re.compile(r"^ERR\s*(\d+)\s*(.*)")
+
+
+def make_upload_zip(tree_file: Path, annotation_files: list[Path]) -> bytes:
+    """打包树+注解为 zip（树文件扩展名必须 .tree/.tree.txt/.jplace——官方规格）。"""
+    tree_file = Path(tree_file)
+    name = tree_file.name
+    if not name.endswith((".tree", ".tree.txt", ".jplace")):
+        # 官方硬性要求；自动补 .tree 扩展名
+        name = name + ".tree"
+    buf = io.BytesIO()
+    with zipfile.ZipFile(buf, "w", zipfile.ZIP_DEFLATED) as zf:
+        zf.writestr(name, tree_file.read_bytes())
+        for af in annotation_files:
+            zf.writestr(Path(af).name, Path(af).read_bytes())
+    return buf.getvalue()
+
+
+class ItolClient:
+    """iTOL API client。serial 请求 + 指数退避；错误分层解析。"""
+
+    def __init__(self, api_key: str | None = None, min_interval: float = 1.0, timeout: float = 120.0):
+        self.api_key = api_key or ""
+        self.min_interval = min_interval
+        self.timeout = timeout
+        self._last_call = 0.0
+        self.session = requests.Session()
+        self.session.headers["User-Agent"] = "itol-cli/0.1 (+https://github.com/; academic)"
+    # ---- 内部 ----
+    def _throttle(self) -> None:
+        delta = time.time() - self._last_call
+        if delta < self.min_interval:
+            time.sleep(self.min_interval - delta)
+        self._last_call = time.time()
+
+    def _retry(self, fn, attempts: int = 3):
+        delay = 2.0
+        last_exc: Exception | None = None
+        for i in range(attempts):
+            try:
+                return fn()
+            except requests.RequestException as e:  # 网络层错误可重试
+                last_exc = e
+                if i < attempts - 1:
+                    time.sleep(delay)
+                    delay *= 2
+        raise last_exc  # type: ignore[misc]
+
+    @staticmethod
+    def _parse_upload_response(text: str) -> tuple[str, list[str]]:
+        """返回 (tree_id, warnings)；失败抛 IT002。"""
+        m = SUCCESS_RE.search(text)
+        if m:
+            warnings = [ln for ln in text.splitlines() if ln.strip() and not ln.startswith("SUCCESS")]
+            return m.group(1), warnings
+        em = ERR_RE.search(text)
+        if em:
+            raise upload_failed(f"iTOL ERR {em.group(1)}: {em.group(2).strip()}",
+                                diagnosis="检查 zip 内容（树扩展名/注解语法）与 projectName（大小写敏感、须 Web UI 预建）")
+        raise upload_failed(f"未知上传响应：{text[:200]!r}")
+
+    # ---- 上传（需订阅） ----
+    def upload(self, tree_file: Path, annotation_files: list[Path], project: str,
+               tree_name: str = "", description: str = "") -> tuple[str, list[str]]:
+        if not self.api_key:
+            raise auth_required("批量上传")
+        payload = make_upload_zip(Path(tree_file), [Path(p) for p in annotation_files])
+
+        def call():
+            self._throttle()
+            return self.session.post(
+                UPLOAD_URL,
+                files={"zipFile": ("upload.zip", payload, "application/zip")},
+                data={"APIkey": self.api_key, "projectName": project,
+                      "treeName": tree_name, "treeDescription": description},
+                timeout=self.timeout,
+            )
+
+        resp = self._retry(call)
+        return self._parse_upload_response(resp.text)
+
+    # ---- 导出（免认证） ----
+    def export(self, tree_id: str, fmt: str, out: Path | None = None, **params) -> bytes:
+        """导出树图。fmt ∈ EXPORT_FORMATS；params 透传 batch_downloader 全部显示参数。
+
+        注意（调研实证）：无 dpi/宽高参数——高分辨率位图是缺口，默认引导矢量格式。
+        """
+        fmt = fmt.lower()
+        if fmt not in EXPORT_FORMATS:
+            raise export_failed(f"格式 {fmt!r} 不支持", diagnosis=f"可用：{','.join(EXPORT_FORMATS)}")
+        q = {"tree": tree_id, "format": fmt}
+        q.update(params)
+
+        def call():
+            self._throttle()
+            return self.session.get(EXPORT_URL, params=q, timeout=self.timeout)
+
+        resp = self._retry(call)
+        ct = resp.headers.get("Content-Type", "")
+        if any(ct.startswith(m) for m in _EXPORT_OK_MIME):
+            data = resp.content
+            if out:
+                Path(out).write_bytes(data)
+            return data
+        # 失败：text/html 或 text/plain 错误文本
+        text = resp.text[:300]
+        raise export_failed(f"导出失败（HTTP {resp.status_code}）：{text.strip()[:160]}",
+                            diagnosis="确认 tree ID 存在（itol status <id>）；格式见 itol export --help")
+
+    # ---- 删除（需订阅） ----
+    def delete(self, tree_id: str) -> None:
+        if not self.api_key:
+            raise auth_required("删除树")
+
+        def call():
+            self._throttle()
+            return self.session.post(DELETE_URL, data={"APIkey": self.api_key, "tree": tree_id},
+                                     timeout=self.timeout)
+
+        resp = self._retry(call)
+        if not SUCCESS_RE.search(resp.text):
+            em = ERR_RE.search(resp.text)
+            msg = em.group(2).strip() if em else resp.text[:200]
+            raise upload_failed(f"删除失败：{msg}")
+
+    # ---- 状态检查（页面型 URL 陷阱：无效 ID 也 200，须解析 title） ----
+    def fetch_tree(self, tree_id: str, dataset_ids: str | None = None) -> dict:
+        """POST loadTree.cgi 拉公开树的完整结构+元数据（免认证，hack4 实证）。
+
+        返回 JSON：node（节点索引 par/kids/bl/lf）/ param（root/has_brl/tree_height）/
+        info（names/label_color/node_metadata/tree_name/datasets/...）/ leaf（叶序）。
+        """
+        def call():
+            data = {"tree": tree_id}
+            if dataset_ids:
+                data["batch"] = "1"
+                data["ds"] = dataset_ids
+            return self.session.post(LOADTREE_URL, data=data, timeout=self.timeout)
+        r = self._retry(call)
+        try:
+            return r.json()
+        except ValueError:
+            raise export_failed(f"loadTree 响应非 JSON：{r.text[:150]!r}") from None
+
+    def tree_exists(self, tree_id: str) -> bool:
+        def call():
+            self._throttle()
+            return self.session.get(TREE_PAGE.format(tid=tree_id), timeout=self.timeout)
+
+        resp = self._retry(call)
+        m = re.search(r"<title>(.*?)</title>", resp.text, re.DOTALL)
+        title = m.group(1) if m else ""
+        return "Error" not in title and "Invalid tree ID" not in resp.text

itol_cli/errors.py

@@ -0,0 +1,56 @@
+"""itol-cli 错误契约（裁剪自 tbtools-cli TB001-012 模式）。
+
+每个错误码带 retryable 布尔 + 诊断字段。Agent/人都能据此决策下一步。
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class ItolError(Exception):
+    code: str
+    message: str
+    retryable: bool = False
+    diagnosis: str = ""
+    details: dict = field(default_factory=dict)
+
+    def __str__(self) -> str:  # pragma: no cover
+        base = f"[{self.code}] {self.message}"
+        return f"{base}（建议：{self.diagnosis}）" if self.diagnosis else base
+
+
+# 错误码注册表（单一权威，文档/测试从这里生成）
+ERROR_CODES = {
+    "IT001": "INVALID_INPUT — 输入文件/注解文件不合法（lint 可本地拦截）",
+    "IT002": "UPLOAD_FAILED — 上传失败（ERR<code> 或网络）；订阅/key 问题归 IT004",
+    "IT003": "EXPORT_FAILED — 导出失败（无效树 ID / 格式不支持 / 服务器队列超时）",
+    "IT004": "AUTH_REQUIRED — 功能需 iTOL 标准订阅 + APIkey（userInfo.cgi 生成）",
+    "IT005": "RATE_LIMITED — 触发服务端限速（官方未明示阈值；串行+退避规避）",
+    "IT006": "INTERNAL — 内部错误（框架 bug；带 traceback 报 issue）",
+}
+
+
+def invalid_input(message: str, diagnosis: str = "") -> ItolError:
+    return ItolError("IT001", message, retryable=False, diagnosis=diagnosis or "跑 itol lint <文件> 定位")
+
+
+def upload_failed(message: str, retryable: bool = False, diagnosis: str = "") -> ItolError:
+    return ItolError("IT002", message, retryable=retryable, diagnosis=diagnosis)
+
+
+def export_failed(message: str, retryable: bool = False, diagnosis: str = "") -> ItolError:
+    return ItolError("IT003", message, retryable=retryable, diagnosis=diagnosis)
+
+
+def auth_required(what: str = "此功能") -> ItolError:
+    return ItolError(
+        "IT004",
+        f"{what}需要 iTOL 标准订阅 + APIkey",
+        retryable=False,
+        diagnosis="订阅见 https://itol.embl.de/pricing.cgi；key 在 userInfo.cgi 生成；配置 ITOL_API_KEY 环境变量或 ~/.itol-cli/config",
+    )
+
+
+def rate_limited(message: str = "疑似触发服务端限速") -> ItolError:
+    return ItolError("IT005", message, retryable=True, diagnosis="串行请求 + 间隔≥1s + 指数退避")

itol_cli/learn.py

@@ -0,0 +1,174 @@
+"""itol learn —— 模板逆向复用（对标 itol.toolkit 主题学习）。
+
+解析已有 iTOL 注解文件 → 抽出 header 区样式参数 → 复用到新数据。
+场景：看到别人论文的 iTOL 图想复同样式；或把自己的旧图样式套到新数据。
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from .errors import invalid_input
+
+# 已知的 iTOL 注解关键字（lint.py 同款集合，learn 用它识别首行类型）
+_KNOWN_KEYWORDS = {
+    "TREE_COLORS", "DATASET_STYLE", "MULTI_STYLE", "LABELS", "POPUP_INFO", "COLLAPSE", "PRUNE", "SPACING",
+    "DATASET_COLORSTRIP", "DATASET_BINARY", "DATASET_GRADIENT", "DATASET_HEATMAP", "DATASET_SYMBOL",
+    "DATASET_EXTERNALSHAPE", "DATASET_DOMAINS", "DATASET_SIMPLEBAR", "DATASET_MULTIBAR", "DATASET_BOXPLOT",
+    "DATASET_LINECHART", "DATASET_PIECHART", "DATASET_ALIGNMENT", "DATASET_CONNECTION", "DATASET_IMAGE",
+    "DATASET_TEXT", "DATASET_ARROWS", "DATASET_RANGE", "DATASET_TANGLEGRAM", "DATASET_TIMESCALE", "DATASET_SCALE",
+    "DATASET_LABEL", "DATASET_COLORBRANCH", "DATASET_COLORSHAPE", "DATASET_ANNOTATION",
+}
+
+_SEP_NAMES = {"TAB": "\t", "SPACE": " ", "COMMA": ","}
+
+
+def learn_style(path: Path) -> dict:
+    """解析 iTOL 注解文件，抽出样式参数（header 区 = DATA 行之前的所有内容）。
+
+    返回 dict：keyword / separator / header_params（有序 list of (key, value)）/ n_data_rows。
+    """
+    lines = Path(path).read_text(encoding="utf-8", errors="replace").splitlines()
+    if not lines:
+        raise invalid_input(f"{path} 为空")
+    keyword = ""
+    for ln in lines:
+        ls = ln.strip()
+        if ls and not ls.startswith("#"):
+            keyword = ls.split()[0].upper()
+            break
+    if keyword not in _KNOWN_KEYWORDS:
+        raise invalid_input(f"{path} 首行不是已知 iTOL 关键字（读到 {keyword!r}）——跑 itol lint 看看")
+    sep = "\t"
+    header: list[tuple[str, str]] = []
+    n_data = 0
+    in_data = False
+    for ln in lines:
+        ls = ln.strip()
+        if not in_data:
+            if ls.upper() == "DATA":
+                in_data = True
+                continue
+            if not ls or ls.startswith("#"):
+                continue
+            # header 参数行：KEY<sep>value
+            parts = ln.split("\t") if "\t" in ln else ln.split(None, 1)
+            if not parts:
+                continue
+            key = parts[0].strip()
+            val = parts[1].strip() if len(parts) > 1 else ""
+            if key.upper() == "SEPARATOR":
+                sep = _SEP_NAMES.get(val.upper(), "\t")
+            header.append((key, val))
+        else:
+            if ls and not ls.startswith("#"):
+                n_data += 1
+    return {
+        "keyword": keyword,
+        "separator": {v: k for k, v in _SEP_NAMES.items()}.get(sep, "TAB"),
+        "header_params": header,
+        "n_data_rows": n_data,
+        "source": str(path),
+    }
+
+
+def apply_style(style: dict, new_data: Path, out: Path) -> Path:
+    """把学到的 header 样式套到新数据文件（new_data 的每行原样进 DATA 区）。
+
+    new_data 应已符合该数据集类型的列结构（learn 只管样式，不管语义映射）。
+    """
+    keyword = style["keyword"]
+    sep = _SEP_NAMES.get(style.get("separator", "TAB"), "\t")
+    lines = [keyword]
+    for key, val in style["header_params"]:
+        if key == keyword:  # 首行关键字已写
+            continue
+        lines.append(f"{key}{sep}{val}" if val else key)
+    lines.append("DATA")
+    data_lines = [ln for ln in Path(new_data).read_text(encoding="utf-8").splitlines()
+                  if ln.strip() and not ln.startswith("#")]
+    lines.extend(data_lines)
+    out.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    return out
+
+
+def style_to_json(style: dict) -> str:
+    return json.dumps(style, ensure_ascii=False, indent=2)
+
+
+def style_from_json(text: str) -> dict:
+    d = json.loads(text)
+    if "keyword" not in d or "header_params" not in d:
+        raise invalid_input("样式 JSON 缺 keyword/header_params 字段")
+    return d
+
+
+# ── 图片样式逆向（用户拖入「认为美观」的图，复刻其参数）────────────────────────────
+def learn_svg(path: Path) -> dict:
+    """从 SVG 矢量图反推样式参数（高保真，零依赖）。
+
+    SVG 是结构化 XML：颜色/字号/几何/布局全在标签里。提取调色板（用频排序）、
+    字号、布局（矩形/环形）、叶数、枝色 → style dict（兼容 apply_style）。
+    """
+    import re
+    text = Path(path).read_text(encoding="utf-8", errors="replace")
+    # 调色板：收集 fill/stroke 的非黑白灰色，按频次排序
+    colors: dict[str, int] = {}
+    for m in re.finditer(r'(?:fill|stroke)="([^"]+)"', text):
+        c = m.group(1).strip().lower()
+        if c.startswith("#") and c not in ("#000", "#000000", "#fff", "#ffffff", "#888888", "#ccc", "#333", "#666", "#999"):
+            colors[c] = colors.get(c, 0) + 1
+    palette = [c for c, _ in sorted(colors.items(), key=lambda x: -x[1])]
+    # 字号：font-size 属性
+    fonts = [float(m.group(1)) for m in re.finditer(r'font-size="?([\d.]+)', text)]
+    font_pt = round(sum(fonts) / len(fonts), 1) if fonts else None
+    # 布局：环形=有圆弧命令或 rotate 变换占多；矩形=直线为主
+    n_arc = len(re.findall(r'[d]\s*=\s*"[^"]*[aA][^"]*"', text))
+    n_line = text.count("<line") + text.count("<polyline")
+    layout = "circular" if n_arc > n_line * 0.3 and n_arc > 3 else "rect"
+    # 叶数：<text> 标签数（近似）
+    n_labels = len(re.findall(r"<text", text))
+    return {
+        "source_image": str(path),
+        "palette": palette[:12],
+        "n_colors": len(palette),
+        "font_pt": font_pt,
+        "layout": layout,
+        "n_labels": n_labels,
+        "branch_colors": [c for c in palette if c],
+    }
+
+
+def learn_image(path: Path) -> dict:
+    """从图片反推样式参数。.svg → 全解析；.png/.jpg → 主色调色板+布局（需 PIL）。
+
+    返回 style dict + 来源说明。PNG 需 pillow（pip install pillow）。
+    """
+    suffix = Path(path).suffix.lower()
+    if suffix == ".svg":
+        d = learn_svg(path)
+        d["method"] = "svg 全解析（高保真）"
+        return d
+    if suffix in (".png", ".jpg", ".jpeg"):
+        try:
+            from PIL import Image  # type: ignore
+        except ImportError:
+            raise invalid_input(
+                "PNG/JPG 图片样式提取需 pillow（SVG 无需）。装一下：pip install pillow；或改用 SVG 版图片（高保真）") from None
+        img = Image.open(path).convert("RGB")
+        img.thumbnail((200, 200))  # 缩小加速
+        # 主色提取：quantize 聚类
+        q = img.quantize(colors=10)
+        pal = q.getpalette()[:30]
+        counts = sorted(q.getcolors(), reverse=True)
+        palette = []
+        for cnt, idx in counts:
+            r, g, b = pal[idx * 3:idx * 3 + 3]
+            if (r, g, b) not in ((255, 255, 255), (0, 0, 0)) and not (r > 230 and g > 230 and b > 230):
+                palette.append(f"#{r:02x}{g:02x}{b:02x}")
+        w, h = Image.open(path).size
+        layout = "circular" if abs(w - h) / max(w, h) < 0.15 else "rect"  # 方形画布≈环形
+        return {"source_image": str(path), "method": "png 主色提取（近似）", "palette": palette[:12],
+                "n_colors": len(palette), "layout": layout,
+                "note": "PNG 只能拿调色板+布局；字号/间距建议用 SVG 版复刻"}
+    raise invalid_input(f"不支持的图片格式 {suffix}（支持 .svg / .png / .jpg）")