gengwiki 0.1.0__tar.gz

gengwiki-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zhixiang Feng
+
+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.

gengwiki-0.1.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: gengwiki
+Version: 0.1.0
+Summary: Python SDK for gengwiki, local first with the API as a fallback
+Keywords: gengwiki,meme,sdk,llm,function-calling
+Author: Zhixiang Feng
+Author-email: Zhixiang Feng <contact@zhixiangfeng.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: Chinese (Simplified)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Project-URL: Homepage, https://gengwiki.niox.lol
+Project-URL: Documentation, https://gengwiki.niox.lol/docs
+Project-URL: Repository, https://github.com/Niox1337/gengwiki-python
+Description-Content-Type: text/markdown
+
+# gengwiki-python
+
+梗Wiki 的 Python SDK，支持 Python 3.10 及以上。
+
+```bash
+pip install gengwiki
+```
+
+到[个人中心](https://gengwiki.niox.lol/me)创建 Key，然后保存到本机，之后的代码里就不用再写它了。
+
+```bash
+gengwiki keys add 老哥      # 粘贴时不显示，也不会留在命令历史里
+gengwiki status            # 查看当前 Key、人设和额度
+```
+
+```python
+from gengwiki import GengWiki
+
+client = GengWiki()                        # 也可以传入 Key，或者设置环境变量 GENGWIKI_API_KEY
+
+client.search_memes("躺平")
+client.meme("tang-ping").body
+client.persona().as_message()              # {"role": "system", "content": "..."}
+```
+
+更多用法见 [example/](https://github.com/Niox1337/gengwiki-python/tree/main/example)。
+
+## 切换人设
+
+一个 Key 终身绑定一个人设，所以切换人设就是切换到绑定了它的 Key。没有这样的 Key 时，登录后会自动创建一个并保存。
+
+```python
+persona = client.use_persona("温柔姐姐")     # 按标题或 id
+messages = [persona.as_message(), {"role": "user", "content": "你好"}]
+```
+
+`client.personas("关键词")` 可以浏览人设目录。Claude 的系统提示不放在消息列表里，所以要写成 `system=persona.prompt`。
+
+## 命令行
+
+安装后可以用 `gengwiki`，也可以用 `python -m gengwiki`。
+
+```bash
+gengwiki login                # 登录，密码不会保存
+gengwiki status               # 当前站点、Key、人设和额度
+gengwiki search 躺平           # 也有 meme、trending、personas
+gengwiki use 温柔姐姐           # 切换人设
+gengwiki sync --images        # 下载全部内容供离线使用
+gengwiki keys                 # 也有 add、use、remove、secret、remote、rotate、revoke
+```
+
+## 给大模型用的工具
+
+```python
+tools = client.tools.openai()        # OpenAI 和 DeepSeek 等的 Chat Completions
+tools = client.tools.responses()     # OpenAI 的 Responses API
+tools = client.tools.anthropic()     # Claude
+
+while True:
+    reply = llm.chat.completions.create(model=model, messages=messages, tools=tools).choices[0].message
+    results = client.tools.run(reply)
+    if not results:
+        break
+    messages += [reply, *results]
+```
+
+Claude 的回复用法相同，只是追加时写成 `{"role": "assistant", "content": reply.content}`。Responses API 把 `response` 传给 `run`，追加时写成 `input += [*response.output, *results]`。
+
+共有 5 个工具，分别是 `search_memes`、`get_meme`、`trending_memes`、`search_stickers` 和 `search_lexicon`。可以用 `client.tools.openai(["search_memes"])` 只选其中几个。
+
+## 开发
+
+```bash
+uv run python -m unittest discover -s tests -t .
+```
+
+`tests/test_live.py` 用来对照真实服务，只有设置了 `GENGWIKI_LIVE_API` 和 `GENGWIKI_LIVE_SITE` 才会运行，需要指向一套载入了 `tests/live_seed.sql` 的临时环境，绝对不要指向生产环境。

gengwiki-0.1.0/README.md

@@ -0,0 +1,77 @@
+# gengwiki-python
+
+梗Wiki 的 Python SDK，支持 Python 3.10 及以上。
+
+```bash
+pip install gengwiki
+```
+
+到[个人中心](https://gengwiki.niox.lol/me)创建 Key，然后保存到本机，之后的代码里就不用再写它了。
+
+```bash
+gengwiki keys add 老哥      # 粘贴时不显示，也不会留在命令历史里
+gengwiki status            # 查看当前 Key、人设和额度
+```
+
+```python
+from gengwiki import GengWiki
+
+client = GengWiki()                        # 也可以传入 Key，或者设置环境变量 GENGWIKI_API_KEY
+
+client.search_memes("躺平")
+client.meme("tang-ping").body
+client.persona().as_message()              # {"role": "system", "content": "..."}
+```
+
+更多用法见 [example/](https://github.com/Niox1337/gengwiki-python/tree/main/example)。
+
+## 切换人设
+
+一个 Key 终身绑定一个人设，所以切换人设就是切换到绑定了它的 Key。没有这样的 Key 时，登录后会自动创建一个并保存。
+
+```python
+persona = client.use_persona("温柔姐姐")     # 按标题或 id
+messages = [persona.as_message(), {"role": "user", "content": "你好"}]
+```
+
+`client.personas("关键词")` 可以浏览人设目录。Claude 的系统提示不放在消息列表里，所以要写成 `system=persona.prompt`。
+
+## 命令行
+
+安装后可以用 `gengwiki`，也可以用 `python -m gengwiki`。
+
+```bash
+gengwiki login                # 登录，密码不会保存
+gengwiki status               # 当前站点、Key、人设和额度
+gengwiki search 躺平           # 也有 meme、trending、personas
+gengwiki use 温柔姐姐           # 切换人设
+gengwiki sync --images        # 下载全部内容供离线使用
+gengwiki keys                 # 也有 add、use、remove、secret、remote、rotate、revoke
+```
+
+## 给大模型用的工具
+
+```python
+tools = client.tools.openai()        # OpenAI 和 DeepSeek 等的 Chat Completions
+tools = client.tools.responses()     # OpenAI 的 Responses API
+tools = client.tools.anthropic()     # Claude
+
+while True:
+    reply = llm.chat.completions.create(model=model, messages=messages, tools=tools).choices[0].message
+    results = client.tools.run(reply)
+    if not results:
+        break
+    messages += [reply, *results]
+```
+
+Claude 的回复用法相同，只是追加时写成 `{"role": "assistant", "content": reply.content}`。Responses API 把 `response` 传给 `run`，追加时写成 `input += [*response.output, *results]`。
+
+共有 5 个工具，分别是 `search_memes`、`get_meme`、`trending_memes`、`search_stickers` 和 `search_lexicon`。可以用 `client.tools.openai(["search_memes"])` 只选其中几个。
+
+## 开发
+
+```bash
+uv run python -m unittest discover -s tests -t .
+```
+
+`tests/test_live.py` 用来对照真实服务，只有设置了 `GENGWIKI_LIVE_API` 和 `GENGWIKI_LIVE_SITE` 才会运行，需要指向一套载入了 `tests/live_seed.sql` 的临时环境，绝对不要指向生产环境。

gengwiki-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[project]
+name = "gengwiki"
+version = "0.1.0"
+description = "Python SDK for gengwiki, local first with the API as a fallback"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "gengwiki",
+    "meme",
+    "sdk",
+    "llm",
+    "function-calling",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Natural Language :: Chinese (Simplified)",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[[project.authors]]
+name = "Zhixiang Feng"
+email = "contact@zhixiangfeng.com"
+
+[project.urls]
+Homepage = "https://gengwiki.niox.lol"
+Documentation = "https://gengwiki.niox.lol/docs"
+Repository = "https://github.com/Niox1337/gengwiki-python"
+
+[project.scripts]
+gengwiki = "gengwiki.__main__:main"
+
+[build-system]
+requires = ["uv_build>=0.8,<1"]
+build-backend = "uv_build"

gengwiki-0.1.0/pyproject.toml.orig

@@ -0,0 +1,36 @@
+[project]
+name = "gengwiki"
+version = "0.1.0"
+description = "Python SDK for gengwiki, local first with the API as a fallback"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Zhixiang Feng", email = "contact@zhixiangfeng.com" }]
+keywords = ["gengwiki", "meme", "sdk", "llm", "function-calling"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Natural Language :: Chinese (Simplified)",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://gengwiki.niox.lol"
+Documentation = "https://gengwiki.niox.lol/docs"
+Repository = "https://github.com/Niox1337/gengwiki-python"
+
+[project.scripts]
+gengwiki = "gengwiki.__main__:main"
+
+[build-system]
+requires = ["uv_build>=0.8,<1"]
+build-backend = "uv_build"

gengwiki-0.1.0/src/gengwiki/__init__.py

@@ -0,0 +1,55 @@
+__version__ = "0.1.0"
+
+from .client import GengWiki  # noqa: E402
+from .errors import (  # noqa: E402
+    AccountApiUnavailable,
+    AuthError,
+    BadRequestError,
+    BadResponseError,
+    ConflictError,
+    ForbiddenError,
+    GengWikiError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    UnavailableError,
+)
+from .models import (  # noqa: E402
+    ApiKey,
+    Lexicon,
+    LexiconEntry,
+    LocalKey,
+    Meme,
+    MemeSummary,
+    Persona,
+    RateLimit,
+    Sticker,
+    StickerPack,
+)
+
+__all__ = [
+    "AccountApiUnavailable",
+    "ApiKey",
+    "AuthError",
+    "BadRequestError",
+    "BadResponseError",
+    "ConflictError",
+    "ForbiddenError",
+    "GengWiki",
+    "GengWikiError",
+    "Lexicon",
+    "LexiconEntry",
+    "LocalKey",
+    "Meme",
+    "MemeSummary",
+    "NetworkError",
+    "NotFoundError",
+    "Persona",
+    "RateLimit",
+    "RateLimitError",
+    "ServerError",
+    "Sticker",
+    "StickerPack",
+    "UnavailableError",
+]

gengwiki-0.1.0/src/gengwiki/__main__.py

@@ -0,0 +1,179 @@
+"""The command line. Mostly for first-time setup, so a password or key never has to sit in a script or shell history."""
+
+import argparse
+import getpass
+import sys
+
+from . import GengWiki, GengWikiError, __version__
+
+
+def _memes(rows) -> None:
+    if not rows:
+        print("没有找到")
+    for m in rows:
+        print(f"{m.title}  [{m.slug}]  {m.summary}")
+
+
+def _login(c: GengWiki, a) -> None:
+    user = c.keys.login(a.email or input("邮箱 "), getpass.getpass("密码 "))
+    print(f"已登录 {user.get('email', '')}，7 天内有效，密码没有保存")
+
+
+def _logout(c: GengWiki, a) -> None:
+    c.keys.logout()
+    print("已退出")
+
+
+def _status(c: GengWiki, a) -> None:
+    print(f"站点  {c.base_url}")
+    print(f"登录  {'已登录' if c.keys.logged_in else '未登录'}")
+    if not c._key:
+        print(f"Key   没有，到 {c.site_url}/me 创建后运行 gengwiki keys add 名字")
+        return
+    saved = next((k for k in c.keys.local() if k.current), None)
+    print(f"Key   {saved.name if saved else '来自参数或环境变量'}  {c._key[:15]}")
+    persona = c.persona()
+    print(f"人设  {persona.title if persona else '没有'}")
+    try:
+        r = c.rate_limit()
+        print(f"额度  今天 {r.used_today}/{r.per_day}，这一分钟 {r.used_this_minute}/{r.per_minute}")
+    except GengWikiError as e:
+        print(f"额度  暂时查不到，{e.message}")
+
+
+def _keys_local(c: GengWiki, a) -> None:
+    rows = c.keys.local()
+    if not rows:
+        print(f"还没有保存 Key，到 {c.site_url}/me 创建后运行 gengwiki keys add 名字")
+    for k in rows:
+        print(f"{'*' if k.current else ' '} {k.name}  {k.prefix}  {k.persona_title or ''}".rstrip())
+
+
+def _keys_add(c: GengWiki, a) -> None:
+    print(f"已保存 {c.keys.add(a.name, getpass.getpass('粘贴 Key ').strip()).name}")
+
+
+def _keys_use(c: GengWiki, a) -> None:
+    print(f"已切换到 {c.keys.use(a.name).name}")
+
+
+def _keys_remove(c: GengWiki, a) -> None:
+    c.keys.remove(a.name)
+    print(f"已从本机删除 {a.name}，服务器上依然有效")
+
+
+def _keys_secret(c: GengWiki, a) -> None:
+    print(c.keys.secret(a.name))
+
+
+def _keys_remote(c: GengWiki, a) -> None:
+    for k in c.keys.list():
+        print(f"{k.name}  {k.prefix}  最后使用 {k.last_used_at or '从未'}")
+
+
+def _keys_rotate(c: GengWiki, a) -> None:
+    print(f"已换新密钥并保存到 {c.keys.rotate(a.name).name}，旧密钥立即失效")
+
+
+def _keys_revoke(c: GengWiki, a) -> None:
+    c.keys.revoke(a.name)
+    print(f"已吊销 {a.name}")
+
+
+def _personas(c: GengWiki, a) -> None:
+    rows = c.personas(a.q)
+    if not rows:
+        print("没有找到")
+    for p in rows:
+        print(f"{p.title}  {p.description}".rstrip())
+
+
+def _use(c: GengWiki, a) -> None:
+    print(f"已切换到 {c.use_persona(a.persona).title}")
+
+
+def _search(c: GengWiki, a) -> None:
+    _memes(c.search_memes(a.q))
+
+
+def _trending(c: GengWiki, a) -> None:
+    _memes(c.trending(a.tag))
+
+
+def _meme(c: GengWiki, a) -> None:
+    m = c.meme(a.slug)
+    print(m.title)
+    if m.aliases:
+        print("别名  " + "、".join(m.aliases))
+    print(f"\n{m.body or m.summary}")
+    if m.usage_scenario:
+        print(f"\n使用场景  {m.usage_scenario}")
+    for example in m.usage_examples:
+        print(f"\n  {example}")
+
+
+def _sync(c: GengWiki, a) -> None:
+    s = c.sync(images=a.images)
+    print(f"梗 {s['memes']} 个，表情 {s['stickers']} 个，图片 {s['images']} 张，发出 {s['requests']} 个请求")
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="gengwiki", description="梗Wiki 命令行")
+    parser.add_argument("--version", action="version", version=__version__)
+    parser.set_defaults(run=None)
+    sub = parser.add_subparsers(metavar="命令")
+
+    def command(parent, name, run, help_text, *args):
+        p = parent.add_parser(name, help=help_text)
+        p.set_defaults(run=run)
+        for arg, kwargs in args:
+            p.add_argument(arg, **kwargs)
+        return p
+
+    optional = {"nargs": "?", "default": ""}
+    command(sub, "status", _status, "当前站点、Key、人设和额度")
+    command(sub, "login", _login, "登录以管理 Key", ("email", optional))
+    command(sub, "logout", _logout, "退出登录")
+    command(sub, "search", _search, "搜索梗", ("q", optional))
+    command(sub, "meme", _meme, "查看一个梗", ("slug", {}))
+    command(sub, "trending", _trending, "热门榜", ("tag", optional))
+    command(sub, "personas", _personas, "浏览人设", ("q", optional))
+    command(sub, "use", _use, "切换人设", ("persona", {}))
+    command(sub, "sync", _sync, "下载全部内容供离线使用", ("--images", {"action": "store_true"}))
+
+    keys = command(sub, "keys", _keys_local, "列出已保存的 Key").add_subparsers(metavar="操作")
+    command(keys, "add", _keys_add, "保存在网站上创建的 Key", ("name", {}))
+    command(keys, "use", _keys_use, "切换到已保存的 Key", ("name", {}))
+    command(keys, "remove", _keys_remove, "只从本机删除", ("name", {}))
+    command(keys, "secret", _keys_secret, "输出密钥，交给别的程序", ("name", {}))
+    command(keys, "remote", _keys_remote, "列出账号上的 Key，需要登录")
+    command(keys, "rotate", _keys_rotate, "换新密钥，需要登录", ("name", {}))
+    command(keys, "revoke", _keys_revoke, "吊销并从本机删除，需要登录", ("name", {}))
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        if hasattr(stream, "reconfigure"):
+            # A pipe on a non-Chinese Windows is cp1252, which would turn all the text into question marks.
+            # On any encoding, one character it lacks must not end the program.
+            encoding = stream.encoding if "梗".encode(stream.encoding, "ignore") else "utf-8"
+            stream.reconfigure(encoding=encoding, errors="replace")
+    parser = _parser()
+    args = parser.parse_args(argv)
+    if args.run is None:
+        parser.print_help()
+        return 0
+    try:
+        with GengWiki() as client:
+            args.run(client, args)
+    except (GengWikiError, ValueError) as e:
+        print(f"错误  {getattr(e, 'message', e)}", file=sys.stderr)
+        return 1
+    except (KeyboardInterrupt, EOFError):
+        return 130
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

gengwiki-0.1.0/src/gengwiki/_http.py

@@ -0,0 +1,136 @@
+"""Stdlib HTTP with typed errors. Knows nothing about caching."""
+
+import email.message
+import gzip
+import http.client
+import ipaddress
+import json
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+import zlib
+
+from . import __version__
+from .errors import (
+    AuthError,
+    BadRequestError,
+    BadResponseError,
+    ConflictError,
+    ForbiddenError,
+    GengWikiError,
+    NetworkError,
+    NotFoundError,
+    RateLimitError,
+    ServerError,
+    UnavailableError,
+)
+
+_BY_STATUS = {400: BadRequestError, 401: AuthError, 403: ForbiddenError, 404: NotFoundError, 409: ConflictError}
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """urllib would forward the Authorization header to wherever a redirect points."""
+
+    def redirect_request(self, *args, **kwargs):
+        return None
+
+
+def check_url(url: str) -> str:
+    """Bearer tokens only travel over HTTPS, plain HTTP is for a dev server on this machine."""
+    parts = urllib.parse.urlsplit(url)
+    if parts.scheme == "https" and parts.hostname:
+        return url.rstrip("/")
+    if parts.scheme == "http" and parts.hostname:
+        try:
+            loopback = ipaddress.ip_address(parts.hostname).is_loopback
+        except ValueError:
+            loopback = parts.hostname == "localhost"
+        if loopback:
+            return url.rstrip("/")
+    raise ValueError(f"{url!r} must be https, or http on localhost")
+
+
+def _raise_for(status: int, body: bytes, headers: email.message.Message) -> None:
+    code, message = None, f"HTTP {status}"
+    try:
+        err = json.loads(body)["error"]
+        code, message = err["code"], err["message"]
+    except (ValueError, KeyError, TypeError):
+        pass
+    if status == 429:
+        try:
+            retry_after = float(headers.get("Retry-After", 0))
+        except ValueError:
+            retry_after = 0
+        raise RateLimitError(message, retry_after=retry_after)
+    if status >= 500:
+        raise ServerError(message, status, code)
+    raise _BY_STATUS.get(status, GengWikiError)(message, status, code)
+
+
+class Http:
+    def __init__(self, timeout: float = 15):
+        self.timeout = timeout
+        self.count = 0
+        self._opener = urllib.request.build_opener(_NoRedirect)
+
+    # ponytail: urllib opens one connection per request. Requests are rare by design, pool with http.client if that changes.
+    def _once(self, req: urllib.request.Request) -> tuple[bytes, email.message.Message]:
+        self.count += 1
+        try:
+            with self._opener.open(req, timeout=self.timeout) as res:
+                body, headers = res.read(), res.headers
+            if headers.get("Content-Encoding") == "gzip":
+                body = gzip.decompress(body)
+            return body, headers
+        except urllib.error.HTTPError as e:
+            with e:
+                _raise_for(e.code, e.read(), e.headers)
+            raise  # unreachable, _raise_for always raises
+        # A connection cut mid-response or a damaged body is the same outage to the caller.
+        except (OSError, EOFError, http.client.HTTPException, zlib.error) as e:
+            raise NetworkError(f"cannot reach {req.host}: {e!r}") from e
+
+    def request(
+        self,
+        method: str,
+        url: str,
+        *,
+        token: str | None = None,
+        params: dict | None = None,
+        body: dict | None = None,
+        retries: int = 0,
+    ) -> tuple[bytes, email.message.Message]:
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+        headers = {"User-Agent": f"gengwiki-python/{__version__}", "Accept-Encoding": "gzip"}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        data = None
+        if body is not None:
+            data = json.dumps(body).encode()
+            headers["Content-Type"] = "application/json"
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        for attempt in range(retries + 1):
+            try:
+                return self._once(req)
+            except UnavailableError as e:
+                # A long Retry-After is the daily limit, waiting it out would hang the caller.
+                wait = e.retry_after if isinstance(e, RateLimitError) else 0.5 * 2**attempt
+                if attempt == retries or wait > 5:
+                    raise
+                time.sleep(wait)
+        raise AssertionError("unreachable")
+
+    def json(self, method: str, url: str, *, expect: type | None = None, **kwargs):
+        """The decoded body. With expect, anything but that type is a bad response, so it never reaches the cache."""
+        body, headers = self.request(method, url, **kwargs)
+        try:
+            value = json.loads(body) if body else None
+        except ValueError as e:
+            raise BadResponseError(f"expected JSON from {url}, got {headers.get_content_type()}", code="bad_response") from e
+        # ponytail: checks the outer type, not each row. Check fields if something in front ever rewrites rows.
+        if expect and not isinstance(value, expect):
+            raise BadResponseError(f"expected a JSON {expect.__name__} from {url}", code="bad_response")
+        return value