Skip to content

Commit cf47a21

Browse files
committed
Minor rewording of the caching section and give it a subsection.
1 parent 4f841c4 commit cf47a21

File tree

2 files changed

+13
-5
lines changed

2 files changed

+13
-5
lines changed

docs/changes.rst

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,11 @@
22
Changelog
33
=========
44

5+
v0.29.1
6+
-------
7+
8+
* Minor docs improvement.
9+
510
v0.29.0
611
-------
712

docs/intro.rst

Lines changed: 8 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -237,12 +237,15 @@ Here's an example of automatically retrieving external references by downloading
237237

238238
`referencing` will of course therefore not do any such thing automatically, and this section generally assumes that you have personally considered the security implications for your own use case.
239239

240-
A common concern in these situations is also to *cache* the resulting resource such that repeated lookups of the same URI do not repeatedly make network calls, or hit the filesystem, etc.
240+
Caching
241+
^^^^^^^
241242

242-
You are of course free to use whatever caching mechanism is convenient (e.g. one specific to ``httpx`` in the above example).
243+
A common concern in these situations is also to *cache* the resulting resource such that repeated lookups of the same URI do not repeatedly call your retrieval function and thereby make network calls, hit the filesystem, etc.
243244

244-
Because of how common it is to retrieve a JSON string and construct a resource from it however, a decorator which specifically does so is also provided called `referencing.retrieval.to_cached_resource`.
245-
If you use it, note that your retrieval callable should return `str`, not a `Resource`, as the decorator will handle deserializing your response (this is mostly because otherwise, deserialized JSON is generally not hashable).
245+
You are of course free to use whatever caching mechanism is convenient even if it uses caching functionality entirely unrelated to this library (e.g. one specific to ``httpx`` in the above example, or one using `functools.lru_cache` internally).
246+
247+
Nonetheless, because it is so common to retrieve a JSON string and construct a resource from it, `referencing.retrieval.to_cached_resource` is a decorator which can help.
248+
If you use it, your retrieval callable should return a `str`, not a `Resource`, as the decorator will handle deserializing your response and constructing a `Resource` from it (this is mostly because otherwise, deserialized JSON is generally not hashable if it ends up being a Python `dict`).
246249

247250
The above example would be written:
248251

@@ -263,4 +266,4 @@ The above example would be written:
263266
resolver = registry.resolver()
264267
print(resolver.lookup("https://json-schema.org/draft/2020-12/schema"))
265268
266-
and besides than that it will cache responses and not repeatedly call the retrieval function, it is otherwise functionally equivalent.
269+
It is otherwise functionally equivalent to the above, other than that retrieval will not repeatedly make a web request.

0 commit comments

Comments
 (0)