Fields¶
Primitive Fields¶
-
class
jsl.fields.
NullField
(id='', default=None, enum=None, title=None, description=None, **kwargs)[source]¶ A null field.
-
class
jsl.fields.
BooleanField
(id='', default=None, enum=None, title=None, description=None, **kwargs)[source]¶ A boolean field.
-
class
jsl.fields.
NumberField
(multiple_of=None, minimum=None, maximum=None, exclusive_minimum=None, exclusive_maximum=None, **kwargs)[source]¶ A number field.
Parameters: - multiple_of (number or
Resolvable
) – A value must be a multiple of this factor. - minimum (number or
Resolvable
) – A minimum allowed value. - exclusive_minimum (bool or
Resolvable
) – Whether a value is allowed to exactly equal the minimum. - maximum (number or
Resolvable
) – A maximum allowed value. - exclusive_maximum (bool or
Resolvable
) – Whether a value is allowed to exactly equal the maximum.
-
multiple_of
= None¶
-
minimum
= None¶
-
exclusive_minimum
= None¶
-
maximum
= None¶
-
exclusive_maximum
= None¶
- multiple_of (number or
-
class
jsl.fields.
IntField
(multiple_of=None, minimum=None, maximum=None, exclusive_minimum=None, exclusive_maximum=None, **kwargs)[source]¶ Bases:
jsl.fields.primitive.NumberField
An integer field.
-
class
jsl.fields.
StringField
(pattern=None, format=None, min_length=None, max_length=None, **kwargs)[source]¶ A string field.
Parameters: - pattern (string or
Resolvable
) – A regular expression (ECMA 262) that a string value must match. - format (string or
Resolvable
) – A semantic format of the string (for example,"date-time"
,"email"
, or"uri"
). - min_length (int or
Resolvable
) – A minimum length. - max_length (int or
Resolvable
) – A maximum length.
-
pattern
= None¶
-
format
= None¶
-
min_length
= None¶
-
max_length
= None¶
- pattern (string or
-
class
jsl.fields.
EmailField
(pattern=None, format=None, min_length=None, max_length=None, **kwargs)[source]¶ Bases:
jsl.fields.primitive.StringField
An email field.
-
class
jsl.fields.
IPv4Field
(pattern=None, format=None, min_length=None, max_length=None, **kwargs)[source]¶ Bases:
jsl.fields.primitive.StringField
An IPv4 field.
Compound Fields¶
-
jsl.fields.
RECURSIVE_REFERENCE_CONSTANT
¶ A special value to be used as an argument to create a recursive
DocumentField
.
-
class
jsl.fields.
DocumentField
(document_cls, as_ref=False, **kwargs)[source]¶ A reference to a nested document.
Parameters: - document_cls – A string (dot-separated path to document class, i.e.
"app.resources.User"
),RECURSIVE_REFERENCE_CONSTANT
or aDocument
subclass. - as_ref (bool) – If
True
, the schema ofdocument_cls`
is placed into the definitions dictionary, and the field schema just references to it:{"$ref": "#/definitions/..."}
. It may make a resulting schema more readable.
-
as_ref
= None¶
- document_cls – A string (dot-separated path to document class, i.e.
-
class
jsl.fields.
RefField
(pointer, **kwargs)[source]¶ A reference.
Parameters: pointer (str) – A JSON pointer.
-
pointer
= None¶
-
-
class
jsl.fields.
ArrayField
(items=None, additional_items=None, min_items=None, max_items=None, unique_items=None, **kwargs)[source]¶ An array field.
Parameters: - items –
Either of the following:
BaseField
– all items of the array must match the field schema;- a list or a tuple of
fields
– all items of the array must be valid according to the field schema at the corresponding index (tuple typing); - a
Resolvable
resolving to either of the first two options.
- min_items (int or
Resolvable
) – A minimum length of an array. - max_items (int or
Resolvable
) – A maximum length of an array. - unique_items (bool or
Resolvable
) – Whether all the values in the array must be distinct. - additional_items (bool or
BaseField
orResolvable
) – If the value ofitems
is a list or a tuple, and the array length is larger than the number of fields initems
, then the additional items are described by theBaseField
passed using this argument.
-
items
= None¶
-
min_items
= None¶
-
max_items
= None¶
-
unique_items
= None¶
-
additional_items
= None¶
- items –
-
class
jsl.fields.
DictField
(properties=None, pattern_properties=None, additional_properties=None, min_properties=None, max_properties=None, **kwargs)[source]¶ A dictionary field.
Parameters: - properties (dict[str ->
BaseField
orResolvable
]) – A dictionary containing fields. - pattern_properties (dict[str ->
BaseField
orResolvable
]) – A dictionary whose keys are regular expressions (ECMA 262). Properties match against these regular expressions, and for any that match, the property is described by the corresponding field schema. - additional_properties (bool or
BaseField
orResolvable
) – Describes properties that are not described by theproperties
orpattern_properties
. - min_properties (int or
Resolvable
) – A minimum number of properties. - max_properties (int or
Resolvable
) – A maximum number of properties
-
properties
= None¶
-
pattern_properties
= None¶
-
additional_properties
= None¶
-
min_properties
= None¶
-
max_properties
= None¶
- properties (dict[str ->
-
class
jsl.fields.
NotField
(field, **kwargs)[source]¶ Parameters: field ( BaseField
orResolvable
) – A field to negate.-
field
= None¶
-
-
class
jsl.fields.
OneOfField
(fields, **kwargs)[source]¶ Parameters: fields (list[ BaseField
orResolvable
]) – A list of fields, exactly one of which describes the data.-
fields
= None¶
-
-
class
jsl.fields.
AnyOfField
(fields, **kwargs)[source]¶ Parameters: fields (list[ BaseField
orResolvable
]) – A list of fields, at least one of which describes the data.-
fields
= None¶
-
-
class
jsl.fields.
AllOfField
(fields, **kwargs)[source]¶ Parameters: fields (list[ BaseField
orResolvable
]) – A list of fields, all of which describe the data.-
fields
= None¶
-
Base Classes¶
-
jsl.fields.
Null
= <jsl.fields.base.NullSentinel object>¶ A special value that can be used to set the default value of a field to null.
-
class
jsl.fields.
BaseField
(name=None, required=False)[source]¶ A base class for fields of
documents
. Instances of this class may be added to a document to define its properties.Implements the
Resolvable
interface.Parameters: - required (bool or
Resolvable
) – Whether the field is required. Defaults toFalse
. - name (str) –
If specified, used as a key under which the field schema appears in
document
schema properties.New in version 0.1.4.
-
name
= None¶ Name
-
required
= None¶ Whether the field is required.
-
resolve
(role)[source]¶ Implements the
Resolvable
interface.Always returns a
Resolution(self, role)
.Return type: Resolution
-
iter_possible_values
()[source]¶ Implements the
Resolvable
interface.Yields a single value –
self
.
-
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 data described by this field, 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 to a reference:{"$ref": "#/definitions/..."}
. Note: resulting definitions will not contain schema for this document.
Raises: Return type: (dict, dict or OrderedDict)
-
iter_fields
()[source]¶ Iterates over the nested fields of the document examining all possible values of the occuring
resolvables
.
-
walk
(through_document_fields=False, visited_documents=frozenset([]))[source]¶ Iterates recursively over the nested fields, examining all possible values of the occuring
resolvables
.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
-
resolve_and_iter_fields
(role='default')[source]¶ The same as
iter_fields()
, butresolvables
are resolved usingrole
.
-
resolve_and_walk
(role='default', through_document_fields=False, visited_documents=frozenset([]))[source]¶ The same as
walk()
, butresolvables
are resolved usingrole
.
-
get_schema
(ordered=False, role='default')[source]¶ Returns a JSON schema (draft v4) of the field.
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
-
resolve_attr
(attr, role='default')[source]¶ Resolves an attribure with the name
field
usingrole
.If the value of
attr
isresolvable
, it resolves it using a givenrole
and returns the result. Otherwise it returns the raw value androle
unchanged.Raises: AttributeError
Return type: Resolution
- required (bool or
-
class
jsl.fields.
BaseSchemaField
(id='', default=None, enum=None, title=None, description=None, **kwargs)[source]¶ A base class for fields that directly map to JSON Schema validator.
Parameters: - required (bool or
Resolvable
) – If the field is required. Defaults toFalse
. - id (str) – A string to be used as a value of the “id” keyword of the resulting schema.
- default (any JSON-representable object, a callable or a
Resolvable
) – The default value for this field. May beNull
(a special value to set the default value to null) or a callable. - enum (list, tuple, set, callable or
Resolvable
) – A list of valid choices. May be a callable. - title (str or
Resolvable
) – A short explanation about the purpose of the data described by this field. - description (str or
Resolvable
) – A detailed explanation about the purpose of the data described by this field.
-
id
= None¶ A string to be used as a value of the “id” keyword of the resulting schema.
-
title
= None¶ A short explanation about the purpose of the data.
-
description
= None¶ A detailed explanation about the purpose of the data.
- required (bool or