Document¶
-
class
jsl.document.
Options
(additional_properties=False, pattern_properties=None, min_properties=None, max_properties=None, title=None, description=None, default=None, enum=None, id='', schema_uri='http://json-schema.org/draft-04/schema#', definition_id=None, roles_to_propagate=None)[source]¶ A container for options.
All the arguments are the same and work exactly as for
fields.DictField
exceptproperties
(since it is automatically populated with the document fields) and these:Parameters: - definition_id (str or
Resolvable
) – A unique string to be used as a key for this document in the “definitions” schema section. If not specified, will be generated from module and class names. - schema_uri (str) – An URI of the JSON Schema meta-schema.
- roles_to_propagate (callable, string or iterable) – A matcher. If it returns
True
for a role, it will be passed to nested documents.
- definition_id (str or
-
class
jsl.document.
Document
[source]¶ A document. Can be thought as a kind of
fields.DictField
, which properties are defined by the fields and scopes added to the document class.It can be tuned using special
Options
attribute (seeOptions
for available settings):class User(Document): class Options(object): title = 'User' description = 'A person who uses a computer or network service.' login = StringField(required=True)
-
classmethod
is_recursive
(role='default')[source]¶ Returns
True
if there is aDocumentField
-references cycle that containscls
.Parameters: role (str) – A current role.
-
classmethod
get_definition_id
(role='default')[source]¶ Returns a unique string to be used as a key for this document in the
"definitions"
schema section.
-
classmethod
resolve_field
(field, role='default')[source]¶ Resolves a field with the name
field
usingrole
.Raises: AttributeError
-
classmethod
resolve_and_iter_fields
(role='default')[source]¶ The same as
iter_fields()
, butresolvables
are resolved usingrole
.
-
classmethod
resolve_and_walk
(role='default', through_document_fields=False, visited_documents=frozenset([]))[source]¶ The same as
walk()
, butresolvables
are resolved usingrole
.
-
classmethod
iter_fields
()[source]¶ Iterates over the fields of the document, resolving its
resolvables
to all possible values.
-
classmethod
walk
(through_document_fields=False, visited_documents=frozenset([]))[source]¶ Iterates recursively over the fields of the document, resolving occurring
resolvables
to their all possible values.Visits fields in a DFS order.
Parameters: - through_document_fields (bool) – If
True
, walks through nestedDocumentField
fields. - visited_documents (set) – Keeps track of visited
documents
to avoid infinite recursion whenthrough_document_field
isTrue
.
Returns: iterable of
BaseField
- through_document_fields (bool) – If
-
classmethod
get_schema
(role='default', ordered=False)[source]¶ Returns a JSON schema (draft v4) of the document.
Parameters: - role (str) – A role.
- ordered (bool) – If
True
, the resulting schema dictionary is ordered. Fields are listed in the order they are added to the class. Schema properties are also ordered in a sensible and consistent way, making the schema more human-readable.
Raises: Return type: dict or OrderedDict
-
classmethod
get_definitions_and_schema
(role='default', res_scope=ResolutionScope( base=, current=, output= ), ordered=False, ref_documents=None)[source]¶ Returns a tuple of two elements.
The second element is a JSON schema of the document, and the first is a dictionary that contains definitions that are referenced from the schema.
Parameters: - role (str) – A role.
- ordered (bool) – If
True
, the resulting schema dictionary is ordered. Fields are listed in the order they are added to the class. Schema properties are also ordered in a sensible and consistent way, making the schema more human-readable. - res_scope (
ResolutionScope
) – The current resolution scope. - ref_documents (set) – If subclass of
Document
is in this set, allDocumentField
s pointing to it will be resolved as a reference:{"$ref": "#/definitions/..."}
. Note: resulting definitions will not contain schema for this document.
Raises: Return type: (dict, dict or OrderedDict)
-
classmethod
-
class
jsl.document.
DocumentMeta
[source]¶ A metaclass for
Document
. It’s responsible for collecting options, fields and scopes registering the document in the registry, making it the owner of nesteddocument fields
s and so on.-
options_container
¶ A class to be used by
create_options()
. Must be a subclass ofOptions
.alias of
Options
-
classmethod
collect_fields
(mcs, bases, attrs)[source]¶ Collects fields from the current class and its parent classes.
Return type: a dictionary mapping field names to fields
-
classmethod
collect_options
(mcs, bases, attrs)[source]¶ Collects options from the current class and its parent classes.
Returns: a dictionary of options
-
classmethod
create_options
(options)[source]¶ Wraps
options
into a container class (seeoptions_container
).Parameters: options – a dictionary of options Returns: an instance of options_container
-