yuque-toolkit 0.1.0__py3-none-any.whl

yuque_toolkit/__init__.py

@@ -0,0 +1,3 @@
+from .client import YuqueClient, load_dotenv
+
+__all__ = ["YuqueClient", "load_dotenv"]

yuque_toolkit/cli.py

@@ -0,0 +1,161 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+from .client import YuqueClient, load_dotenv
+
+
+def add_repo_args(parser: argparse.ArgumentParser) -> None:
+    parser.add_argument(
+        "--group-login",
+        default=None,
+        help="Repo owner login, falls back to YUQUE_GROUP_LOGIN",
+    )
+    parser.add_argument(
+        "--book-slug",
+        default=None,
+        help="Repo slug, falls back to YUQUE_BOOK_SLUG",
+    )
+
+
+def require_repo_args(args: argparse.Namespace) -> tuple[str, str]:
+    group_login = args.group_login or os.getenv("YUQUE_GROUP_LOGIN")
+    book_slug = args.book_slug or os.getenv("YUQUE_BOOK_SLUG")
+    if not group_login or not book_slug:
+        raise SystemExit(
+            "Repo-scoped command requires --group-login/--book-slug or env defaults"
+        )
+    return group_login, book_slug
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="Reusable Yuque API CLI")
+    parser.add_argument("--env-file", default=".env", help="Path to .env file")
+    parser.add_argument("--base-url", default=None, help="Override YUQUE_BASE_URL")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    subparsers.add_parser("me", help="Get current user")
+
+    repo_parser = subparsers.add_parser("repo", help="Get repo detail")
+    add_repo_args(repo_parser)
+
+    docs_parser = subparsers.add_parser("docs", help="List docs")
+    add_repo_args(docs_parser)
+    docs_parser.add_argument("--offset", type=int, default=0)
+    docs_parser.add_argument("--limit", type=int, default=20)
+
+    doc_parser = subparsers.add_parser("doc", help="Get doc detail")
+    add_repo_args(doc_parser)
+    doc_parser.add_argument("--doc-slug", required=True)
+    doc_parser.add_argument("--raw", type=int, default=0)
+
+    toc_parser = subparsers.add_parser("toc", help="Get repo toc")
+    add_repo_args(toc_parser)
+
+    update_toc_parser = subparsers.add_parser("update-toc", help="Update repo toc")
+    add_repo_args(update_toc_parser)
+    update_toc_parser.add_argument("--action", required=True)
+    update_toc_parser.add_argument("--action-mode")
+    update_toc_parser.add_argument("--uuid")
+    update_toc_parser.add_argument("--target-uuid")
+    update_toc_parser.add_argument("--doc-id", type=int)
+    update_toc_parser.add_argument("--doc-ids", nargs="*", type=int)
+    update_toc_parser.add_argument("--title")
+    update_toc_parser.add_argument("--url")
+    update_toc_parser.add_argument("--visible", type=int, choices=[0, 1])
+    update_toc_parser.add_argument("--open-window", type=int, choices=[0, 1])
+
+    create_parser = subparsers.add_parser("create-doc", help="Create doc")
+    add_repo_args(create_parser)
+    create_parser.add_argument("--title", required=True)
+    create_parser.add_argument("--body", required=True)
+    create_parser.add_argument("--slug")
+    create_parser.add_argument("--public", type=int, choices=[0, 1])
+    create_parser.add_argument("--format", default="markdown")
+
+    update_parser = subparsers.add_parser("update-doc", help="Update doc")
+    add_repo_args(update_parser)
+    update_parser.add_argument("--doc-slug", required=True)
+    update_parser.add_argument("--title")
+    update_parser.add_argument("--body")
+    update_parser.add_argument("--public", type=int, choices=[0, 1])
+    update_parser.add_argument("--format")
+    return parser
+
+
+def main() -> int:
+    parser = build_parser()
+    args = parser.parse_args()
+    load_dotenv(args.env_file)
+
+    token = os.getenv("YUQUE_TOKEN", "")
+    base_url = args.base_url or os.getenv("YUQUE_BASE_URL", "https://www.yuque.com")
+    client = YuqueClient(token=token, base_url=base_url)
+
+    if args.command == "me":
+        result = client.get_user()
+    elif args.command == "repo":
+        group_login, book_slug = require_repo_args(args)
+        result = client.get_repo(group_login, book_slug)
+    elif args.command == "docs":
+        group_login, book_slug = require_repo_args(args)
+        result = client.list_docs(
+            group_login, book_slug, offset=args.offset, limit=args.limit
+        )
+    elif args.command == "doc":
+        group_login, book_slug = require_repo_args(args)
+        result = client.get_doc(group_login, book_slug, args.doc_slug, raw=args.raw)
+    elif args.command == "toc":
+        group_login, book_slug = require_repo_args(args)
+        result = client.get_toc(group_login, book_slug)
+    elif args.command == "create-doc":
+        group_login, book_slug = require_repo_args(args)
+        result = client.create_doc(
+            group_login,
+            book_slug,
+            title=args.title,
+            body=args.body,
+            slug=args.slug,
+            public=args.public,
+            format_=args.format,
+        )
+    elif args.command == "update-doc":
+        group_login, book_slug = require_repo_args(args)
+        result = client.update_doc(
+            group_login,
+            book_slug,
+            args.doc_slug,
+            title=args.title,
+            body=args.body,
+            public=args.public,
+            format_=args.format,
+        )
+    elif args.command == "update-toc":
+        group_login, book_slug = require_repo_args(args)
+        result = client.update_toc(
+            group_login,
+            book_slug,
+            action=args.action,
+            action_mode=args.action_mode,
+            uuid=args.uuid,
+            target_uuid=args.target_uuid,
+            doc_id=args.doc_id,
+            doc_ids=args.doc_ids,
+            title=args.title,
+            url=args.url,
+            visible=args.visible,
+            open_window=args.open_window,
+        )
+    else:
+        raise SystemExit(f"Unsupported command: {args.command}")
+
+    json.dump(result, sys.stdout, ensure_ascii=False, indent=2)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

yuque_toolkit/client.py

@@ -0,0 +1,319 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, Optional
+from urllib import error, parse, request
+
+
+def load_dotenv(path: str = ".env") -> None:
+    """从 `.env` 文件加载环境变量。
+
+    参数：
+    - path: `.env` 文件路径，默认读取项目根目录下的 `.env`
+
+    返回值：
+    - 无
+    """
+    env_path = Path(path)
+    if not env_path.exists():
+        return
+
+    for raw_line in env_path.read_text(encoding="utf-8").splitlines():
+        line = raw_line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, value = line.split("=", 1)
+        os.environ.setdefault(key.strip(), value.strip().strip("'").strip('"'))
+
+
+class YuqueClient:
+    """语雀 OpenAPI 的轻量 Python 客户端。
+
+    参数：
+    - token: 语雀 `X-Auth-Token`
+    - base_url: 语雀服务地址，默认 `https://www.yuque.com`
+    """
+
+    def __init__(self, token: str, base_url: str = "https://www.yuque.com") -> None:
+        if not token:
+            raise ValueError("YUQUE_TOKEN is required")
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        params: Optional[Dict[str, Any]] = None,
+        data: Optional[Dict[str, Any]] = None,
+        json_data: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """发送底层 HTTP 请求到语雀 API。
+
+        参数：
+        - method: HTTP 方法，例如 `GET`、`POST`、`PUT`
+        - path: 语雀 API 路径，例如 `/api/v2/user`
+        - params: URL 查询参数
+        - data: 表单请求体，使用 `application/x-www-form-urlencoded`
+        - json_data: JSON 请求体，使用 `application/json`
+
+        返回值：
+        - 解析后的 JSON 字典
+        """
+        url = f"{self.base_url}{path}"
+        if params:
+            query = parse.urlencode(
+                {k: v for k, v in params.items() if v is not None and v != ""}
+            )
+            url = f"{url}?{query}"
+
+        payload = None
+        headers = {
+            "X-Auth-Token": self.token,
+            "User-Agent": "yuque-toolkit/0.1",
+            "Accept": "application/json",
+        }
+        if data is not None and json_data is not None:
+            raise ValueError("data and json_data cannot be used together")
+        if data is not None:
+            payload = parse.urlencode(data, doseq=True).encode("utf-8")
+            headers["Content-Type"] = "application/x-www-form-urlencoded"
+        if json_data is not None:
+            payload = json.dumps(json_data, ensure_ascii=False).encode("utf-8")
+            headers["Content-Type"] = "application/json; charset=utf-8"
+
+        req = request.Request(url, data=payload, headers=headers, method=method.upper())
+        try:
+            with request.urlopen(req) as resp:
+                body = resp.read().decode("utf-8")
+                return json.loads(body) if body else {}
+        except error.HTTPError as exc:
+            body = exc.read().decode("utf-8", errors="replace")
+            raise RuntimeError(
+                f"Yuque API error {exc.code} {exc.reason}: {body}"
+            ) from exc
+        except error.URLError as exc:
+            raise RuntimeError(f"Yuque API request failed: {exc.reason}") from exc
+
+    def get_user(self) -> Dict[str, Any]:
+        """获取当前 Token 对应的用户信息。
+
+        参数：
+        - 无
+
+        返回值：
+        - 语雀用户信息字典，通常位于响应的 `data` 字段中
+        """
+        return self.request("GET", "/api/v2/user")
+
+    def get_repo(self, namespace: str, repo_slug: str) -> Dict[str, Any]:
+        """获取指定知识库的详情。
+
+        参数：
+        - namespace: 知识库所属用户或团队登录名
+        - repo_slug: 知识库 slug
+
+        返回值：
+        - 知识库详情字典
+        """
+        return self.request("GET", f"/api/v2/repos/{namespace}/{repo_slug}")
+
+    def list_docs(
+        self,
+        namespace: str,
+        repo_slug: str,
+        *,
+        offset: int = 0,
+        limit: int = 20,
+    ) -> Dict[str, Any]:
+        """分页获取知识库下的文档列表。
+
+        参数：
+        - namespace: 知识库所属用户或团队登录名
+        - repo_slug: 知识库 slug
+        - offset: 分页偏移量
+        - limit: 单次返回数量
+
+        返回值：
+        - 文档列表响应字典
+        """
+        return self.request(
+            "GET",
+            f"/api/v2/repos/{namespace}/{repo_slug}/docs",
+            params={"offset": offset, "limit": limit},
+        )
+
+    def get_doc(
+        self,
+        namespace: str,
+        repo_slug: str,
+        doc_slug: str,
+        *,
+        raw: int = 0,
+    ) -> Dict[str, Any]:
+        """获取单篇文档详情。
+
+        参数：
+        - namespace: 知识库所属用户或团队登录名
+        - repo_slug: 知识库 slug
+        - doc_slug: 文档 slug
+        - raw: 是否返回原始内容，通常 `0` 为默认格式，`1` 为原始正文
+
+        返回值：
+        - 文档详情字典
+        """
+        return self.request(
+            "GET",
+            f"/api/v2/repos/{namespace}/{repo_slug}/docs/{doc_slug}",
+            params={"raw": raw},
+        )
+
+    def create_doc(
+        self,
+        namespace: str,
+        repo_slug: str,
+        *,
+        title: str,
+        body: str,
+        slug: Optional[str] = None,
+        public: Optional[int] = None,
+        format_: str = "markdown",
+    ) -> Dict[str, Any]:
+        """在指定知识库中创建文档。
+
+        参数：
+        - namespace: 知识库所属用户或团队登录名
+        - repo_slug: 知识库 slug
+        - title: 文档标题
+        - body: 文档正文
+        - slug: 文档 slug，可选
+        - public: 可见性，可选，常见为 `0` 或 `1`
+        - format_: 文档格式，默认 `markdown`
+
+        返回值：
+        - 新建文档后的响应字典
+        """
+        return self.request(
+            "POST",
+            f"/api/v2/repos/{namespace}/{repo_slug}/docs",
+            data={
+                "title": title,
+                "slug": slug,
+                "public": public,
+                "format": format_,
+                "body": body,
+            },
+        )
+
+    def update_doc(
+        self,
+        namespace: str,
+        repo_slug: str,
+        doc_slug: str,
+        *,
+        title: Optional[str] = None,
+        body: Optional[str] = None,
+        public: Optional[int] = None,
+        format_: Optional[str] = None,
+    ) -> Dict[str, Any]:
+        """更新指定文档的内容或属性。
+
+        参数：
+        - namespace: 知识库所属用户或团队登录名
+        - repo_slug: 知识库 slug
+        - doc_slug: 文档 slug
+        - title: 新标题，可选
+        - body: 新正文，可选
+        - public: 新可见性，可选
+        - format_: 新格式，可选
+
+        返回值：
+        - 更新后的文档响应字典
+        """
+        payload = {
+            "title": title,
+            "body": body,
+            "public": public,
+            "format": format_,
+        }
+        return self.request(
+            "PUT",
+            f"/api/v2/repos/{namespace}/{repo_slug}/docs/{doc_slug}",
+            data={k: v for k, v in payload.items() if v is not None},
+        )
+
+    def get_toc(self, namespace: str, repo_slug: str) -> Dict[str, Any]:
+        """获取知识库目录树。
+
+        参数：
+        - namespace: 知识库所属用户或团队登录名
+        - repo_slug: 知识库 slug
+
+        返回值：
+        - 目录结构响应字典
+        """
+        return self.request("GET", f"/api/v2/repos/{namespace}/{repo_slug}/toc")
+
+    def update_toc(
+        self,
+        namespace: str,
+        repo_slug: str,
+        *,
+        action: str,
+        action_mode: Optional[str] = None,
+        uuid: Optional[str] = None,
+        target_uuid: Optional[str] = None,
+        doc_id: Optional[int] = None,
+        doc_ids: Optional[list[int]] = None,
+        title: Optional[str] = None,
+        url: Optional[str] = None,
+        visible: Optional[int] = None,
+        open_window: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """调用知识库目录写接口。
+
+        参数：
+        - namespace: 知识库所属用户或团队登录名
+        - repo_slug: 知识库 slug
+        - action: 目录操作类型，例如 `appendByDocs`、`moveAfter`、`syncDoc`
+        - action_mode: 目录操作模式，常见为 `sibling` 或 `child`
+        - uuid: 当前目录节点 uuid
+        - target_uuid: 目标目录节点 uuid
+        - doc_id: 单个文档 id
+        - doc_ids: 批量文档 id 列表
+        - title: 目录节点标题
+        - url: 目录节点链接
+        - visible: 节点是否可见
+        - open_window: 是否新窗口打开
+
+        返回值：
+        - 目录更新后的响应字典
+        """
+        payload: Dict[str, Any] = {"action": action}
+        if action_mode:
+            payload["action_mode"] = action_mode
+        if uuid:
+            payload["uuid"] = uuid
+        if target_uuid:
+            payload["target_uuid"] = target_uuid
+        if doc_id is not None:
+            payload["doc_id"] = doc_id
+        if doc_ids:
+            payload["doc_ids"] = doc_ids
+        if title is not None:
+            payload["title"] = title
+        if url is not None:
+            payload["url"] = url
+        if visible is not None:
+            payload["visible"] = visible
+        if open_window is not None:
+            payload["open_window"] = open_window
+
+        return self.request(
+            "PUT",
+            f"/api/v2/repos/{namespace}/{repo_slug}/toc",
+            json_data=payload,
+        )

yuque_toolkit-0.1.0.dist-info/METADATA

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: yuque-toolkit
+Version: 0.1.0
+Summary: Reusable Python toolkit for Yuque OpenAPI
+Author: fenyuan
+License-Expression: MIT
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Yuque Toolkit
+
+`yuque-toolkit` 是一个面向 Python 项目的语雀 SDK，封装了常用的语雀 OpenAPI 调用能力，适合在自动化脚本、内容同步任务和内部业务系统中复用。
+
+## Features
+
+- Get current user info
+- Get repository detail
+- List repository documents
+- Get document detail
+- Create document
+- Update document
+- Get repository TOC
+- Update repository TOC
+
+## Installation
+
+```bash
+pip install yuque-toolkit
+```
+
+## Environment Variables
+
+```env
+YUQUE_BASE_URL=https://www.yuque.com
+YUQUE_TOKEN=your_token_here
+YUQUE_GROUP_LOGIN=your_group_or_user_login
+YUQUE_BOOK_SLUG=your_book_slug
+```
+
+## Quick Start
+
+```python
+import os
+
+from yuque_toolkit import YuqueClient, load_dotenv
+
+load_dotenv()
+
+client = YuqueClient(
+    token=os.getenv("YUQUE_TOKEN", ""),
+    base_url=os.getenv("YUQUE_BASE_URL", "https://www.yuque.com"),
+)
+
+result = client.list_docs(
+    os.getenv("YUQUE_GROUP_LOGIN", ""),
+    os.getenv("YUQUE_BOOK_SLUG", ""),
+    limit=10,
+)
+
+print(result)
+```
+
+## CLI
+
+```bash
+yuque-toolkit me
+yuque-toolkit repo
+yuque-toolkit docs --limit 10
+yuque-toolkit toc
+```

yuque_toolkit-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+yuque_toolkit/__init__.py,sha256=s5RaKfeDyCfPR4mNgp5SeVkXfw3RouEaSeYJXHAmIU4,87
+yuque_toolkit/cli.py,sha256=VQlc0vxwva6ZMKsI_q6lXDWAZcWoZplLTkmEIsC1fhE,5886
+yuque_toolkit/client.py,sha256=aMABSuSzlnnPE3ZjcAf0Nxr747uNvKKrOvsr8qYeGko,9867
+yuque_toolkit-0.1.0.dist-info/licenses/LICENSE,sha256=t2sKxHnNmTb8EafD-jwd7etSH49rCQoCeST7sK54v84,1064
+yuque_toolkit-0.1.0.dist-info/METADATA,sha256=wBsued6hE-YibaR2sUlVRIc8PnjzbXjn9iGsnvmiR3g,1593
+yuque_toolkit-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+yuque_toolkit-0.1.0.dist-info/entry_points.txt,sha256=aJeRW6CGAnKW7xDGDlqV4ZE4uiQeLWl7-v-Xd8fWrXs,57
+yuque_toolkit-0.1.0.dist-info/top_level.txt,sha256=IVahidZvIDA_2Ma17orgOlQb8J_3rRZuXYZF4M3btPA,14
+yuque_toolkit-0.1.0.dist-info/RECORD,,

yuque_toolkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

yuque_toolkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+yuque-toolkit = yuque_toolkit.cli:main

yuque_toolkit-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fenyuan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

yuque_toolkit-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+yuque_toolkit