clientx 0.1.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.
- clientx/__init__.py +39 -0
- clientx/_arguments.py +65 -0
- clientx/_builder.py +429 -0
- clientx/_class_setup.py +252 -0
- clientx/_client.py +300 -0
- clientx/_decoding.py +240 -0
- clientx/_endpoint.py +276 -0
- clientx/_method.py +198 -0
- clientx/_planner.py +1281 -0
- clientx/_registry.py +32 -0
- clientx/_signature.py +312 -0
- clientx/_tools.py +440 -0
- clientx/_types.py +313 -0
- clientx/_version.py +5 -0
- clientx/arguments.py +60 -0
- clientx/exceptions.py +61 -0
- clientx/method.py +16 -0
- clientx/py.typed +0 -0
- clientx/tools.py +23 -0
- clientx-0.1.0.dist-info/METADATA +176 -0
- clientx-0.1.0.dist-info/RECORD +23 -0
- clientx-0.1.0.dist-info/WHEEL +4 -0
- clientx-0.1.0.dist-info/licenses/LICENSE +21 -0
clientx/_tools.py
ADDED
|
@@ -0,0 +1,440 @@
|
|
|
1
|
+
"""Describe a client's endpoints as tools a model can call.
|
|
2
|
+
|
|
3
|
+
``list_tools(client)`` returns one ``Tool`` per endpoint on the client and the
|
|
4
|
+
resources mounted on it: a name, a description, a JSON Schema of its arguments
|
|
5
|
+
and of its result, hints from its HTTP method, its tags, and ``call()`` or
|
|
6
|
+
``acall()``.
|
|
7
|
+
Nothing here depends on an AI library, so an adapter for MCP or another
|
|
8
|
+
framework can build on it.
|
|
9
|
+
|
|
10
|
+
- Names: the attribute path from the client, joined with ``_``, so
|
|
11
|
+
``api.users.create`` is ``users_create``. An endpoint's second name in its
|
|
12
|
+
class is left out: it's the same endpoint.
|
|
13
|
+
- Left out: an endpoint that streams (``-> Iterator[...]`` or
|
|
14
|
+
``stream=True``), returns the raw ``Response``, or has an argument with no
|
|
15
|
+
JSON form, such as a binary file. A model can't use them well.
|
|
16
|
+
- Descriptions: the docstring, up to its first section (``Args:``,
|
|
17
|
+
``Returns:``...), or else the method and path. An argument's description is
|
|
18
|
+
its helper's ``description=``, or else its entry in the docstring's
|
|
19
|
+
``Args:``.
|
|
20
|
+
- Schemas: arguments are named as in the method, not by their helpers'
|
|
21
|
+
aliases. Pydantic's ``title`` on each property is left out, and a model or
|
|
22
|
+
``type`` alias is written in place rather than behind a ``$ref``, unless it
|
|
23
|
+
refers to itself.
|
|
24
|
+
- Calls: a model's arguments are validated as Pydantic validates a call,
|
|
25
|
+
leniently, so ``"7"`` fits an ``int``. Only the arguments the model gave are
|
|
26
|
+
passed, so a default stays a default, as ``Send(exclude_unset=True)`` and a
|
|
27
|
+
JSON field's ``None`` need. The result is JSON-ready data.
|
|
28
|
+
- Errors: a failed call raises ``ToolError``, with a message written for a
|
|
29
|
+
model and the original error as its cause. HTTP errors name the method and
|
|
30
|
+
path template, never the host or query string, which can hold credentials.
|
|
31
|
+
"""
|
|
32
|
+
|
|
33
|
+
from __future__ import annotations
|
|
34
|
+
|
|
35
|
+
import inspect
|
|
36
|
+
import re
|
|
37
|
+
from collections.abc import Callable, Generator, Mapping, Sequence
|
|
38
|
+
from contextlib import contextmanager
|
|
39
|
+
from dataclasses import dataclass, field
|
|
40
|
+
from types import NoneType
|
|
41
|
+
from typing import TYPE_CHECKING, Any, cast
|
|
42
|
+
|
|
43
|
+
import httpx2
|
|
44
|
+
from pydantic import ConfigDict, PydanticSchemaGenerationError, TypeAdapter, ValidationError
|
|
45
|
+
from pydantic.errors import PydanticInvalidForJsonSchema
|
|
46
|
+
|
|
47
|
+
from clientx._registry import endpoint_for
|
|
48
|
+
from clientx.exceptions import ArgumentError, ToolError
|
|
49
|
+
|
|
50
|
+
if TYPE_CHECKING:
|
|
51
|
+
from clientx._client import AsyncClientX, ClientX
|
|
52
|
+
from clientx._endpoint import Endpoint
|
|
53
|
+
from clientx._signature import ParameterInfo
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
# --- Entry point --------------------------------------------------------------
|
|
57
|
+
def list_tools(client: ClientX | AsyncClientX) -> list[Tool]:
|
|
58
|
+
"""Return a tool for each endpoint a model can call, resources' included.
|
|
59
|
+
|
|
60
|
+
Every endpoint on the client and the resources mounted on it is a tool,
|
|
61
|
+
named by its attribute path (``users_create``), except one a model can't
|
|
62
|
+
use well:
|
|
63
|
+
|
|
64
|
+
- one that streams, annotated ``-> Iterator[...]`` or with
|
|
65
|
+
``stream=True``;
|
|
66
|
+
- one that returns the raw ``Response``: annotate what the API returns
|
|
67
|
+
instead, such as a model or ``dict[str, Any]``;
|
|
68
|
+
- one with an argument that has no JSON form, such as a binary file.
|
|
69
|
+
|
|
70
|
+
An endpoint's second name in its class is listed once.
|
|
71
|
+
"""
|
|
72
|
+
tools: list[Tool] = []
|
|
73
|
+
_collect(client, "", tools, set())
|
|
74
|
+
return tools
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def _collect(owner: object, prefix: str, tools: list[Tool], seen: set[int]) -> None:
|
|
78
|
+
"""Add a tool for each endpoint on ``owner``, then on its resources.
|
|
79
|
+
|
|
80
|
+
``seen`` holds each endpoint met so far, by ``id``, so an endpoint's second
|
|
81
|
+
name is left out.
|
|
82
|
+
"""
|
|
83
|
+
for name, value in _members(type(owner)).items():
|
|
84
|
+
endpoint = endpoint_for(value)
|
|
85
|
+
if endpoint is not None and id(endpoint) not in seen:
|
|
86
|
+
seen.add(id(endpoint))
|
|
87
|
+
tool = _tool(prefix + name, endpoint, getattr(owner, name))
|
|
88
|
+
if tool is not None:
|
|
89
|
+
tools.append(tool)
|
|
90
|
+
elif hasattr(type(value), "__clientx_prefix__"): # A mounted resource.
|
|
91
|
+
_collect(getattr(owner, name), f"{prefix}{name}_", tools, seen)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def _members(cls: type) -> dict[str, object]:
|
|
95
|
+
"""Return the attributes ``cls`` and its parents define, in class order."""
|
|
96
|
+
members: dict[str, object] = {}
|
|
97
|
+
for class_ in reversed(cls.__mro__):
|
|
98
|
+
members.update(vars(class_))
|
|
99
|
+
return members
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
# --- Tools --------------------------------------------------------------------
|
|
103
|
+
@dataclass(frozen=True, kw_only=True)
|
|
104
|
+
class Tool:
|
|
105
|
+
"""An endpoint described for a model, and called with a model's arguments.
|
|
106
|
+
|
|
107
|
+
Attributes:
|
|
108
|
+
name: The attribute path from the client, joined with ``_``.
|
|
109
|
+
description: What the endpoint does, from its docstring.
|
|
110
|
+
input_schema: The JSON Schema of the arguments: an object with one
|
|
111
|
+
property per parameter, named as in the method.
|
|
112
|
+
output_schema: The JSON Schema of the result, or ``None`` for an
|
|
113
|
+
endpoint annotated ``-> None``.
|
|
114
|
+
read_only: The endpoint only reads: ``GET``, ``HEAD`` or ``OPTIONS``.
|
|
115
|
+
destructive: It can change or delete what's there: ``PUT``,
|
|
116
|
+
``PATCH`` or ``DELETE``.
|
|
117
|
+
idempotent: Calling it twice has the effect of calling it once:
|
|
118
|
+
``GET``, ``HEAD``, ``OPTIONS``, ``PUT`` or ``DELETE``.
|
|
119
|
+
tags: The endpoint's tags, its resource's first, to choose which tools
|
|
120
|
+
to register by.
|
|
121
|
+
is_async: It's an ``async def`` endpoint, called with ``acall()``.
|
|
122
|
+
"""
|
|
123
|
+
|
|
124
|
+
name: str
|
|
125
|
+
description: str
|
|
126
|
+
input_schema: dict[str, Any]
|
|
127
|
+
output_schema: dict[str, Any] | None
|
|
128
|
+
read_only: bool
|
|
129
|
+
destructive: bool
|
|
130
|
+
idempotent: bool
|
|
131
|
+
tags: tuple[str, ...]
|
|
132
|
+
is_async: bool
|
|
133
|
+
_call: _Call = field(repr=False, compare=False)
|
|
134
|
+
|
|
135
|
+
def call(self, arguments: Mapping[str, Any] | None = None) -> Any:
|
|
136
|
+
"""Call the endpoint with a model's arguments; return JSON-ready data.
|
|
137
|
+
|
|
138
|
+
Raises:
|
|
139
|
+
ToolError: If the arguments don't fit, the request can't be sent or
|
|
140
|
+
fails, or the response doesn't fit the endpoint's annotation.
|
|
141
|
+
TypeError: If the endpoint is ``async def``: use ``acall()``.
|
|
142
|
+
"""
|
|
143
|
+
if self.is_async:
|
|
144
|
+
raise TypeError(f"Tool {self.name!r} is an async def endpoint: call it with acall().")
|
|
145
|
+
args, kwargs = self._call.arguments(self.name, arguments)
|
|
146
|
+
with self._call.errors(self.name):
|
|
147
|
+
result = self._call.function(*args, **kwargs)
|
|
148
|
+
return self._call.dump(result)
|
|
149
|
+
|
|
150
|
+
async def acall(self, arguments: Mapping[str, Any] | None = None) -> Any:
|
|
151
|
+
"""Call the ``async def`` endpoint with a model's arguments.
|
|
152
|
+
|
|
153
|
+
Raises:
|
|
154
|
+
ToolError: As for ``call()``.
|
|
155
|
+
TypeError: If the endpoint is a plain ``def``: use ``call()``.
|
|
156
|
+
"""
|
|
157
|
+
if not self.is_async:
|
|
158
|
+
raise TypeError(f"Tool {self.name!r} is a def endpoint: call it with call().")
|
|
159
|
+
args, kwargs = self._call.arguments(self.name, arguments)
|
|
160
|
+
with self._call.errors(self.name):
|
|
161
|
+
result = await self._call.function(*args, **kwargs)
|
|
162
|
+
return self._call.dump(result)
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
@dataclass(frozen=True)
|
|
166
|
+
class _Call:
|
|
167
|
+
"""What a tool needs to call its endpoint and report on it."""
|
|
168
|
+
|
|
169
|
+
function: Callable[..., Any]
|
|
170
|
+
adapter: TypeAdapter[dict[str, Any]]
|
|
171
|
+
output: TypeAdapter[Any] | None
|
|
172
|
+
positional: tuple[ParameterInfo, ...]
|
|
173
|
+
request: str # The method and path template, for messages: "POST /users".
|
|
174
|
+
|
|
175
|
+
def arguments(self, name: str, arguments: Mapping[str, Any] | None) -> tuple[list[Any], dict[str, Any]]:
|
|
176
|
+
"""Return the validated arguments the model gave, to call with.
|
|
177
|
+
|
|
178
|
+
A positional-only parameter is passed by position, so one the model
|
|
179
|
+
left out before one it gave gets its default.
|
|
180
|
+
|
|
181
|
+
Raises:
|
|
182
|
+
ToolError: If the arguments don't fit the endpoint's parameters.
|
|
183
|
+
"""
|
|
184
|
+
given = dict(arguments or {})
|
|
185
|
+
try:
|
|
186
|
+
validated = self.adapter.validate_python(given)
|
|
187
|
+
except ValidationError as error:
|
|
188
|
+
raise ToolError(
|
|
189
|
+
f"The arguments don't fit {name}: {_problems(error, values=True)}. Nothing was sent.", tool=name
|
|
190
|
+
) from error
|
|
191
|
+
last = max((index for index, parameter in enumerate(self.positional) if parameter.name in given), default=-1)
|
|
192
|
+
args = [validated.get(parameter.name, parameter.default) for parameter in self.positional[: last + 1]]
|
|
193
|
+
positional_names = {parameter.name for parameter in self.positional}
|
|
194
|
+
kwargs = {key: value for key, value in validated.items() if key in given and key not in positional_names}
|
|
195
|
+
return args, kwargs
|
|
196
|
+
|
|
197
|
+
@contextmanager
|
|
198
|
+
def errors(self, name: str) -> Generator[None]:
|
|
199
|
+
"""Raise ``ToolError`` for what can go wrong in a call, with its cause.
|
|
200
|
+
|
|
201
|
+
An HTTP error shows the API's own answer, truncated, as it often says
|
|
202
|
+
what to fix.
|
|
203
|
+
"""
|
|
204
|
+
try:
|
|
205
|
+
yield
|
|
206
|
+
except ArgumentError as error:
|
|
207
|
+
raise ToolError(f"{name} couldn't send its request: {error}", tool=name) from error
|
|
208
|
+
except httpx2.HTTPStatusError as error:
|
|
209
|
+
response = error.response
|
|
210
|
+
message = f"{name}: the API answered {response.status_code} {response.reason_phrase} to {self.request}"
|
|
211
|
+
body = response.text.strip()
|
|
212
|
+
raise ToolError(f"{message}: {_truncated(body)}" if body else f"{message}.", tool=name) from error
|
|
213
|
+
except httpx2.RequestError as error:
|
|
214
|
+
raise ToolError(
|
|
215
|
+
f"{name}: the request to {self.request} failed before the API answered ({type(error).__name__}).",
|
|
216
|
+
tool=name,
|
|
217
|
+
) from error
|
|
218
|
+
except ValidationError as error:
|
|
219
|
+
raise ToolError(
|
|
220
|
+
f"{name}: the API's answer to {self.request} doesn't fit the endpoint's return annotation: "
|
|
221
|
+
f"{_problems(error, values=False)}.",
|
|
222
|
+
tool=name,
|
|
223
|
+
) from error
|
|
224
|
+
|
|
225
|
+
def dump(self, result: Any) -> Any:
|
|
226
|
+
"""Return the endpoint's result as JSON-ready data."""
|
|
227
|
+
return None if self.output is None else self.output.dump_python(result, mode="json")
|
|
228
|
+
|
|
229
|
+
|
|
230
|
+
# --- Building a tool ----------------------------------------------------------
|
|
231
|
+
# What each HTTP method implies, for the hints. POST is in none of them: it
|
|
232
|
+
# usually adds something, so it's neither read-only nor idempotent, and not
|
|
233
|
+
# destructive either, which is for replacing or removing what's there.
|
|
234
|
+
_READ_ONLY = frozenset({"GET", "HEAD", "OPTIONS"})
|
|
235
|
+
_IDEMPOTENT = frozenset({"GET", "HEAD", "OPTIONS", "PUT", "DELETE"})
|
|
236
|
+
_DESTRUCTIVE = frozenset({"PUT", "PATCH", "DELETE"})
|
|
237
|
+
|
|
238
|
+
|
|
239
|
+
def _tool(name: str, endpoint: Endpoint, function: Callable[..., Any]) -> Tool | None:
|
|
240
|
+
"""Return the tool for an endpoint, or ``None`` if a model can't use it."""
|
|
241
|
+
returns = endpoint.signature.returns
|
|
242
|
+
if endpoint.stream or returns.base_type is httpx2.Response:
|
|
243
|
+
return None
|
|
244
|
+
parameters = endpoint.signature.parameters[1:]
|
|
245
|
+
try:
|
|
246
|
+
adapter = _arguments_adapter(parameters)
|
|
247
|
+
input_schema = _compact(adapter.json_schema(by_alias=False))
|
|
248
|
+
returns_nothing = returns.base_type is None or returns.base_type is NoneType
|
|
249
|
+
output = None if returns_nothing else TypeAdapter[Any](returns.annotation)
|
|
250
|
+
output_schema = None if output is None else _compact(output.json_schema(mode="serialization"))
|
|
251
|
+
except (PydanticSchemaGenerationError, PydanticInvalidForJsonSchema):
|
|
252
|
+
return None
|
|
253
|
+
doc = inspect.cleandoc(endpoint.signature.doc or "")
|
|
254
|
+
argument_docs = _argument_docs(doc)
|
|
255
|
+
for parameter_name, schema in input_schema.get("properties", {}).items():
|
|
256
|
+
if "description" not in schema and parameter_name in argument_docs:
|
|
257
|
+
schema["description"] = argument_docs[parameter_name]
|
|
258
|
+
request = f"{endpoint.method} {endpoint.raw_path or '/'}"
|
|
259
|
+
positional = tuple(p for p in parameters if p.kind is inspect.Parameter.POSITIONAL_ONLY)
|
|
260
|
+
return Tool(
|
|
261
|
+
name=name,
|
|
262
|
+
description=_description(doc) or request,
|
|
263
|
+
input_schema=input_schema,
|
|
264
|
+
output_schema=output_schema,
|
|
265
|
+
read_only=endpoint.method in _READ_ONLY,
|
|
266
|
+
destructive=endpoint.method in _DESTRUCTIVE,
|
|
267
|
+
idempotent=endpoint.method in _IDEMPOTENT,
|
|
268
|
+
tags=tuple(endpoint.tags),
|
|
269
|
+
is_async=endpoint.signature.is_async,
|
|
270
|
+
_call=_Call(function, adapter, output, positional, request),
|
|
271
|
+
)
|
|
272
|
+
|
|
273
|
+
|
|
274
|
+
# Validates arguments by parameter name: a helper's alias is the name sent to
|
|
275
|
+
# the API, not the one a caller uses.
|
|
276
|
+
_BY_NAME = ConfigDict(validate_by_name=True, validate_by_alias=False)
|
|
277
|
+
|
|
278
|
+
|
|
279
|
+
def _arguments_adapter(parameters: Sequence[ParameterInfo]) -> TypeAdapter[dict[str, Any]]:
|
|
280
|
+
"""Return a validator of a model's arguments for these parameters.
|
|
281
|
+
|
|
282
|
+
It validates a call to a stand-in with the endpoint's parameters, all
|
|
283
|
+
keyword-only so a mapping fills them, and returns the arguments: the
|
|
284
|
+
endpoint is called separately, so a response that doesn't fit isn't taken
|
|
285
|
+
for arguments that don't.
|
|
286
|
+
"""
|
|
287
|
+
|
|
288
|
+
def arguments(**values: Any) -> dict[str, Any]:
|
|
289
|
+
return values
|
|
290
|
+
|
|
291
|
+
arguments.__signature__ = inspect.Signature( # pyright: ignore[reportFunctionMemberAccess]
|
|
292
|
+
[
|
|
293
|
+
inspect.Parameter(p.name, inspect.Parameter.KEYWORD_ONLY, default=p.default, annotation=p.annotation)
|
|
294
|
+
for p in parameters
|
|
295
|
+
]
|
|
296
|
+
)
|
|
297
|
+
arguments.__annotations__ = {p.name: p.annotation for p in parameters}
|
|
298
|
+
# Pydantic validates a call to a function, which its types don't allow.
|
|
299
|
+
return TypeAdapter[dict[str, Any]](cast("Any", arguments), config=_BY_NAME)
|
|
300
|
+
|
|
301
|
+
|
|
302
|
+
# --- Error messages -----------------------------------------------------------
|
|
303
|
+
# How much of an error response's body a message shows.
|
|
304
|
+
_BODY_LIMIT = 2000
|
|
305
|
+
|
|
306
|
+
|
|
307
|
+
def _truncated(text: str) -> str:
|
|
308
|
+
if len(text) <= _BODY_LIMIT:
|
|
309
|
+
return text
|
|
310
|
+
return f"{text[:_BODY_LIMIT]}... ({len(text) - _BODY_LIMIT} more characters)"
|
|
311
|
+
|
|
312
|
+
|
|
313
|
+
def _problems(error: ValidationError, *, values: bool) -> str:
|
|
314
|
+
"""Return each of Pydantic's errors as ``where: what``, without its URL.
|
|
315
|
+
|
|
316
|
+
With ``values``, a value that's there but doesn't fit is shown too, short:
|
|
317
|
+
it's the model's own argument. A response's values aren't.
|
|
318
|
+
"""
|
|
319
|
+
problems: list[str] = []
|
|
320
|
+
for problem in error.errors(include_url=False, include_context=False):
|
|
321
|
+
where = ".".join(str(part) for part in problem["loc"]) or "the arguments"
|
|
322
|
+
# A missing argument is reported as keyword-only, as the stand-in's are.
|
|
323
|
+
if problem["type"].startswith("missing"):
|
|
324
|
+
problems.append(f"{where}: is required")
|
|
325
|
+
continue
|
|
326
|
+
text = f"{where}: {problem['msg']}"
|
|
327
|
+
if values:
|
|
328
|
+
text += f" (got {problem['input']!r:.80})"
|
|
329
|
+
problems.append(text)
|
|
330
|
+
return "; ".join(problems)
|
|
331
|
+
|
|
332
|
+
|
|
333
|
+
# --- Descriptions -------------------------------------------------------------
|
|
334
|
+
# A Google-style section header, which ends a docstring's description.
|
|
335
|
+
_SECTION = re.compile(
|
|
336
|
+
r"(Args|Arguments|Attributes|Example|Examples|Note|Notes|Raises|Returns|See Also|Warning|Warnings|Yields):"
|
|
337
|
+
)
|
|
338
|
+
# An argument's entry in ``Args:``: "name: text", or "name (type): text".
|
|
339
|
+
_ENTRY = re.compile(r"\*{0,2}(?P<name>\w+)(?:\s*\([^)]*\))?:\s*(?P<text>.*)")
|
|
340
|
+
|
|
341
|
+
|
|
342
|
+
def _description(doc: str) -> str:
|
|
343
|
+
"""Return a docstring up to its first section, such as ``Args:``."""
|
|
344
|
+
lines = doc.splitlines()
|
|
345
|
+
end = next((index for index, line in enumerate(lines) if _SECTION.fullmatch(line.strip())), len(lines))
|
|
346
|
+
return "\n".join(lines[:end]).strip()
|
|
347
|
+
|
|
348
|
+
|
|
349
|
+
def _argument_docs(doc: str) -> dict[str, str]:
|
|
350
|
+
"""Return each argument's description from a docstring's ``Args:``.
|
|
351
|
+
|
|
352
|
+
An entry's continuation lines, indented further, are joined to it.
|
|
353
|
+
"""
|
|
354
|
+
lines = doc.splitlines()
|
|
355
|
+
start = next((index + 1 for index, line in enumerate(lines) if line.strip() in {"Args:", "Arguments:"}), None)
|
|
356
|
+
if start is None:
|
|
357
|
+
return {}
|
|
358
|
+
docs: dict[str, str] = {}
|
|
359
|
+
entry_indent: int | None = None
|
|
360
|
+
current: str | None = None
|
|
361
|
+
for line in lines[start:]:
|
|
362
|
+
if not line.strip():
|
|
363
|
+
continue
|
|
364
|
+
indent = len(line) - len(line.lstrip())
|
|
365
|
+
if indent == 0:
|
|
366
|
+
break
|
|
367
|
+
entry_indent = indent if entry_indent is None else entry_indent
|
|
368
|
+
if indent == entry_indent:
|
|
369
|
+
match = _ENTRY.fullmatch(line.strip())
|
|
370
|
+
if match is None:
|
|
371
|
+
current = None
|
|
372
|
+
continue
|
|
373
|
+
name: str = match["name"]
|
|
374
|
+
docs[name], current = match["text"], name
|
|
375
|
+
elif current is not None:
|
|
376
|
+
docs[current] = f"{docs[current]} {line.strip()}".strip()
|
|
377
|
+
return docs
|
|
378
|
+
|
|
379
|
+
|
|
380
|
+
# --- Compact schemas ----------------------------------------------------------
|
|
381
|
+
# Keys whose value maps names to schemas, not a schema itself.
|
|
382
|
+
_SCHEMA_MAPS = frozenset({"$defs", "patternProperties", "properties"})
|
|
383
|
+
# Keys whose value is data, not a schema, so it's kept as it is.
|
|
384
|
+
_DATA = frozenset({"const", "default", "enum", "examples"})
|
|
385
|
+
|
|
386
|
+
|
|
387
|
+
def _compact(schema: dict[str, Any]) -> dict[str, Any]:
|
|
388
|
+
"""Return a JSON Schema without titles, with each ``$ref`` written in place.
|
|
389
|
+
|
|
390
|
+
A definition that refers to itself, directly or not, can't be written in
|
|
391
|
+
place, so it stays in ``$defs``, and so do the references to it.
|
|
392
|
+
"""
|
|
393
|
+
definitions: dict[str, Any] = schema.get("$defs", {})
|
|
394
|
+
kept: dict[str, Any] = {}
|
|
395
|
+
compact = _inline({k: v for k, v in schema.items() if k != "$defs"}, definitions, frozenset(), kept)
|
|
396
|
+
pending = [name for name in kept if kept[name] is None]
|
|
397
|
+
while pending:
|
|
398
|
+
for name in pending:
|
|
399
|
+
kept[name] = _inline(definitions[name], definitions, frozenset({name}), kept)
|
|
400
|
+
pending = [name for name in kept if kept[name] is None]
|
|
401
|
+
if kept:
|
|
402
|
+
compact["$defs"] = kept
|
|
403
|
+
return compact
|
|
404
|
+
|
|
405
|
+
|
|
406
|
+
def _inline(node: Any, definitions: dict[str, Any], stack: frozenset[str], kept: dict[str, Any]) -> Any:
|
|
407
|
+
"""Return ``node`` with titles left out and references written in place.
|
|
408
|
+
|
|
409
|
+
``stack`` holds the definitions being written in place around ``node``: a
|
|
410
|
+
reference to one of them is kept, and its name added to ``kept``.
|
|
411
|
+
"""
|
|
412
|
+
if isinstance(node, list):
|
|
413
|
+
return [_inline(item, definitions, stack, kept) for item in node] # pyright: ignore[reportUnknownVariableType]
|
|
414
|
+
if not isinstance(node, dict):
|
|
415
|
+
return node
|
|
416
|
+
reference = node.get("$ref") # pyright: ignore[reportUnknownMemberType, reportUnknownVariableType]
|
|
417
|
+
if isinstance(reference, str) and reference.startswith("#/$defs/"):
|
|
418
|
+
name = reference.removeprefix("#/$defs/")
|
|
419
|
+
others = {k: v for k, v in node.items() if k != "$ref"} # pyright: ignore[reportUnknownVariableType]
|
|
420
|
+
if name in stack:
|
|
421
|
+
kept.setdefault(name, None)
|
|
422
|
+
return {"$ref": reference, **_inline(others, definitions, stack, kept)}
|
|
423
|
+
return {
|
|
424
|
+
**_inline(definitions[name], definitions, stack | {name}, kept),
|
|
425
|
+
**_inline(others, definitions, stack, kept),
|
|
426
|
+
}
|
|
427
|
+
compact: dict[str, Any] = {}
|
|
428
|
+
for key, value in node.items(): # pyright: ignore[reportUnknownVariableType]
|
|
429
|
+
if key == "title":
|
|
430
|
+
continue
|
|
431
|
+
if key in _DATA:
|
|
432
|
+
compact[key] = value
|
|
433
|
+
elif key in _SCHEMA_MAPS and isinstance(value, dict):
|
|
434
|
+
compact[key] = {
|
|
435
|
+
sub_name: _inline(sub, definitions, stack, kept)
|
|
436
|
+
for sub_name, sub in value.items() # pyright: ignore[reportUnknownVariableType]
|
|
437
|
+
}
|
|
438
|
+
else:
|
|
439
|
+
compact[key] = _inline(value, definitions, stack, kept)
|
|
440
|
+
return compact
|