From c10f3af211f05234550ff13b5ec6778793d56e90 Mon Sep 17 00:00:00 2001 From: Brett Date: Tue, 14 May 2024 12:00:29 -0400 Subject: [PATCH] update docs for Converter.lazy attribute --- asdf/extension/_converter.py | 5 +++++ docs/asdf/extending/converters.rst | 8 ++++++++ 2 files changed, 13 insertions(+) diff --git a/asdf/extension/_converter.py b/asdf/extension/_converter.py index 3fa437916..fca64a936 100644 --- a/asdf/extension/_converter.py +++ b/asdf/extension/_converter.py @@ -34,6 +34,11 @@ class Converter(abc.ABC): and return a str, the selected tag (should be one of tags) or `None` which will trigger the result of ``to_yaml_tree`` to be used to look up the next converter for this object. + + The ``lazy`` attribute is optional. If ``True`` asdf will + pass "lazy" objects to the converter. If ``False`` (or not + defined) asdf will convert all child objects before calling + `from_yaml_tree`. """ @classmethod diff --git a/docs/asdf/extending/converters.rst b/docs/asdf/extending/converters.rst index 4c5beb410..6f98c8695 100644 --- a/docs/asdf/extending/converters.rst +++ b/docs/asdf/extending/converters.rst @@ -56,6 +56,14 @@ when some logic is required to select the tag to assign to a ``to_yaml_tree`` re `Converter.select_tag` - an optional method that accepts a complex Python object and a list candidate tags and returns the tag that should be used to serialize the object. +`Converter.lazy` - a boolean attribute indicating if this converter accepts "lazy" objects +(those defined in `asdf.lazy_nodes`). This is mostly useful for container-like classes +(where the "lazy" objects can defer conversion of contained objects until they are accessed). +If a converter produces a generator lazy should be set to ``False`` as asdf will need +to generate nodes further out the branch to fully resolve the object returned from the +generator. + + A simple example ================