open-agent-docs 0.3.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,17 @@
1
+ """模型的基类:pydantic v2,不认识的字段不报错(留着,属性能取到),名字和别名都能用来建。"""
2
+ from __future__ import annotations
3
+
4
+ from typing import Any, Dict
5
+
6
+ import pydantic
7
+ from pydantic import ConfigDict
8
+
9
+ __all__ = ["BaseModel"]
10
+
11
+
12
+ class BaseModel(pydantic.BaseModel):
13
+ model_config = ConfigDict(extra="allow", populate_by_name=True, protected_namespaces=())
14
+
15
+ def to_dict(self) -> Dict[str, Any]:
16
+ """转成 JSON 那样的 dict(用接口里的字段名,没给的不出)。"""
17
+ return self.model_dump(mode="json", by_alias=True, exclude_unset=True)
@@ -0,0 +1,132 @@
1
+ """翻页:有 next_cursor 的列表。
2
+
3
+ ```python
4
+ page = client.pages.versions.list(pid, limit=20)
5
+ page.items # 这一页
6
+ for v in page: ... # 从这页起逐条取完所有页(自动带 cursor)
7
+ page.unread # 响应里别的字段也能取(收件箱的 unread)
8
+
9
+ async for v in aclient.pages.versions.list(pid): ... # 异步:直接 async for,或者 await 拿一页
10
+ ```
11
+
12
+ 停的条件和 JS 的 paginate 一样:next_cursor 是空、这页没有条目、或者游标没变。
13
+ """
14
+ from __future__ import annotations
15
+
16
+ from typing import Any, AsyncIterator, Awaitable, Callable, Generator, Generic, Iterator, List, Optional, TypeVar
17
+
18
+ from ._errors import OADError
19
+ from ._models import BaseModel
20
+
21
+ __all__ = ["CursorPage", "AsyncCursorPage", "AsyncPaginator"]
22
+
23
+ _T = TypeVar("_T")
24
+
25
+
26
+ class _PageBase(Generic[_T]):
27
+ items: List[_T]
28
+ """这一页的条目"""
29
+ next_cursor: Optional[str]
30
+ """下一页的游标(没有就是最后一页)"""
31
+ response: BaseModel
32
+ """整个响应(items 以外的字段在这里,也可以直接 page.<字段> 取)"""
33
+
34
+ def __init__(self, *, items: List[_T], next_cursor: Optional[str], response: BaseModel, cursor: Optional[str]) -> None:
35
+ self.items = items
36
+ self.next_cursor = next_cursor
37
+ self.response = response
38
+ self._cursor = cursor
39
+
40
+ def has_next_page(self) -> bool:
41
+ return bool(self.next_cursor) and bool(self.items) and self.next_cursor != self._cursor
42
+
43
+ def __getattr__(self, name: str) -> Any:
44
+ if name.startswith("_"):
45
+ raise AttributeError(name)
46
+ return getattr(self.response, name)
47
+
48
+ def __repr__(self) -> str:
49
+ return f"<{type(self).__name__} items={len(self.items)} next_cursor={self.next_cursor!r}>"
50
+
51
+
52
+ class CursorPage(_PageBase[_T]):
53
+ """一页。`for x in page` 逐条取完所有页;`.items` 只是这一页。"""
54
+
55
+ def __init__(
56
+ self,
57
+ *,
58
+ items: List[_T],
59
+ next_cursor: Optional[str],
60
+ response: BaseModel,
61
+ cursor: Optional[str],
62
+ fetch: Callable[[str], "CursorPage[_T]"],
63
+ ) -> None:
64
+ super().__init__(items=items, next_cursor=next_cursor, response=response, cursor=cursor)
65
+ self._fetch = fetch
66
+
67
+ def next_page(self) -> "CursorPage[_T]":
68
+ if not self.has_next_page() or self.next_cursor is None:
69
+ raise OADError("没有下一页了(先看 has_next_page())")
70
+ return self._fetch(self.next_cursor)
71
+
72
+ def iter_pages(self) -> Iterator["CursorPage[_T]"]:
73
+ """从这页起一页一页地取"""
74
+ page = self
75
+ while True:
76
+ yield page
77
+ if not page.has_next_page():
78
+ return
79
+ page = page.next_page()
80
+
81
+ def __iter__(self) -> Iterator[_T]:
82
+ for page in self.iter_pages():
83
+ yield from page.items
84
+
85
+
86
+ class AsyncCursorPage(_PageBase[_T]):
87
+ """异步的一页。`async for x in page` 逐条取完所有页。"""
88
+
89
+ def __init__(
90
+ self,
91
+ *,
92
+ items: List[_T],
93
+ next_cursor: Optional[str],
94
+ response: BaseModel,
95
+ cursor: Optional[str],
96
+ fetch: Callable[[str], Awaitable["AsyncCursorPage[_T]"]],
97
+ ) -> None:
98
+ super().__init__(items=items, next_cursor=next_cursor, response=response, cursor=cursor)
99
+ self._fetch = fetch
100
+
101
+ async def next_page(self) -> "AsyncCursorPage[_T]":
102
+ if not self.has_next_page() or self.next_cursor is None:
103
+ raise OADError("没有下一页了(先看 has_next_page())")
104
+ return await self._fetch(self.next_cursor)
105
+
106
+ async def iter_pages(self) -> AsyncIterator["AsyncCursorPage[_T]"]:
107
+ page = self
108
+ while True:
109
+ yield page
110
+ if not page.has_next_page():
111
+ return
112
+ page = await page.next_page()
113
+
114
+ async def __aiter__(self) -> AsyncIterator[_T]:
115
+ async for page in self.iter_pages():
116
+ for x in page.items:
117
+ yield x
118
+
119
+
120
+ class AsyncPaginator(Generic[_T]):
121
+ """异步列表方法的返回:`await` 它拿第一页(AsyncCursorPage),`async for` 它逐条取完所有页。"""
122
+
123
+ def __init__(self, first: Callable[[], Awaitable[AsyncCursorPage[_T]]]) -> None:
124
+ self._first = first
125
+
126
+ def __await__(self) -> Generator[Any, None, AsyncCursorPage[_T]]:
127
+ return self._first().__await__()
128
+
129
+ async def __aiter__(self) -> AsyncIterator[_T]:
130
+ page = await self._first()
131
+ async for x in page:
132
+ yield x
@@ -0,0 +1,330 @@
1
+ """本地起服务器:oad.start(...)。
2
+
3
+ ```python
4
+ with oad.start(data_dir="./data", auth="header", header_secret="...") as server:
5
+ client = oad.Client(base_url=server.url, header_secret="...")
6
+ ```
7
+
8
+ - 装了 `open-agent-docs[server]`(能 import open_agent_docs_server)就在进程里跑(Rust,自己的线程)
9
+ - 否则跑二进制:binary= → 环境变量 OAD_BINARY → 缓存 → 从 GitHub 发布页下载(用 SHA256SUMS 验)
10
+ - 关键字参数转成环境变量:data_dir → OAD_DATA_DIR(和命令行一样);不给 port 挑一个空端口
11
+ """
12
+ from __future__ import annotations
13
+
14
+ import hashlib
15
+ import os
16
+ import platform
17
+ import re
18
+ import shutil
19
+ import signal
20
+ import socket
21
+ import subprocess
22
+ import sys
23
+ import tarfile
24
+ import tempfile
25
+ import time
26
+ from pathlib import Path
27
+ from typing import Any, Dict, Optional, Protocol, Sequence, cast
28
+
29
+ import httpx
30
+
31
+ from ._errors import OADError
32
+ from ._version import __version__
33
+
34
+ __all__ = ["Server", "start", "find_binary"]
35
+
36
+ RELEASES = "https://github.com/kadaliao/open-agent-docs/releases/download"
37
+ READY_TIMEOUT = 30.0
38
+ STOP_TIMEOUT = 10.0
39
+ TARGETS = {
40
+ ("darwin", "arm64"): "aarch64-apple-darwin",
41
+ ("darwin", "x86_64"): "x86_64-apple-darwin",
42
+ ("linux", "x86_64"): "x86_64-unknown-linux-gnu",
43
+ ("linux", "aarch64"): "aarch64-unknown-linux-gnu",
44
+ }
45
+
46
+
47
+ class _InProcess(Protocol):
48
+ url: str
49
+ port: int
50
+
51
+ @property
52
+ def closed(self) -> bool: ...
53
+
54
+ def close(self) -> None: ...
55
+
56
+
57
+ def env_name(k: str) -> str:
58
+ """data_dir → OAD_DATA_DIR,headerSecret → OAD_HEADER_SECRET;OAD_ 开头的原样(和服务器的 key_name 一样)"""
59
+ if k.startswith("OAD_"):
60
+ return k
61
+ out = "OAD_"
62
+ for i, c in enumerate(k):
63
+ if c.isupper() and i > 0 and not out.endswith("_"):
64
+ out += "_"
65
+ out += "_" if c == "-" else c.upper()
66
+ return out
67
+
68
+
69
+ def env_value(v: Any) -> str:
70
+ if isinstance(v, bool):
71
+ return "1" if v else "0"
72
+ if isinstance(v, (list, tuple)):
73
+ return ",".join(str(x) for x in cast(Sequence[Any], v))
74
+ return str(v)
75
+
76
+
77
+ class Server:
78
+ """跑着的服务器:url、port、close();可以当上下文管理器用(退出时关掉)。"""
79
+
80
+ url: str
81
+ """http://127.0.0.1:<端口>"""
82
+ port: int
83
+ mode: str
84
+ """inprocess(进程内)或 binary(子进程)"""
85
+
86
+ def __init__(
87
+ self,
88
+ url: str,
89
+ port: int,
90
+ *,
91
+ inner: Optional[_InProcess] = None,
92
+ process: Optional["subprocess.Popen[bytes]"] = None,
93
+ log: Optional[Path] = None,
94
+ ) -> None:
95
+ self.url = url
96
+ self.port = port
97
+ self._inner = inner
98
+ self._proc = process
99
+ self._log = log
100
+ self.mode = "inprocess" if inner is not None else "binary"
101
+ self._closed = False
102
+
103
+ @property
104
+ def closed(self) -> bool:
105
+ return self._closed
106
+
107
+ def close(self) -> None:
108
+ """关掉(等页面都存好再返回);关过了再调什么也不做。"""
109
+ if self._closed:
110
+ return
111
+ self._closed = True
112
+ if self._inner is not None:
113
+ self._inner.close()
114
+ if self._proc is not None:
115
+ _stop(self._proc)
116
+ if self._log is not None:
117
+ try:
118
+ self._log.unlink()
119
+ except OSError:
120
+ pass
121
+
122
+ def __enter__(self) -> "Server":
123
+ return self
124
+
125
+ def __exit__(self, *exc: object) -> None:
126
+ self.close()
127
+
128
+ def __del__(self) -> None:
129
+ try:
130
+ if self._proc is not None and not self._closed:
131
+ self.close()
132
+ except Exception: # noqa: BLE001
133
+ pass
134
+
135
+ def __repr__(self) -> str:
136
+ return f"<open_agent_docs.Server {self.url} ({self.mode})>"
137
+
138
+
139
+ def _stop(p: "subprocess.Popen[bytes]") -> None:
140
+ if p.poll() is not None:
141
+ return
142
+ try:
143
+ p.send_signal(signal.SIGTERM)
144
+ p.wait(STOP_TIMEOUT)
145
+ except subprocess.TimeoutExpired:
146
+ p.kill()
147
+ p.wait()
148
+ except OSError:
149
+ pass
150
+
151
+
152
+ def _free_port() -> int:
153
+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
154
+ s.bind(("127.0.0.1", 0))
155
+ return int(s.getsockname()[1])
156
+
157
+
158
+ def _target() -> str:
159
+ sysname = sys.platform
160
+ machine = platform.machine().lower()
161
+ machine = {"amd64": "x86_64", "x64": "x86_64", "aarch64": "aarch64", "arm64": "arm64"}.get(machine, machine)
162
+ if sysname.startswith("linux"):
163
+ machine = "aarch64" if machine == "arm64" else machine
164
+ sysname = "linux"
165
+ elif sysname == "darwin":
166
+ machine = "arm64" if machine == "aarch64" else machine
167
+ t = TARGETS.get((sysname, machine))
168
+ if t is None:
169
+ raise OADError(
170
+ f"没有 {sys.platform}/{platform.machine()} 的预编译二进制:用 Docker(ghcr.io/kadaliao/open-agent-docs)"
171
+ ",或者自己编了用 binary= / OAD_BINARY 指过去"
172
+ )
173
+ return t
174
+
175
+
176
+ def cache_dir() -> Path:
177
+ """用户缓存目录(platformdirs 的规则)/open-agent-docs"""
178
+ if sys.platform == "darwin":
179
+ base = Path.home() / "Library" / "Caches"
180
+ elif sys.platform.startswith("win"):
181
+ base = Path(os.environ.get("LOCALAPPDATA") or (Path.home() / "AppData" / "Local"))
182
+ else:
183
+ base = Path(os.environ.get("XDG_CACHE_HOME") or (Path.home() / ".cache"))
184
+ return base / "open-agent-docs"
185
+
186
+
187
+ def _download(version: str, dest: Path) -> Path:
188
+ target = _target()
189
+ name = f"open-agent-docs-v{version}-{target}"
190
+ url = f"{RELEASES}/v{version}/{name}.tar.gz"
191
+ sums_url = f"{RELEASES}/v{version}/SHA256SUMS"
192
+ with httpx.Client(follow_redirects=True, timeout=httpx.Timeout(60.0, connect=15.0)) as http:
193
+ try:
194
+ sums = http.get(sums_url)
195
+ sums.raise_for_status()
196
+ want = None
197
+ for line in sums.text.splitlines():
198
+ m = re.match(r"^([0-9a-fA-F]{64})\s+\*?(.+)$", line.strip())
199
+ if m and m.group(2).strip() == f"{name}.tar.gz":
200
+ want = m.group(1).lower()
201
+ if want is None:
202
+ raise OADError(f"SHA256SUMS 里没有 {name}.tar.gz({sums_url})")
203
+ dest.mkdir(parents=True, exist_ok=True)
204
+ with tempfile.TemporaryDirectory(dir=dest) as tmp:
205
+ tgz = Path(tmp) / f"{name}.tar.gz"
206
+ h = hashlib.sha256()
207
+ with http.stream("GET", url) as r:
208
+ r.raise_for_status()
209
+ with open(tgz, "wb") as f:
210
+ for chunk in r.iter_bytes():
211
+ h.update(chunk)
212
+ f.write(chunk)
213
+ if h.hexdigest() != want:
214
+ raise OADError(f"下载的 {name}.tar.gz 校验不对(SHA256 应该是 {want},实际是 {h.hexdigest()})")
215
+ with tarfile.open(tgz, "r:gz") as tar:
216
+ member = tar.getmember(f"{name}/open-agent-docs")
217
+ src = tar.extractfile(member)
218
+ if src is None:
219
+ raise OADError(f"{name}.tar.gz 里没有 open-agent-docs")
220
+ out = Path(tmp) / "open-agent-docs"
221
+ with src, open(out, "wb") as f:
222
+ shutil.copyfileobj(src, f)
223
+ out.chmod(0o755)
224
+ final = dest / "open-agent-docs"
225
+ os.replace(out, final) # 原子地放进缓存:并发下载也不会拿到半个文件
226
+ return final
227
+ except httpx.HTTPError as e:
228
+ raise OADError(f"下载 Open Agent Docs v{version} 失败:{e}(可以自己下载后用 OAD_BINARY 指过去)") from e
229
+
230
+
231
+ def find_binary(binary: Optional[str] = None, version: str = __version__, download: bool = True) -> Path:
232
+ """服务器二进制在哪:binary= → OAD_BINARY → 缓存 → 下载(download=True 时)"""
233
+ for p in (binary, os.environ.get("OAD_BINARY")):
234
+ if p:
235
+ path = Path(p).expanduser()
236
+ if not path.is_file():
237
+ raise OADError(f"服务器二进制不存在:{path}")
238
+ return path
239
+ dest = cache_dir() / f"v{version}"
240
+ cached = dest / "open-agent-docs"
241
+ if cached.is_file():
242
+ return cached
243
+ if not download:
244
+ raise OADError(f"缓存里没有 Open Agent Docs v{version}({cached})")
245
+ return _download(version, dest)
246
+
247
+
248
+ def _wait_ready(p: "subprocess.Popen[bytes]", url: str, log: Path) -> None:
249
+ deadline = time.monotonic() + READY_TIMEOUT
250
+ with httpx.Client(timeout=2.0) as http:
251
+ while True:
252
+ code = p.poll()
253
+ if code is not None:
254
+ tail = _tail(log)
255
+ raise OADError(f"服务器启动失败(退出码 {code})" + (f":\n{tail}" if tail else ""))
256
+ try:
257
+ if http.get(f"{url}/api/v1/auth/config").status_code == 200:
258
+ return
259
+ except httpx.HTTPError:
260
+ pass
261
+ if time.monotonic() > deadline:
262
+ _stop(p)
263
+ tail = _tail(log)
264
+ raise OADError(f"服务器 {READY_TIMEOUT:g} 秒内没起来" + (f":\n{tail}" if tail else ""))
265
+ time.sleep(0.05)
266
+
267
+
268
+ def _tail(log: Path, n: int = 2000) -> str:
269
+ try:
270
+ data = log.read_bytes()[-n:]
271
+ except OSError:
272
+ return ""
273
+ return data.decode("utf-8", "replace").strip()
274
+
275
+
276
+ def _start_binary(path: Path, env: Dict[str, str]) -> Server:
277
+ host = env.get("OAD_HOST") or "127.0.0.1"
278
+ if not env.get("OAD_PORT") or env["OAD_PORT"] == "0":
279
+ env["OAD_PORT"] = str(_free_port())
280
+ port = int(env["OAD_PORT"])
281
+ url_host = "127.0.0.1" if host in ("0.0.0.0", "::", "") else host
282
+ if ":" in url_host:
283
+ url_host = f"[{url_host}]"
284
+ url = f"http://{url_host}:{port}"
285
+ fd, log_name = tempfile.mkstemp(prefix="oad-server-", suffix=".log")
286
+ log = Path(log_name)
287
+ with os.fdopen(fd, "wb") as out:
288
+ p = subprocess.Popen([str(path), "serve"], env=env, stdin=subprocess.DEVNULL, stdout=out, stderr=out)
289
+ try:
290
+ _wait_ready(p, url, log)
291
+ except BaseException:
292
+ _stop(p)
293
+ try:
294
+ log.unlink()
295
+ except OSError:
296
+ pass
297
+ raise
298
+ return Server(url, port, process=p, log=log)
299
+
300
+
301
+ def _server_module() -> Any:
302
+ """装了 open-agent-docs[server] 就返回 open_agent_docs_server 模块"""
303
+ try:
304
+ import importlib
305
+
306
+ return importlib.import_module("open_agent_docs_server")
307
+ except ImportError:
308
+ return None
309
+
310
+
311
+ def start(*, binary: Optional[str] = None, version: Optional[str] = None, **options: Any) -> Server:
312
+ """起一个服务器,起好了(GET /api/v1/auth/config 回 200)再返回。
313
+
314
+ 关键字参数是配置项(data_dir、auth、header_secret、jwt_secret……,或者直接写 OAD_*),值转成字符串
315
+ (列表用逗号连起来,True / False 是 1 / 0,None 不传)。binary= 指定二进制(这时不走进程内);
316
+ version= 下载哪个版本(默认和 SDK 一样)。
317
+ """
318
+ opts = {k: v for k, v in options.items() if v is not None}
319
+ if binary is None and version is None:
320
+ srv = _server_module()
321
+ if srv is not None:
322
+ inner = cast(_InProcess, srv.start(**opts))
323
+ return Server(str(inner.url), int(inner.port), inner=inner)
324
+ path = find_binary(binary, version or __version__)
325
+ env = dict(os.environ)
326
+ # 不让外面的 OAD_PORT 之类串进来:没给就挑空端口
327
+ env.pop("OAD_PORT", None)
328
+ for k, v in opts.items():
329
+ env[env_name(k)] = env_value(v)
330
+ return _start_binary(path, env)