`marsh.schema`¶

This module houses the mechanics that powers marshaling and unmarshaling.

class MarshalSchema(value, *args, **kwargs)[source]¶

Marshals its value input into a JSON-like object.

Parameters:: value (Any) – The value to match/marshal.

marshal()[source]¶

Marshal the value held by this instance into a JSON-like object.

Return type:: Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]
Returns:: The JSON-like marshaled value.

static doc_static_description()¶

Get a static string description of how the type supported by this schema is used.

Return type:: Optional[str]
Returns:: The description.

static doc_static_type()¶

Get a static string representation of the type supported by this schema.

Return type:: Optional[str]
Returns:: The name of the type.

classmethod match(value)¶

Match this class against a value.

Parameters:: value (Any) – The value to match against.
Return type:: bool
Returns:: True if matched, else False.

class UnmarshalSchema(*args, default='???', default_factory='???', **kwargs)[source]¶

Unmarshals JSON-like inputs into its value type.

Note

Static type checkers may give an error for abstract types (issue).

Some type aliases are also not recognized as types. For the moment there is not better solution than using a simple # type: ignore comment.

Parameters:

value (Type[_T]) – The value to match/unmarshal.
default (TypeVar(_T)) – An immutable default value. Mutually exclusive with default_factory.
default_factory (Callable[..., TypeVar(_T)]) – Factory function for a mutable default value. Mutually exclusive with default.

class Doc(type=None, default=None, description=None, fields=None, special_fields=None)[source]¶

Structured unmarshal documentation for a type.

Parameters:

type (Optional[str]) –
default (Optional[str]) –
description (Optional[str]) –
fields (Optional[Mapping[str, Field]]) –
special_fields (Optional[Sequence[SpecialField]]) –

class Field(doc, type=None, description=None)[source]¶

Unmarshal documentation for a field/attribute of a type.

Parameters:

doc (Doc) –
type (Optional[str]) –
description (Optional[str]) –

doc: Doc¶: The field unmarshal documentation.

type: Optional[str] = None¶: Type string as should be displayed when this is a field of a parent.

description: Optional[str] = None¶: Description for field by parent.

class SpecialField(value, description=None)[source]¶

Unmarshal documentation for a special field.

A special field may document any value.

Parameters:

value (str) –
description (Optional[str]) –

value: str¶: The name of the value being documented.

description: Optional[str] = None¶: Its description.

type: Optional[str] = None¶: String representation of the type.

default: Optional[str] = None¶: Default value.

description: Optional[str] = None¶: Description for type.

fields: Optional[Mapping[str, Field]] = None¶: Named internal fields of the documented type.

special_fields: Optional[Sequence[SpecialField]] = None¶: Any other fields that do not follow the name/type/default style.

has_default()[source]¶

Evaluates if this schema holds a default value.

Return type:: bool
Returns:: True if there is a default value, else False.

get_default()[source]¶

Get the default value of this schema.

If default value exists marsh.MISSING is returned instead.

Return type:: TypeVar(_T)
Returns:: The default value or marsh.MISSING.

select(path)[source]¶

Select a nested schema from this schema based on a dot-separated path. If not all of the path is consumed by this schema it is forwarded to the select method of the nested schema.

Parameters:: path (str) – The path to traverse.
Return type:: UnmarshalSchema
Returns:: The schema at the end of the path.

doc(depth=0)[source]¶

Get the documentation for the type unmarshaled by this schema.

Parameters:: depth (int) – How deep should documentation be fetched in nested schemas. If 0, only the fields and info for the type of this schema is returned.
Return type:: Doc
Returns:: The documentation.

doc_type()[source]¶

The name of the type unmarshaled by this schema.

Return type:: str
Returns:: The type name.

doc_field_type()[source]¶

Alternative name of the type unmarshaled by this schema.

This corresponds to the type that should be display in parent documentation when this is one of its fields.

Return type:: str
Returns:: Alternative type name.

doc_default()[source]¶

Document default value.

The default implementation of this method returns None if no default value exists and '...' if the default value is mutable. If the default value is immutable, an attempt is first made to marshal the default value before returning a string of its marshaled state. If this fails, a string of the default is returned.

Return type:: Optional[str]
Returns:: String of default.

doc_description()[source]¶

A description for the type unmarshaled by this schema.

Return type:: Optional[str]
Returns:: The description.

doc_fields(depth)[source]¶

Documentation for the fields of the type unmarshaled by this schema.

No documentation is returned if no fields exist.

Return type:: Optional[Mapping[str, Field]]
Returns:: Field documentation.
Parameters:: depth (int) –

doc_special_fields()[source]¶

Documentation for the special fields of the type unmarshaled by this schema.

No documentation is returned if no special fields exist.

Return type:: Optional[Sequence[SpecialField]]
Returns:: Special field documentation.

unmarshal(element)[source]¶

Construct the object of this schema.

Parameters:: element (Union[None, int, float, bool, str, Sequence[Any], Mapping[str, Any]]) – The input JSON-style data.
Return type:: TypeVar(_T)
Returns:: The object initialized with the input data.

static doc_static_description()¶

Get a static string description of how the type supported by this schema is used.

Return type:: Optional[str]
Returns:: The description.

static doc_static_type()¶

Get a static string representation of the type supported by this schema.

Return type:: Optional[str]
Returns:: The name of the type.

classmethod match(value)¶

Match this class against a value.

Parameters:: value (Any) – The value to match against.
Return type:: bool
Returns:: True if matched, else False.

register(schema: Type[_S], /, *, priority: int = 0, lower_priority: Union[None, Type[Schema], int, Iterable[Type[Schema]], Iterable[int]] = None, higher_priority: Union[None, Type[Schema], int, Iterable[Type[Schema]], Iterable[int]] = None, replace: bool = False) → Type[_S][source]¶

register(*, priority: int = 0, lower_priority: Union[None, Type[Schema], int, Iterable[Type[Schema]], Iterable[int]] = None, higher_priority: Union[None, Type[Schema], int, Iterable[Type[Schema]], Iterable[int]] = None, replace: bool = False) → Callable[[Type[_S]], Type[_S]]

Register a new schema (decorator).

Relative priorities can be given as higher and lower, where any schema in higher means that the schema being registered should have a lower priority than that, the opposite is true for lower.

The relative priority (if given) takes precedence over the base priority.

Parameters:

schema (Optional[Type[TypeVar(_S, bound= Schema)]]) – The schema to register.
priority (int) – Base priority level.
lower_priority (Union[None, Type[Schema], int, Iterable[Type[Schema]], Iterable[int]]) – Any other schemas that should have lower priority compared to the new schema.
higher_priority (Union[None, Type[Schema], int, Iterable[Type[Schema]], Iterable[int]]) – Any other schemas that should have higher priority compared to the new schema.
replace (bool) – Allow replacing existing registered schema with same name.

Return type:

Union[Callable[[Type[TypeVar(_S, bound= Schema)]], Type[TypeVar(_S, bound= Schema)]], Type[TypeVar(_S, bound= Schema)]]

Returns:

Decorator if schema was not given, else schema.

caches¶: An instance of marsh.utils.CachePool containing the caches used throughout marsh.schema

marsh.schema¶

`marsh.schema`¶