Unlike with querying values you can, but don't need to specify whether elements queried from the document are optional or required. As you will most often use the elements' values themselves, the necessity for the element hierarchy in between the document and that value is automatically inferred by whether the value itself is optional or required:
The line above can be run for an entirely empty document and still return
None, while by
modifying the query of the value itself to be required would make the code raise an error for
the first element missing in that hierarchy instead (again assuming an empty document):
This would produce an error:
The section 'content' is missing - in case it has been specified look for typos and also check for correct capitalization. Line | Content * 1 |
With that said, there will of course also be cases where you want to be explicit
about whether an element is optional or required, for this you can use the
required_* accessor variant, which exists for all
element types, for instance:
As with value accessors, the
optional_* variants return
None if the element
does not exist (be aware that you should not chain further queries after such a
call because you'd potentially be calling a function on
None), while the
variants immediately raise an error when the element is missing (here you can safely chain further queries afterwards).
Below is a pattern you might find useful, it's basically saying "There always has to
be a field with the key 'author', but it can be empty". It returns
None or the value,
and only raises an error when the field itself is missing.
The pattern below is sort of the reverse, it's "If there is a field with the key 'author', it also requires a value", and guarantees there is a value if there is also a field, otherwise an error is raised.
author = document.optional_field('author') if author: value = author.required_string_value() # ...
Last but not least a pattern that does not work:
author = document.field('author') if author: # Will always enter here, author is never None
As shown earlier you can safely and deeply query a non-existing document
hierarchy. This is possible because the standard query methods return proxy
MissingSection) instead of
None when an element in the chain
is missing, and with that it's clear why the previous example does not work,
instead you have to use the explicit
optional_field accessor to ensure you are
None if there is no element.
author = document.optional_field('author') if author: # This works, author can be None now
Next page: Dynamic layouts