HideyoshiNakazone/jambo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 12 Wiki Activity

chore: improves documentation and readme

Browse Source
This commit is contained in:
Vitor Hideyoshi
2025-11-26 09:00:57 -03:00
parent b705a3a70b
commit beed4e5e97
3 changed files with 61 additions and 6 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/source/usage.ref_cache.rst
View File

@@ -10,6 +10,12 @@ and :py:meth:`SchemaConverter.build <jambo.SchemaConverter.build>`.
However, only :py:meth:`SchemaConverter.build_with_cache <jambo.SchemaConverter.build_with_cache>` exposes the cache through a supported API;
:py:meth:`SchemaConverter.build <jambo.SchemaConverter.build>` uses the cache internally and does not provide access to it.
The reference cache accepts a mutable mapping (typically a plain Python dict)
that maps reference names (strings) to generated Pydantic model classes.
Since only the reference names are stored it can cause name collisions if
multiple schemas with overlapping names are processed using the same cache.
Therefore, it's recommended that each namespace or schema source uses its own
:class:`SchemaConverter` instance.
-----------------------------------------
Configuring and Using the Reference Cache

7
docs/source/usage.rst
View File

@@ -42,7 +42,7 @@ Static Method (no config)
The :py:meth:`SchemaConverter.build <jambo.SchemaConverter.build>` static method takes a JSON Schema dictionary and returns a Pydantic model class.
Note: the static ``build`` method was the original public API of this library and is kept for backwards compatibility. It creates and returns a model class for the provided schema but does not expose or persist an instance cache.
Note: the static ``build`` method was the original public API of this library. It creates and returns a model class for the provided schema but does not expose or persist an instance cache.
--------------------------------
@@ -97,6 +97,11 @@ the instance method persists and exposes the reference cache and provides helper
:py:meth:`SchemaConverter.get_cached_ref <jambo.SchemaConverter.get_cached_ref>` and
:py:meth:`SchemaConverter.clear_ref_cache <jambo.SchemaConverter.clear_ref_cache>`.
.. warning::
The instance API with reference cache can lead to schema and type name collisions if not managed carefully.
It's recommended that each namespace or schema source uses its own `SchemaConverter` instance.
If you don't need cache control, the static API is simpler and sufficient for most use cases.
For details and examples about the reference cache and the different cache modes (instance cache, per-call cache, ephemeral cache), see:
.. toctree::