Contents
Information about the AnyBlok / Marshmallow project.
AnyBlok is hosted on github - the main project page is at https://github.com/AnyBlok/AnyBlok_Marshmallow. Source code is tracked here using GIT.
Releases and project status are available on Pypi at http://pypi.python.org/pypi/anyblok_marshmallow.
The most recent published version of this documentation should be at http://doc.anyblok-marshmallow.anyblok.org.
AnyBlok with Marshmallow is currently in beta status and is expected to be fairly stable. Users should take care to report bugs and missing features on an as-needed basis. It should be expected that the development version may be required for proper implementation of recently repaired issues in between releases;
Install released versions of AnyBlok from the Python package index with pip or a similar tool:
pip install anyblok_marshmallow
Installation via source distribution is via the setup.py script:
python setup.py install
Installation will add the anyblok commands to the environment.
AnyBlok works with Python 3.3 and later. The install process will ensure that AnyBlok, marshmallow and marshmallow-sqlalchemy are installed, in addition to other dependencies. The latest version of them is strongly recommended.
Anyblok / Marshmallow is at a very early stage, feel free to fork, talk with core dev, and spread the word!
Bugs and feature enhancements to AnyBlok should be reported on the Issue tracker.
Contents
from anyblok.column import Integer, String
from anyblok.relationship import Many2One, Many2Many
from anyblok import Declarations
@Declarations.register(Declarations.Model)
class City:
id = Integer(primary_key=True)
name = String(nullable=False)
zipcode = String(nullable=False)
def __repr__(self):
return '<City(name={self.name!r})>'.format(self=self)
@Declarations.register(Declarations.Model)
class Tag:
id = Integer(primary_key=True)
name = String(nullable=False)
def __repr__(self):
return '<Tag(name={self.name!r})>'.format(self=self)
@Declarations.register(Declarations.Model)
class Customer:
id = Integer(primary_key=True)
name = String(nullable=False)
tags = Many2Many(model=Declarations.Model.Tag)
def __repr__(self):
return '<Customer(name={self.name!r}, '
'tags={self.tags!r})>'.format(self=self)
@Declarations.register(Declarations.Model)
class Address:
id = Integer(primary_key=True)
street = String(nullable=False)
city = Many2One(model=Declarations.Model.City, nullable=False)
customer = Many2One(
model=Declarations.Model.Customer, nullable=False,
one2many="addresses")
Warning
The AnyBlok model must be declared in a blok
from anyblok_marshmallow import ModelSchema, PostLoadSchema, Nested
class CitySchema(ModelSchema):
class Meta:
model = 'Model.City'
class TagSchema(ModelSchema):
class Meta:
model = 'Model.Tag'
class AddressSchema(ModelSchema):
# follow the relationship Many2One and One2One
city = Nested(CitySchema)
class Meta:
model = 'Model.Address'
class CustomerSchema(PostLoadSchema, ModelSchema):
# follow the relationship One2Many and Many2Many
# - the many=True is required because it is *2Many
# - exclude is used to forbid the recurse loop
addresses = Nested(AddressSchema, many=True, exclude=('customer', ))
tags = Nested(TagSchema, many=True)
class Meta:
model = 'Model.Customer'
# optionally attach an AnyBlok registry
# to use for serialization, desarialization and validation
registry = registry
customer_schema = CustomerSchema()
Note
New in version 1.1.0 the Nested field must come from anyblok_marshmallow, because marshmallow cache the Nested field with the context. And the context is not propagated again if it changed
Note
Ref in version 1.4.0, post_load_return_instance was replaced by the mixin class
PostLoadSchema
customer = registry.Customer.insert(name="JS Suzanne")
tag1 = registry.Tag.insert(name="tag 1")
customer.tags.append(tag1)
tag2 = registry.Tag.insert(name="tag 2")
customer.tags.append(tag2)
rouen = registry.City.insert(name="Rouen", zipcode="76000")
paris = registry.City.insert(name="Paris", zipcode="75000")
registry.Address.insert(customer=customer, street="Somewhere", city=rouen)
registry.Address.insert(customer=customer, street="Another place", city=paris)
dump_data = customer_schema.dump(customer).data
# {
# 'id': 1,
# 'name': 'JS Suzanne',
# 'tags': [
# {
# 'id': 1,
# 'name': 'tag 1',
# },
# {
# 'id': 2,
# 'name': 'tag 2',
# },
# ],
# 'addresses': [
# {
# 'id': 1
# 'street': 'Somewhere'
# 'city': {
# 'id': 1,
# 'name': 'Rouen',
# 'zipcode': '76000',
# },
# },
# {
# 'id': 2
# 'street': 'Another place'
# 'city': {
# 'id': 2,
# 'name': 'Paris',
# 'zipcode': '75000',
# },
# },
# ],
# }
customer_schema.load(dump_data).data
# <Customer(name='JS Suzanne' tags=[<Tag(name='tag 1')>, <Tag (name='tag 2')>])>
errors = customer_schema.validate(dump_data)
# dict with all the validating errors
Note
We have an instance of the model cause of the mixin PostLoadSchema
The schema need to have the registry.
If no registry found when the de(serialization) or validation then the RegistryNotFound exception will be raised.
This is the solution given in the main exemple:
class CustomerSchema(ModelSchema):
class Meta:
model = 'Model.Customer'
registry = registry
This solution is use during the instanciation
customer_schema = CustomerSchema(registry=registry)
This solution is use during the instanciation or after
customer_schema = CustomerSchema(context={'registry': registry})
or
customer_schema = CustomerSchema()
customer_schema.context['registry'] = registry
customer_schema.dump(customer, registry=registry)
customer_schema.load(dump_data, registry=registry)
customer_schema.validate(dump_data, registry=registry)
This option add in the model name. As the registry, this option can be passed by definition, initialization, context or during the call of the (de)serialization / validation
class AnySchema(ModelSchema):
class Meta:
model = "Model.Customer"
or
any_schema = AnySchema(model="Model.customer")
or
any_schema.context['model'] = "Model.Customer"
or
any_schema.dump(instance, model="Model.Customer")
any_schema.load(dump_data, model="Model.Customer")
any_schema.validate(dump_data, model="Model.Customer")
This option add in the only argument the primary keys of the model. As the registry, this option can be passed by definition, initialization, context or during the call of the (de)serialization / validation
class CustomerSchema(ModelSchema):
class Meta:
model = "Model.Customer"
only_primary_key = True
or
customer_schema = CustomerSchema(only_primary_key=True)
or
customer_schema.context['only_primary_key'] = True
or
customer_schema.dump(instance, only_primary_key=True)
customer_schema.load(dump_data, only_primary_key=True)
customer_schema.validate(dump_data, only_primary_key=True)
This option force the generated fields, and only them to be requried.
class CustomerSchema(ModelSchema):
class Meta:
model = "Model.Customer"
required_fields = True
# or required_fields = [ list of fieldname ]
or
customer_schema = CustomerSchema(required_fields=True)
or
customer_schema.context['required_fields'] = True
or
customer_schema.load(dump_data, required_fields=True)
customer_schema.validate(dump_data, required_fields=True)
Note
All the attributes can take True or the list of the fieldname to be required
This field allow the schema to inspect an AnyBlok.fields.Json in an any specific instance to validate the value.
AnyBlok models:
@register(Model)
class Template:
name = anyblok.column.String(primary_key=True)
properties = anyblok.column.Json(defaumt={})
@register(Model)
class SaleOrder:
id = anyblok.column.Integer(primary_key=True)
number = anyblok.column.Integer(nullable=False)
discount = anyblok.column.Integer()
AnyBlok / Marchmallow schema:
class SaleOrderSchema(ModelSchema):
class Meta:
model = 'Model.SaleOrder'
discount = JsonCollection(
fieldname='properties',
keys=['allowed_discount'],
cls_or_instance_type=marshmallow.fields.Integer(required=True)
)
Use:
goodcustomer = registry.Template.insert(
name='Good customer',
properties={'allowed_discount': [10, 15, 30]
)
customer = registry.Template.insert(
name='Customer',
properties={'allowed_discount': [0, 5, 10]
)
badcustomer = registry.Template.insert(
name='Bad customer',
properties={'allowed_discount': [0]
)
schema = SaleOrderSchema(registry=registry)
--------------------------
data, errors = schema.load(
{
number='SO0001',
discount=10,
},
instances={'default': goodcustomer}
)
==> error = {}
--------------------------
data, errors = schema.load(
{
number='SO0001',
discount=10,
},
instances={'default': customer}
)
==> error = {}
--------------------------
data, errors = schema.load(
{
number='SO0001',
discount=10,
},
instances={'default': badcustomer}
)
==> error = {'discount': ['Not a valid choice']}
Contents
anyblok_marshmallow.exceptions.RegistryNotFoundBases: Exception
Exception raised when no registry is found to build schema
with_traceback()Exception.with_traceback(tb) – set self.__traceback__ to tb and return self.
anyblok_marshmallow.fields.Nested(nested, default=<marshmallow.missing>, exclude=(), only=None, **kwargs)Bases: marshmallow.fields.Nested
Inherit marshmallow fields.Nested
contextThe context dictionary for the parent Schema.
deserialize(value, attr=None, data=None)Deserialize value.
| Raises: | ValidationError – If an invalid value is passed or if a required value is missing. |
|---|
fail(key, **kwargs)A helper method that simply raises a ValidationError.
get_value(attr, obj, accessor=None, default=<marshmallow.missing>)Return the value for a given key from an object.
rootReference to the Schema that this field belongs to even if it is buried in a List. Return None for unbound fields.
schemaOverload the super property to remove cache
it is the only way to propagate the context at each call
serialize(attr, obj, accessor=None)Pulls the value for the given key from the object, applies the field’s formatting and returns the result.
| Parameters: | |
|---|---|
| Raises: | ValidationError – In case of formatting problem |
anyblok_marshmallow.fields.File(default=<marshmallow.missing>, attribute=None, load_from=None, dump_to=None, error=None, validate=None, required=False, allow_none=None, load_only=False, dump_only=False, missing=<marshmallow.missing>, error_messages=None, **metadata)Bases: marshmallow.fields.Field
contextThe context dictionary for the parent Schema.
deserialize(value, attr=None, data=None)Deserialize value.
| Raises: | ValidationError – If an invalid value is passed or if a required value is missing. |
|---|
fail(key, **kwargs)A helper method that simply raises a ValidationError.
get_value(attr, obj, accessor=None, default=<marshmallow.missing>)Return the value for a given key from an object.
rootReference to the Schema that this field belongs to even if it is buried in a List. Return None for unbound fields.
serialize(attr, obj, accessor=None)Pulls the value for the given key from the object, applies the field’s formatting and returns the result.
| Parameters: | |
|---|---|
| Raises: | ValidationError – In case of formatting problem |
anyblok_marshmallow.fields.Text(default=<marshmallow.missing>, attribute=None, load_from=None, dump_to=None, error=None, validate=None, required=False, allow_none=None, load_only=False, dump_only=False, missing=<marshmallow.missing>, error_messages=None, **metadata)Bases: marshmallow.fields.String
Simple field use to distinct by the class String and Text
contextThe context dictionary for the parent Schema.
deserialize(value, attr=None, data=None)Deserialize value.
| Raises: | ValidationError – If an invalid value is passed or if a required value is missing. |
|---|
fail(key, **kwargs)A helper method that simply raises a ValidationError.
get_value(attr, obj, accessor=None, default=<marshmallow.missing>)Return the value for a given key from an object.
rootReference to the Schema that this field belongs to even if it is buried in a List. Return None for unbound fields.
serialize(attr, obj, accessor=None)Pulls the value for the given key from the object, applies the field’s formatting and returns the result.
| Parameters: | |
|---|---|
| Raises: | ValidationError – In case of formatting problem |
anyblok_marshmallow.fields.JsonCollection(fieldname=None, keys=None, instance='default', cls_or_instance_type=<class 'marshmallow.fields.String'>, *args, **kwargs)Bases: marshmallow.fields.Field
contextThe context dictionary for the parent Schema.
deserialize(value, attr=None, data=None)Deserialize value.
| Raises: | ValidationError – If an invalid value is passed or if a required value is missing. |
|---|
fail(key, **kwargs)A helper method that simply raises a ValidationError.
get_value(attr, obj, accessor=None, default=<marshmallow.missing>)Return the value for a given key from an object.
rootReference to the Schema that this field belongs to even if it is buried in a List. Return None for unbound fields.
serialize(attr, obj, accessor=None)Pulls the value for the given key from the object, applies the field’s formatting and returns the result.
| Parameters: | |
|---|---|
| Raises: | ValidationError – In case of formatting problem |
anyblok_marshmallow.fields.Country(default=<marshmallow.missing>, attribute=None, load_from=None, dump_to=None, error=None, validate=None, required=False, allow_none=None, load_only=False, dump_only=False, missing=<marshmallow.missing>, error_messages=None, **metadata)Bases: marshmallow.fields.String
contextThe context dictionary for the parent Schema.
deserialize(value, attr=None, data=None)Deserialize value.
| Raises: | ValidationError – If an invalid value is passed or if a required value is missing. |
|---|
fail(key, **kwargs)A helper method that simply raises a ValidationError.
get_value(attr, obj, accessor=None, default=<marshmallow.missing>)Return the value for a given key from an object.
rootReference to the Schema that this field belongs to even if it is buried in a List. Return None for unbound fields.
serialize(attr, obj, accessor=None)Pulls the value for the given key from the object, applies the field’s formatting and returns the result.
| Parameters: | |
|---|---|
| Raises: | ValidationError – In case of formatting problem |
anyblok_marshmallow.fields.Country(default=<marshmallow.missing>, attribute=None, load_from=None, dump_to=None, error=None, validate=None, required=False, allow_none=None, load_only=False, dump_only=False, missing=<marshmallow.missing>, error_messages=None, **metadata)Bases: marshmallow.fields.String
contextThe context dictionary for the parent Schema.
deserialize(value, attr=None, data=None)Deserialize value.
| Raises: | ValidationError – If an invalid value is passed or if a required value is missing. |
|---|
fail(key, **kwargs)A helper method that simply raises a ValidationError.
get_value(attr, obj, accessor=None, default=<marshmallow.missing>)Return the value for a given key from an object.
rootReference to the Schema that this field belongs to even if it is buried in a List. Return None for unbound fields.
serialize(attr, obj, accessor=None)Pulls the value for the given key from the object, applies the field’s formatting and returns the result.
| Parameters: | |
|---|---|
| Raises: | ValidationError – In case of formatting problem |
anyblok_marshmallow.schema.update_from_kwargs(*entries)decorator to get temporaly the value in kwargs and put it in schema
| Params entries: | array ok entry name to take from the kwargs |
|---|
anyblok_marshmallow.schema.format_fields(x)remove the anyblok prefix form the field name
anyblok_marshmallow.schema.ModelConverter(schema_cls=None)Bases: marshmallow_sqlalchemy.convert.ModelConverter
Overwrite the ModelConverter class of marshmallow-sqlalchemy
The goal if to fix the fieldname, because they are prefixed.
fields_for_model(Model, **kwargs)Overwrite the method and remove prefix of the field name
anyblok_marshmallow.schema.ModelSchemaOpts(meta, *args, **kwargs)Bases: marshmallow.schema.SchemaOpts
Model schema option for Model schema
Add get option from the Meta:
anyblok_marshmallow.schema.ModelSchema(*args, **kwargs)Bases: marshmallow.schema.Schema
A marshmallow schema based on the AnyBlok Model
Wrap the real schema, because at the instanciation the registry is not available
MetaBases: object
Options object for a Schema.
Example usage:
class Meta:
fields = ("id", "email", "date_created")
exclude = ("password", "secret_attribute")
Available options:
fields: Tuple or list of fields to include in the serialized result.additional: Tuple or list of fields to include in addition to theadditional and fields are
mutually-exclusive options.include: Dictionary of additional fields to include in the schema. It isexclude: Tuple or list of fields to exclude in the serialized result.dateformat: Date format for all DateTime fields that do not have theirstrict: If True, raise errors during marshalling rather thanjson_module: JSON module to use for loads and dumps.json module in the stdlib.ordered: If True, order serialization output according to theindex_errors: If True, errors dictionaries will include the indexload_only: Tuple or list of fields to exclude from serialized results.dump_only: Tuple or list of fields to exclude from deserializationOPTIONS_CLASSalias of ModelSchemaOpts
accessor(func)Decorator that registers a function for pulling values from an object
to serialize. The function receives the Schema instance, the
key of the value to get, the obj to serialize, and an optional
default value.
Deprecated since version 2.0.0: Set the error_handler class Meta option instead.
dumps(obj, many=None, update_fields=True, *args, **kwargs)Same as dump(), except return a JSON-encoded string.
| Parameters: |
|
|---|---|
| Returns: | A tuple of the form ( |
| Return type: | MarshalResult, a collections.namedtuple |
New in version 1.0.0.
error_handler(func)Decorator that registers an error handler function for the schema.
The function receives the Schema instance, a dictionary of errors,
and the serialized object (if serializing data) or data dictionary (if
deserializing data) as arguments.
Example:
class UserSchema(Schema):
email = fields.Email()
@UserSchema.error_handler
def handle_errors(schema, errors, obj):
raise ValueError('An error occurred while marshalling {}'.format(obj))
user = User(email='invalid')
UserSchema().dump(user) # => raises ValueError
UserSchema().load({'email': 'bademail'}) # raises ValueError
New in version 0.7.0.
Deprecated since version 2.0.0: Set the error_handler class Meta option instead.
generate_marsmallow_instance()Generate the real mashmallow-sqlalchemy schema
get_attribute(attr, obj, default)Defines how to pull values from an object to serialize.
New in version 2.0.0.
handle_error(error, data)Custom error handler function for the schema.
| Parameters: |
|
|---|
New in version 2.0.0.
loads(json_data, many=None, *args, **kwargs)Same as load(), except it takes a JSON string as input.
| Parameters: |
|
|---|---|
| Returns: | A tuple of the form ( |
| Return type: | UnmarshalResult, a collections.namedtuple |
New in version 1.0.0.
on_bind_field(field_name, field_obj)Hook to modify a field when it is bound to the Schema. No-op by default.
schemaproperty to get the real schema
Contents
anyblok.column.Textanyblok.column.Emailanyblok.column.URLanyblok.column.PhoneNumberanyblok.column.Countryvalidates_schema on ModelSchema to automaticly check
if the field exist on the model