anyblok_marshmallow 1.3.0

Add validator, serializer and deserializer to AnyBlok

AnyBlok Marshmallow

Improve AnyBlok AnyBlok to add validator, serializer and deserializer schema with marshmallow.

This module is a wrapper of marshmallow-sqlalchemy, the goal is to give the SQLAlchemy Model build by AnyBlok to this librairy

AnyBlok Marshmallow is released under the terms of the Mozilla Public License.

See the latest documentation

Contents

• AnyBlok Marshmallow

• Front Matter

  • Project Homepage

  • Project Status

  • Installation

  • Unit Test

  • Dependencies

  • Contributing (hackers needed!)

  • Author

  • Contributors

  • Bugs

• Memento

  • Declare your AnyBlok model

  • Declare your schema

  • (De)serialize your data and validate it

  • Give the registry

    • Add the registry by the Meta

    • Add the registry during init

    • Add the registry by the context

    • Add the registry when the de(serialization or validatoris called

  • post_load_return_instance option

  • model option

  • only_primary_key option

• CHANGELOG

  • 1.3.0 (2017-12-23)

  • 1.2.0 (2017-11-30)

  • 1.1.0 (2017-11-02)

  • 1.0.2 (2017-10-25)

  • 1.0.0 (2017-10-24)

Front Matter

Information about the AnyBlok / Marshmallow project.

Project Homepage

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.

Project Status

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;

Installation

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.

Unit Test

Run the test with nose:

pip install nose
nosetests anyblok_marshmallow/tests

Dependencies

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.

Contributing (hackers needed!)

Anyblok / Marshmallow is at a very early stage, feel free to fork, talk with core dev, and spread the word!

Author

Jean-Sébastien Suzanne

Contributors

Anybox team:

• Jean-Sébastien Suzanne

Sensee team:

• Franck Bret

Bugs

Bugs and feature enhancements to AnyBlok should be reported on the Issue tracker.

Contents

• AnyBlok Marshmallow

• Front Matter

  • Project Homepage

  • Project Status

  • Installation

  • Unit Test

  • Dependencies

  • Contributing (hackers needed!)

  • Author

  • Contributors

  • Bugs

• Memento

  • Declare your AnyBlok model

  • Declare your schema

  • (De)serialize your data and validate it

  • Give the registry

    • Add the registry by the Meta

    • Add the registry during init

    • Add the registry by the context

    • Add the registry when the de(serialization or validatoris called

  • post_load_return_instance option

  • model option

  • only_primary_key option

• CHANGELOG

  • 1.3.0 (2017-12-23)

  • 1.2.0 (2017-11-30)

  • 1.1.0 (2017-11-02)

  • 1.0.2 (2017-10-25)

  • 1.0.0 (2017-10-24)

Memento

Declare your AnyBlok model

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

Declare your schema

from anyblok_marshmallow import ModelSchema
from anyblok_marshmallow.fields import 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(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
        # optionally return an AnyBlok model instance
        post_load_return_instance = True


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

(De)serialize your data and validate it

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

By default: the deserialization return a dict with deserialized data, here we get an instance of the model because the CustomerSchema add post_load_return_instance = True in their Meta

Give the registry

The schema need to have the registry.

If no registry found when the de(serialization) or validation then the RegistryNotFound exception will be raised.

Add the registry by the Meta

This is the solution given in the main exemple:

class CustomerSchema(ModelSchema):

    class Meta:
        model = 'Model.Customer'
        registry = registry

Add the registry during init

This solution is use during the instanciation

customer_schema = CustomerSchema(registry=registry)

Add the registry by the context

This solution is use during the instanciation or after

customer_schema = CustomerSchema(context={'registry': registry})

or

customer_schema = CustomerSchema()
customer_schema.context['registry'] = registry

Add the registry when the de(serialization or validatoris called

customer_schema.dump(customer, registry=registry)
customer_schema.load(dump_data, registry=registry)
customer_schema.validate(dump_data, registry=registry)

post_load_return_instance option

As the registry this option can be passed by initialization of the schema, by the context or during the call of methods

The value of this options can be:

• False: default, the output is a dict

• True: the output is an instance of the model. The primary keys must be in value

• array of string: the output is an instance of the model, each str entry must be an existing column

Warning

If the option is not False, and the instance can no be found, then the instance error will be added in the errors dict of the method

Warning

The post load is only for load method!!!

model option

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")

only_primary_key option

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)

Contents

• AnyBlok Marshmallow

• Front Matter

  • Project Homepage

  • Project Status

  • Installation

  • Unit Test

  • Dependencies

  • Contributing (hackers needed!)

  • Author

  • Contributors

  • Bugs

• Memento

  • Declare your AnyBlok model

  • Declare your schema

  • (De)serialize your data and validate it

  • Give the registry

    • Add the registry by the Meta

    • Add the registry during init

    • Add the registry by the context

    • Add the registry when the de(serialization or validatoris called

  • post_load_return_instance option

  • model option

  • only_primary_key option

• CHANGELOG

  • 1.3.0 (2017-12-23)

  • 1.2.0 (2017-11-30)

  • 1.1.0 (2017-11-02)

  • 1.0.2 (2017-10-25)

  • 1.0.0 (2017-10-24)

CHANGELOG

1.3.0 (2017-12-23)

• [ADD] unittest on some case

• [FIX] AnyBlok field.Function is return as MarshMallow fields.Raw

• [ADD] fields.File, type to encode and decode to/from base 64

1.2.0 (2017-11-30)

• [REF] decrease complexity

• [IMP] Add validates_schema on ModelSchema to automaticly check if the field exist on the model

1.1.0 (2017-11-02)

• Add option put only the primary keys

• Fix the Front page

• REF model option, can be given by another way than Meta

• Put RegistryNotFound in exceptions

• Add Nested field, this field is not and have not to be cached

1.0.2 (2017-10-25)

• Fix pypi documentation

1.0.0 (2017-10-24)

• Add marshmallow schema for AnyBlok for:

  • Serialization

  • Deserialization

  • Validation