schemez 2.2.29__tar.gz → 2.2.30__tar.gz

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.
Files changed (47) hide show
  1. schemez-2.2.30/PKG-INFO +280 -0
  2. schemez-2.2.30/README.md +226 -0
  3. schemez-2.2.30/pyproject.toml +318 -0
  4. schemez-2.2.29/pyproject.toml → schemez-2.2.30/pyproject.toml.orig +28 -16
  5. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/code_generation/route_helpers.py +6 -8
  6. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/code_generation/tool_code_generator.py +2 -2
  7. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/commented_yaml.py +4 -4
  8. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/convert.py +7 -8
  9. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/docstrings.py +3 -3
  10. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/functionschema/__init__.py +0 -1
  11. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/functionschema/executable.py +19 -15
  12. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/functionschema/functionschema.py +15 -13
  13. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/functionschema/helpers.py +1 -1
  14. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/functionschema/typedefs.py +1 -1
  15. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/generators.py +8 -8
  16. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/helpers.py +4 -4
  17. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/markdown.py +2 -2
  18. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/openapi/callable_factory.py +2 -2
  19. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/openapi/resolver.py +3 -3
  20. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/schema.py +10 -6
  21. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/schema_to_type/main_impl.py +2 -2
  22. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/schema_to_type/marvin_impl.py +16 -16
  23. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/schema_to_type/simple_impl.py +9 -11
  24. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/schemadef/schemadef.py +8 -11
  25. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/storage/model_store.py +5 -3
  26. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/tool_executor/executor.py +5 -4
  27. schemez-2.2.29/PKG-INFO +0 -496
  28. schemez-2.2.29/README.md +0 -448
  29. {schemez-2.2.29 → schemez-2.2.30}/LICENSE +0 -0
  30. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/__init__.py +0 -0
  31. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/bind_kwargs.py +0 -0
  32. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/code.py +0 -0
  33. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/code_generation/__init__.py +0 -0
  34. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/code_generation/namespace_callable.py +0 -0
  35. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/code_generation/toolset_code_generator.py +0 -0
  36. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/functionschema/schema_generators.py +0 -0
  37. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/log.py +0 -0
  38. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/openapi/__init__.py +0 -0
  39. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/openapi/loader.py +0 -0
  40. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/py.typed +0 -0
  41. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/pydantic_types.py +0 -0
  42. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/schema_to_type/__init__.py +0 -0
  43. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/schemadef/__init__.py +0 -0
  44. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/storage/__init__.py +0 -0
  45. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/tool_executor/__init__.py +0 -0
  46. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/tool_executor/helpers.py +0 -0
  47. {schemez-2.2.29 → schemez-2.2.30}/src/schemez/tool_executor/types.py +0 -0
@@ -0,0 +1,280 @@
1
+ Metadata-Version: 2.4
2
+ Name: schemez
3
+ Version: 2.2.30
4
+ Summary: Pydantic toolkit for function schemas, JSON Schema to model conversion, tool code generation and config models
5
+ Keywords: code-generation,configuration,data-models,function-calling,json-schema,llm,openai,pydantic,schema,serialization,tool-use,type-hints,validation,yaml
6
+ Author: Philipp Temminghoff
7
+ Author-email: Philipp Temminghoff <philipptemminghoff@googlemail.com>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Framework :: Pydantic
12
+ Classifier: Framework :: Pydantic :: 2
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Topic :: Software Development
20
+ Classifier: Topic :: Software Development :: Code Generators
21
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
22
+ Classifier: Topic :: Utilities
23
+ Classifier: Typing :: Typed
24
+ Requires-Dist: docstring-parser>=0.17.0
25
+ Requires-Dist: griffelib
26
+ Requires-Dist: pydantic
27
+ Requires-Dist: pydantic-core
28
+ Requires-Dist: typing-extensions>=4.12.0
29
+ Requires-Dist: universal-pathlib>=0.2.6
30
+ Requires-Dist: agentpool ; extra == 'ai'
31
+ Requires-Dist: anyenv>=0.4.14 ; extra == 'ai'
32
+ Requires-Dist: httpx>=0.27.0 ; extra == 'ai'
33
+ Requires-Dist: pydantic-ai-slim>=1.0.0 ; extra == 'ai'
34
+ Requires-Dist: datamodel-code-generator[ruff] ; extra == 'codegen'
35
+ Requires-Dist: jinja2>=3.1.0 ; extra == 'markdown'
36
+ Requires-Dist: aiosqlite>=0.20.0 ; extra == 'storage'
37
+ Requires-Dist: fastapi>=0.118.2 ; extra == 'tool-execution'
38
+ Requires-Dist: uvicorn>=0.30.0 ; extra == 'tool-execution'
39
+ Requires-Dist: yamling ; extra == 'yaml'
40
+ Requires-Python: >=3.13
41
+ Project-URL: Code coverage, https://app.codecov.io/gh/phil65/schemez
42
+ Project-URL: Discussions, https://github.com/phil65/schemez/discussions
43
+ Project-URL: Documentation, https://phil65.github.io/schemez/
44
+ Project-URL: Homepage, https://github.com/phil65/schemez
45
+ Project-URL: Issues, https://github.com/phil65/schemez/issues
46
+ Project-URL: Source, https://github.com/phil65/schemez
47
+ Provides-Extra: ai
48
+ Provides-Extra: codegen
49
+ Provides-Extra: markdown
50
+ Provides-Extra: storage
51
+ Provides-Extra: tool-execution
52
+ Provides-Extra: yaml
53
+ Description-Content-Type: text/markdown
54
+
55
+ # Schemez
56
+
57
+ [![PyPI License](https://img.shields.io/pypi/l/schemez.svg)](https://pypi.org/project/schemez/)
58
+ [![Package status](https://img.shields.io/pypi/status/schemez.svg)](https://pypi.org/project/schemez/)
59
+ [![Monthly downloads](https://img.shields.io/pypi/dm/schemez.svg)](https://pypi.org/project/schemez/)
60
+ [![Distribution format](https://img.shields.io/pypi/format/schemez.svg)](https://pypi.org/project/schemez/)
61
+ [![Wheel availability](https://img.shields.io/pypi/wheel/schemez.svg)](https://pypi.org/project/schemez/)
62
+ [![Python version](https://img.shields.io/pypi/pyversions/schemez.svg)](https://pypi.org/project/schemez/)
63
+ [![Implementation](https://img.shields.io/pypi/implementation/schemez.svg)](https://pypi.org/project/schemez/)
64
+ [![Releases](https://img.shields.io/github/downloads/phil65/schemez/total.svg)](https://github.com/phil65/schemez/releases)
65
+ [![Github Contributors](https://img.shields.io/github/contributors/phil65/schemez)](https://github.com/phil65/schemez/graphs/contributors)
66
+ [![Github Discussions](https://img.shields.io/github/discussions/phil65/schemez)](https://github.com/phil65/schemez/discussions)
67
+ [![Github Forks](https://img.shields.io/github/forks/phil65/schemez)](https://github.com/phil65/schemez/forks)
68
+ [![Github Issues](https://img.shields.io/github/issues/phil65/schemez)](https://github.com/phil65/schemez/issues)
69
+ [![Github Issues](https://img.shields.io/github/issues-pr/phil65/schemez)](https://github.com/phil65/schemez/pulls)
70
+ [![Github Watchers](https://img.shields.io/github/watchers/phil65/schemez)](https://github.com/phil65/schemez/watchers)
71
+ [![Github Stars](https://img.shields.io/github/stars/phil65/schemez)](https://github.com/phil65/schemez/stars)
72
+ [![Github Repository size](https://img.shields.io/github/repo-size/phil65/schemez)](https://github.com/phil65/schemez)
73
+ [![Github last commit](https://img.shields.io/github/last-commit/phil65/schemez)](https://github.com/phil65/schemez/commits)
74
+ [![Github release date](https://img.shields.io/github/release-date/phil65/schemez)](https://github.com/phil65/schemez/releases)
75
+ [![Github language count](https://img.shields.io/github/languages/count/phil65/schemez)](https://github.com/phil65/schemez)
76
+ [![Github commits this month](https://img.shields.io/github/commit-activity/m/phil65/schemez)](https://github.com/phil65/schemez)
77
+ [![Package status](https://codecov.io/gh/phil65/schemez/branch/main/graph/badge.svg)](https://codecov.io/gh/phil65/schemez/)
78
+ [![PyUp](https://pyup.io/repos/github/phil65/schemez/shield.svg)](https://pyup.io/repos/github/phil65/schemez/)
79
+
80
+ [Read the documentation!](https://phil65.github.io/schemez/)
81
+
82
+ Schemez is a Pydantic toolkit for turning Python code into schemas and schemas into code.
83
+ It builds OpenAI-compatible tool schemas from function signatures, creates Pydantic models
84
+ from JSON Schema, generates HTTP/MCP client code and FastAPI routes for tools, and gives your
85
+ config models YAML, markdown and test-data helpers.
86
+
87
+ ## Installation
88
+
89
+ ```bash
90
+ pip install schemez
91
+ ```
92
+
93
+ Optional extras enable individual features:
94
+
95
+ | Extra | Enables |
96
+ | --- | --- |
97
+ | `yaml` | `Schema.from_yaml()`, `Schema.model_dump_yaml()` |
98
+ | `codegen` | `Schema.from_json_schema()`, `FunctionSchema.to_parameter_model_code()`, `jsonschema_to_code()`, `openapi_to_code()` |
99
+ | `tool_execution` | FastAPI routes and the HTTP tool server |
100
+ | `storage` | `ModelStore` (async SQLite storage) |
101
+ | `markdown` | Jinja templates for markdown docs |
102
+ | `ai` | `Schema.from_llm()`, `create_schema(..., mode="openai")`, `schemez.openapi` |
103
+
104
+ ```bash
105
+ pip install "schemez[yaml,codegen]"
106
+ ```
107
+
108
+ ## Quick start
109
+
110
+ ```python
111
+ from typing import Literal
112
+
113
+ from schemez import create_schema
114
+
115
+
116
+ def search_users(
117
+ query: str,
118
+ limit: int = 10,
119
+ status: Literal["active", "inactive"] = "active",
120
+ ) -> list[dict]:
121
+ """Search for users.
122
+
123
+ Args:
124
+ query: Search query string
125
+ limit: Maximum number of results
126
+ status: User status filter
127
+ """
128
+ return []
129
+
130
+
131
+ schema = create_schema(search_users)
132
+ schema.name # "search_users"
133
+ schema.description # "Search for users."
134
+ schema.parameters["properties"]["status"]
135
+ # {'type': 'string', 'description': 'User status filter',
136
+ # 'enum': ['active', 'inactive'], 'default': 'active'}
137
+
138
+ schema.model_dump_openai() # {"type": "function", "function": {...}}
139
+ schema.to_python_signature()
140
+ # (*, query: str, limit: int = 10, status: Literal['active', 'inactive'] = 'active') -> list[typing.Any]
141
+ ```
142
+
143
+ ## Features
144
+
145
+ ### Function schemas
146
+
147
+ `create_schema()` returns a `FunctionSchema` (name, description, parameters, required, returns)
148
+ built from type hints and docstrings (Google, NumPy and Sphinx styles).
149
+
150
+ - `model_dump_openai()`: OpenAI function-calling tool definition
151
+ - `to_python_signature()`, `get_annotations()`: reconstruct the signature
152
+ - `create_parameter_model()`: Pydantic model for the parameters
153
+ - `to_parameter_model_code()` / `to_return_model_code()`: Python source for those models (`codegen` extra)
154
+ - `create_schema(func, exclude_types=[Context])` drops parameters of the given types (e.g. injected
155
+ context objects); `name_override` / `description_override` replace name and docstring.
156
+ - `mode="simple"` (default) produces compact, LLM-friendly schemas: unions collapse to their first
157
+ type, enums become plain value lists. `mode="jsonschema"` keeps Pydantic's full JSON Schema
158
+ (`anyOf`, `$defs`), `mode="openai"` uses pydantic-ai's tool schema generator.
159
+
160
+ Bulk helpers: `create_schemas_from_callables({"name": func, ...})`, `create_schemas_from_class(cls)`,
161
+ `create_schemas_from_module(module, include_functions=[...])` and `create_constructor_schema(cls)`.
162
+
163
+ `create_executable(func)` wraps a function together with its schema and runs sync, async and
164
+ (async) generator functions uniformly via `run()`, `arun()` and `astream()`.
165
+
166
+ ### `Schema` base model
167
+
168
+ `Schema` is a `pydantic.BaseModel` with `extra="forbid"` and attribute docstrings as field
169
+ descriptions, plus helpers:
170
+
171
+ ```python
172
+ from schemez import Schema
173
+
174
+
175
+ class DatabaseConfig(Schema):
176
+ host: str = "localhost"
177
+ """Database host."""
178
+
179
+ port: int = 5432
180
+ """Database port."""
181
+
182
+
183
+ class AppConfig(Schema):
184
+ name: str
185
+ database: DatabaseConfig = DatabaseConfig()
186
+
187
+
188
+ config = AppConfig.from_yaml("name: my-app\ndatabase:\n port: 6543\n")
189
+ print(config.model_dump_yaml(comments=True))
190
+ # database:
191
+ # host: localhost # Database host.
192
+ # port: 6543 # Database port.
193
+ # name: my-app
194
+
195
+ config.model_dump_markdown() # markdown table documenting the model and its values
196
+ AppConfig.generate_test_data(mode="minimal") # valid instance generated from the schema
197
+ ```
198
+
199
+ More class methods: `Schema.for_function(func)` and `Schema.for_class_ctor(cls)` build models from
200
+ signatures, `Schema.from_json_schema(json_schema)` builds one from JSON Schema (`codegen` extra),
201
+ `to_python_code()` emits model source code, and `merge()` / `iter_submodels()` work on instances.
202
+
203
+ ### JSON Schema and OpenAPI to code
204
+
205
+ `jsonschema_to_code()` and `openapi_to_code()` generate Pydantic model source code (via
206
+ datamodel-code-generator). `SchemaDef` (`InlineSchemaDef`, `ImportedSchemaDef`) lets you declare
207
+ models in YAML/JSON config and build them with `get_schema()`.
208
+
209
+ ### Tool code generation
210
+
211
+ `ToolsetCodeGenerator` turns a set of callables (or `FunctionSchema`s) into client code, LLM stubs
212
+ or FastAPI routes:
213
+
214
+ ```python
215
+ from fastapi import FastAPI
216
+
217
+ from schemez import ToolsetCodeGenerator
218
+
219
+
220
+ def get_weather(location: str, unit: str = "C") -> dict:
221
+ """Get weather for a location."""
222
+ return {"temp": 22, "location": location}
223
+
224
+
225
+ generator = ToolsetCodeGenerator.from_callables([get_weather, search_users])
226
+
227
+ # Async httpx client functions calling a tool server
228
+ client_code = generator.generate_code(base_url="https://api.example.com", path_prefix="/tools")
229
+ # Signatures + docstrings only, for LLM prompts
230
+ stubs = generator.generate_code(output_type="stubs")
231
+ # Functions taking a generated Pydantic input model instead of keyword arguments
232
+ model_based = generator.generate_code(args_format="model")
233
+ # Human-readable overview of the available functions
234
+ print(generator.generate_tool_description())
235
+
236
+ # Expose the callables as FastAPI routes: GET /tools/get_weather, GET /tools/search_users
237
+ app = FastAPI()
238
+ generator.add_all_routes(app, path_prefix="/tools")
239
+ ```
240
+
241
+ `ToolsetCodeGenerator.from_schemas([...])` works without implementations (code generation only),
242
+ `generate_mcp_code(server_configs)` emits FastMCP client code, and `ToolCodeGenerator` handles a
243
+ single tool. `schemez.tool_executor.HttpToolExecutor` serves tools over HTTP.
244
+
245
+ ### Model storage
246
+
247
+ ```python
248
+ from pydantic import BaseModel
249
+
250
+ from schemez import ModelStore
251
+
252
+
253
+ class Note(BaseModel):
254
+ title: str
255
+ tags: list[str] = []
256
+
257
+
258
+ async def main() -> None:
259
+ async with ModelStore(Note, "notes.db") as store:
260
+ note_id = await store.insert(Note(title="hello", tags=["a"]))
261
+ await store.get(note_id) # Note(title='hello', tags=['a'])
262
+ await store.query(title="hello")
263
+
264
+ # Reopen later: the model type is rebuilt from the stored JSON schema
265
+ async with await ModelStore.open("notes.db") as store:
266
+ await store.all()
267
+ ```
268
+
269
+ ### Markdown documentation
270
+
271
+ `models_to_markdown_docs()` renders documentation for several models; the `jinjarope` entry point
272
+ registers the markdown helpers as Jinja filters.
273
+
274
+ ## Documentation
275
+
276
+ Full API reference: https://phil65.github.io/schemez/
277
+
278
+ ## License
279
+
280
+ MIT
@@ -0,0 +1,226 @@
1
+ # Schemez
2
+
3
+ [![PyPI License](https://img.shields.io/pypi/l/schemez.svg)](https://pypi.org/project/schemez/)
4
+ [![Package status](https://img.shields.io/pypi/status/schemez.svg)](https://pypi.org/project/schemez/)
5
+ [![Monthly downloads](https://img.shields.io/pypi/dm/schemez.svg)](https://pypi.org/project/schemez/)
6
+ [![Distribution format](https://img.shields.io/pypi/format/schemez.svg)](https://pypi.org/project/schemez/)
7
+ [![Wheel availability](https://img.shields.io/pypi/wheel/schemez.svg)](https://pypi.org/project/schemez/)
8
+ [![Python version](https://img.shields.io/pypi/pyversions/schemez.svg)](https://pypi.org/project/schemez/)
9
+ [![Implementation](https://img.shields.io/pypi/implementation/schemez.svg)](https://pypi.org/project/schemez/)
10
+ [![Releases](https://img.shields.io/github/downloads/phil65/schemez/total.svg)](https://github.com/phil65/schemez/releases)
11
+ [![Github Contributors](https://img.shields.io/github/contributors/phil65/schemez)](https://github.com/phil65/schemez/graphs/contributors)
12
+ [![Github Discussions](https://img.shields.io/github/discussions/phil65/schemez)](https://github.com/phil65/schemez/discussions)
13
+ [![Github Forks](https://img.shields.io/github/forks/phil65/schemez)](https://github.com/phil65/schemez/forks)
14
+ [![Github Issues](https://img.shields.io/github/issues/phil65/schemez)](https://github.com/phil65/schemez/issues)
15
+ [![Github Issues](https://img.shields.io/github/issues-pr/phil65/schemez)](https://github.com/phil65/schemez/pulls)
16
+ [![Github Watchers](https://img.shields.io/github/watchers/phil65/schemez)](https://github.com/phil65/schemez/watchers)
17
+ [![Github Stars](https://img.shields.io/github/stars/phil65/schemez)](https://github.com/phil65/schemez/stars)
18
+ [![Github Repository size](https://img.shields.io/github/repo-size/phil65/schemez)](https://github.com/phil65/schemez)
19
+ [![Github last commit](https://img.shields.io/github/last-commit/phil65/schemez)](https://github.com/phil65/schemez/commits)
20
+ [![Github release date](https://img.shields.io/github/release-date/phil65/schemez)](https://github.com/phil65/schemez/releases)
21
+ [![Github language count](https://img.shields.io/github/languages/count/phil65/schemez)](https://github.com/phil65/schemez)
22
+ [![Github commits this month](https://img.shields.io/github/commit-activity/m/phil65/schemez)](https://github.com/phil65/schemez)
23
+ [![Package status](https://codecov.io/gh/phil65/schemez/branch/main/graph/badge.svg)](https://codecov.io/gh/phil65/schemez/)
24
+ [![PyUp](https://pyup.io/repos/github/phil65/schemez/shield.svg)](https://pyup.io/repos/github/phil65/schemez/)
25
+
26
+ [Read the documentation!](https://phil65.github.io/schemez/)
27
+
28
+ Schemez is a Pydantic toolkit for turning Python code into schemas and schemas into code.
29
+ It builds OpenAI-compatible tool schemas from function signatures, creates Pydantic models
30
+ from JSON Schema, generates HTTP/MCP client code and FastAPI routes for tools, and gives your
31
+ config models YAML, markdown and test-data helpers.
32
+
33
+ ## Installation
34
+
35
+ ```bash
36
+ pip install schemez
37
+ ```
38
+
39
+ Optional extras enable individual features:
40
+
41
+ | Extra | Enables |
42
+ | --- | --- |
43
+ | `yaml` | `Schema.from_yaml()`, `Schema.model_dump_yaml()` |
44
+ | `codegen` | `Schema.from_json_schema()`, `FunctionSchema.to_parameter_model_code()`, `jsonschema_to_code()`, `openapi_to_code()` |
45
+ | `tool_execution` | FastAPI routes and the HTTP tool server |
46
+ | `storage` | `ModelStore` (async SQLite storage) |
47
+ | `markdown` | Jinja templates for markdown docs |
48
+ | `ai` | `Schema.from_llm()`, `create_schema(..., mode="openai")`, `schemez.openapi` |
49
+
50
+ ```bash
51
+ pip install "schemez[yaml,codegen]"
52
+ ```
53
+
54
+ ## Quick start
55
+
56
+ ```python
57
+ from typing import Literal
58
+
59
+ from schemez import create_schema
60
+
61
+
62
+ def search_users(
63
+ query: str,
64
+ limit: int = 10,
65
+ status: Literal["active", "inactive"] = "active",
66
+ ) -> list[dict]:
67
+ """Search for users.
68
+
69
+ Args:
70
+ query: Search query string
71
+ limit: Maximum number of results
72
+ status: User status filter
73
+ """
74
+ return []
75
+
76
+
77
+ schema = create_schema(search_users)
78
+ schema.name # "search_users"
79
+ schema.description # "Search for users."
80
+ schema.parameters["properties"]["status"]
81
+ # {'type': 'string', 'description': 'User status filter',
82
+ # 'enum': ['active', 'inactive'], 'default': 'active'}
83
+
84
+ schema.model_dump_openai() # {"type": "function", "function": {...}}
85
+ schema.to_python_signature()
86
+ # (*, query: str, limit: int = 10, status: Literal['active', 'inactive'] = 'active') -> list[typing.Any]
87
+ ```
88
+
89
+ ## Features
90
+
91
+ ### Function schemas
92
+
93
+ `create_schema()` returns a `FunctionSchema` (name, description, parameters, required, returns)
94
+ built from type hints and docstrings (Google, NumPy and Sphinx styles).
95
+
96
+ - `model_dump_openai()`: OpenAI function-calling tool definition
97
+ - `to_python_signature()`, `get_annotations()`: reconstruct the signature
98
+ - `create_parameter_model()`: Pydantic model for the parameters
99
+ - `to_parameter_model_code()` / `to_return_model_code()`: Python source for those models (`codegen` extra)
100
+ - `create_schema(func, exclude_types=[Context])` drops parameters of the given types (e.g. injected
101
+ context objects); `name_override` / `description_override` replace name and docstring.
102
+ - `mode="simple"` (default) produces compact, LLM-friendly schemas: unions collapse to their first
103
+ type, enums become plain value lists. `mode="jsonschema"` keeps Pydantic's full JSON Schema
104
+ (`anyOf`, `$defs`), `mode="openai"` uses pydantic-ai's tool schema generator.
105
+
106
+ Bulk helpers: `create_schemas_from_callables({"name": func, ...})`, `create_schemas_from_class(cls)`,
107
+ `create_schemas_from_module(module, include_functions=[...])` and `create_constructor_schema(cls)`.
108
+
109
+ `create_executable(func)` wraps a function together with its schema and runs sync, async and
110
+ (async) generator functions uniformly via `run()`, `arun()` and `astream()`.
111
+
112
+ ### `Schema` base model
113
+
114
+ `Schema` is a `pydantic.BaseModel` with `extra="forbid"` and attribute docstrings as field
115
+ descriptions, plus helpers:
116
+
117
+ ```python
118
+ from schemez import Schema
119
+
120
+
121
+ class DatabaseConfig(Schema):
122
+ host: str = "localhost"
123
+ """Database host."""
124
+
125
+ port: int = 5432
126
+ """Database port."""
127
+
128
+
129
+ class AppConfig(Schema):
130
+ name: str
131
+ database: DatabaseConfig = DatabaseConfig()
132
+
133
+
134
+ config = AppConfig.from_yaml("name: my-app\ndatabase:\n port: 6543\n")
135
+ print(config.model_dump_yaml(comments=True))
136
+ # database:
137
+ # host: localhost # Database host.
138
+ # port: 6543 # Database port.
139
+ # name: my-app
140
+
141
+ config.model_dump_markdown() # markdown table documenting the model and its values
142
+ AppConfig.generate_test_data(mode="minimal") # valid instance generated from the schema
143
+ ```
144
+
145
+ More class methods: `Schema.for_function(func)` and `Schema.for_class_ctor(cls)` build models from
146
+ signatures, `Schema.from_json_schema(json_schema)` builds one from JSON Schema (`codegen` extra),
147
+ `to_python_code()` emits model source code, and `merge()` / `iter_submodels()` work on instances.
148
+
149
+ ### JSON Schema and OpenAPI to code
150
+
151
+ `jsonschema_to_code()` and `openapi_to_code()` generate Pydantic model source code (via
152
+ datamodel-code-generator). `SchemaDef` (`InlineSchemaDef`, `ImportedSchemaDef`) lets you declare
153
+ models in YAML/JSON config and build them with `get_schema()`.
154
+
155
+ ### Tool code generation
156
+
157
+ `ToolsetCodeGenerator` turns a set of callables (or `FunctionSchema`s) into client code, LLM stubs
158
+ or FastAPI routes:
159
+
160
+ ```python
161
+ from fastapi import FastAPI
162
+
163
+ from schemez import ToolsetCodeGenerator
164
+
165
+
166
+ def get_weather(location: str, unit: str = "C") -> dict:
167
+ """Get weather for a location."""
168
+ return {"temp": 22, "location": location}
169
+
170
+
171
+ generator = ToolsetCodeGenerator.from_callables([get_weather, search_users])
172
+
173
+ # Async httpx client functions calling a tool server
174
+ client_code = generator.generate_code(base_url="https://api.example.com", path_prefix="/tools")
175
+ # Signatures + docstrings only, for LLM prompts
176
+ stubs = generator.generate_code(output_type="stubs")
177
+ # Functions taking a generated Pydantic input model instead of keyword arguments
178
+ model_based = generator.generate_code(args_format="model")
179
+ # Human-readable overview of the available functions
180
+ print(generator.generate_tool_description())
181
+
182
+ # Expose the callables as FastAPI routes: GET /tools/get_weather, GET /tools/search_users
183
+ app = FastAPI()
184
+ generator.add_all_routes(app, path_prefix="/tools")
185
+ ```
186
+
187
+ `ToolsetCodeGenerator.from_schemas([...])` works without implementations (code generation only),
188
+ `generate_mcp_code(server_configs)` emits FastMCP client code, and `ToolCodeGenerator` handles a
189
+ single tool. `schemez.tool_executor.HttpToolExecutor` serves tools over HTTP.
190
+
191
+ ### Model storage
192
+
193
+ ```python
194
+ from pydantic import BaseModel
195
+
196
+ from schemez import ModelStore
197
+
198
+
199
+ class Note(BaseModel):
200
+ title: str
201
+ tags: list[str] = []
202
+
203
+
204
+ async def main() -> None:
205
+ async with ModelStore(Note, "notes.db") as store:
206
+ note_id = await store.insert(Note(title="hello", tags=["a"]))
207
+ await store.get(note_id) # Note(title='hello', tags=['a'])
208
+ await store.query(title="hello")
209
+
210
+ # Reopen later: the model type is rebuilt from the stored JSON schema
211
+ async with await ModelStore.open("notes.db") as store:
212
+ await store.all()
213
+ ```
214
+
215
+ ### Markdown documentation
216
+
217
+ `models_to_markdown_docs()` renders documentation for several models; the `jinjarope` entry point
218
+ registers the markdown helpers as Jinja filters.
219
+
220
+ ## Documentation
221
+
222
+ Full API reference: https://phil65.github.io/schemez/
223
+
224
+ ## License
225
+
226
+ MIT