halogen 2.0.0

Attr()

The name of the attribute member in the schema is the name of the key the result will be serialized to. By default the same attribute name is used to access the source model.

Example:

import halogen
from flask import url_for

class Spell(object):
    uid = "abracadabra"
    name = "Abra Cadabra"
    cost = 10

spell = Spell()

class SpellSchema(halogen.Schema):
    self = halogen.Link(attr=lambda spell: url_for("spell.get" uid=spell.uid))
    name = halogen.Attr()

serialized = SpellSchema.serialize(spell)

Result:

{
    "_links": {
        "self": {"href": "/spells/abracadabra"}
    },
    "name": "Abra Cadabra"
}

Attr(“const”)

In case the attribute represents a constant the value can be specified as a first parameter. This first parameter is a type of the attribute. If the type is not a instance or subclass of a halogen.types.Type it will be bypassed.

import halogen
from flask import url_for

class Spell(object):
    uid = "abracadabra"
    name = "Abra Cadabra"
    cost = 10

spell = Spell()

class SpellSchema(halogen.Schema):
    self = halogen.Link(attr=lambda spell: url_for("spell.get" uid=spell.uid))
    name = halogen.Attr("custom name")

serialized = SpellSchema.serialize(spell)

Result:

{
    "_links": {
        "self": {"href": "/spells/abracadabra"}
    },
    "name": "custom name"
}

In some cases also the attr can be specified to be a callable that returns a constant value.

Attr(attr=”foo”)

In case the attribute name doesn’t correspond your model you can override it:

import halogen
from flask import url_for

class Spell(object):
    uid = "abracadabra"
    title = "Abra Cadabra"
    cost = 10

spell = Spell()

class SpellSchema(halogen.Schema):
    self = halogen.Link(attr=lambda spell: url_for("spell.get" uid=spell.uid))
    name = halogen.Attr(attr="title")

serialized = SpellSchema.serialize(spell)

Result:

{
    "_links": {
        "self": {"href": "/spells/abracadabra"}
    },
    "name": "Abra Cadabra"
}

The attr parameter accepts strings of the source attribute name or even dot-separated path to the attribute. This works for both: nested dictionaries or related objects an Python properties.

import halogen

class SpellSchema(halogen.Schema):
    name = halogen.Attr(attr="path.to.my.attribute")

Attr(attr=lambda value: value)

The attr parameter accepts callables that take the entire source model and can access the neccessary attribute. You can pass a function or lambda in order to return the desired value which also can be just a constant.

import halogen
from flask import url_for

class Spell(object):
    uid = "abracadabra"
    title = "Abra Cadabra"
    cost = 10

spell = Spell()

class SpellSchema(halogen.Schema):
    self = halogen.Link(attr=lambda spell: url_for("spell.get" uid=spell.uid))
    name = halogen.Attr(attr=lambda value: value.title)

serialized = SpellSchema.serialize(spell)

Result:

{
    "_links": {
        "self": {"href": "/spells/abracadabra"}
    },
    "name": "Abra Cadabra"
}

Attribute as a decorator

Sometimes accessor functions are too big for lambdas. In this case it is possible to decorate a method of the class to be a getter accessor.

import halogen

class ShoppingCartSchema(halogen.Schema):

    @halogen.attr(AmountType(), default=None)
    def total(obj):
        return sum(
            (item.amount for item in obj.items),
            0,
        )

    @total.setter
    def set_total(obj, value):
        obj.total = value

Attr(attr=Acccessor)

In case the schema is used for both directions to serialize and to deserialize the halogen.schema.Accessor can be passed with both getter and setter specified. Getter is a string or callable in order to get the value from a model, and setter is a string or callable that knows where the deserialized value should be stored.

Attr(Type())

After the attibute gets the value it passes it to it’s type in order to complete the serialization. Halogen provides basic types for example halogen.types.List to implement lists of values or schemas. Schema is also a Type and can be passed to the attribute to implement complex structures.

Example:

import halogen
from flask import url_for

class Book(object):
    uid = "good-book-uid"
    title = "Harry Potter and the Philosopher's Stone"
    genres = [
        {"uid": "fantasy-literature", "title": "fantasy literature"},
        {"uid": "mystery", "title": "mystery"},
        {"uid": "adventure", "title": "adventure"},
    ]

book = Book()

class GenreSchema(halogen.Schema):
    self = halogen.Link(attr=lambda genre: url_for("genre.get" uid=genre['uid']))
    title = halogen.Attr()

class BookSchema(halogen.Schema):
    self = halogen.Link(attr=lambda book: url_for("book.get" uid=book.uid))
    title = halogen.Attr()
    genres = halogen.Attr(halogen.types.List(GenreSchema))

serialized = BookSchema.serialize(book)

Result:

{
    "_links": {
        "self": {"href": "good-book-uid"}
    },
    "genres": [
        {"_links": {"self": {"href": "fantasy-literature"}}, "title": "fantasy literature"},
        {"_links": {"self": {"href": "mystery"}}, "title": "mystery"},
        {"_links": {"self": {"href": "adventure"}}, "title": "adventure"}
    ],
    "title": "Harry Potter and the Philosopher's Stone"
}

Attr(Type(validators=[validator]))

Type gets optional validators parameter, which is a list of halogen.validators.Validator objects whose single interface method validate will be called for the given value during the deserialization. If the value is not valid, halogen.exceptions.ValidationError should be raised. Halogen provides basic validators, for example halogen.validators.Range to validate that the values is in certain range.

Attr(default=value)

If an attribute cannot be taken, provided default value will be used; if default value is a callable, it will be called to get the default value.

Attr(required=False)

By default, attributes are required, so when an attribute can not be taken during the serialization and default is not provided, an exception will be raised (AttributeError or KeyError, depending on the input). It’s possible to relax this restriction by passing required=False to the attribute constructor. For deserialization, the same logic applies, but the exception type will be halogen.exceptions.ValidationError for human readability (see Deserialization).

Subclassing types

Types that are common in your application can be shared between schemas. This could be the datetime type, specific URL type, internationalized strings and any other representation that requires specific format.

Type.serialize

The default implementation of the Type.serialize is a bypass.

Serialization method of a type is the last opportunity to convert the value that is being serialized:

Example:

import halogen

class Amount(object):
    currency = "EUR"
    amount = 1


class AmountType(halogen.types.Type):
    def serialize(self, value):

        if value is None or not isinstance(value, Amount):
            return None

        return {
            "currency": value.currency,
            "amount": value.amount
        }


class Product(object):
    name = "Milk"

    def __init__(self):
        self.price = Amount()

product = Product()


class ProductSchema(halogen.Schema):

    name = halogen.Attr()
    price = halogen.Attr(AmountType())

serialized = ProductSchema.serialize(product)

Result:

{
    "name": "Milk",
    "price": {
        "amount": 1,
        "currency": "EUR"
    }
}

Nullable types

In case the accessor returns None and the further serialization by a type or a nested schema is not desired the type can be wrapped into Nullable type.

import halogen


class FreeProduct(object):
    """A free product, that doesn't have a price."""

    price = None


class AmountSchema(halogen.Schema):

    currency = halogen.Attr(required=True, default="USD")
    amount = halogen.Attr(required=True, default=0)


class FreeProductSchema(halogen.Schema):

    price_null = halogen.Attr(halogen.types.Nullable(AmountType()), attr="price")
    price_zero = halogen.Attr(AmountType(), attr="price")


serialized = FreeProductSchema.serialize(FreeProduct())

Result:

{
    "price_null": None,
    "price_zero": {
        "amount": 0,
        "currency": "USD"
    }
}

CURIE

CURIEs are providing links to the resource documentation.

import halogen

doc = halogen.Curie(
    name="doc,
    href="http://haltalk.herokuapp.com/docs/{rel}",
    templated=True
)

class BlogSchema(halogen.Schema):

    lastest_post = halogen.Link(attr="/posts/latest", curie=doc)

{
    "_links": {
        "curies": [
            {
              "name": "doc",
              "href": "http://haltalk.herokuapp.com/docs/{rel}",
              "templated": true
            }
        ],

        "doc:latest_posts": {
            "href": "/posts/latest"
        }
    }
}

Schema also can be a param to link

import halogen

class BookLinkSchema(halogen.Schema):
    href = halogen.Attr("/books")

class BookSchema(halogen.Schema):

    books = halogen.Link(BookLinkSchema)

serialized = BookSchema.serialize({"books": ""})

{
    "_links": {
        "books": {
            "href": "/books"
        }
    }
}

Embedded

The reserved “_embedded” property is OPTIONAL. It is an object whose property names are link relation types (as defined by [RFC5988]) and values are either a Resource Object or an array of Resource Objects.

Embedded Resources MAY be a full, partial, or inconsistent version of the representation served from the target URI.

For creating _embedded in your schema you should use halogen.Embedded.

Example:

import halogen

em = halogen.Curie(
    name="em",
    href="https://docs.event-manager.com/{rel}.html",
    templated=True,
    type="text/html"
)


class EventSchema(halogen.Schema):
    self = halogen.Link("/events/activity-event")
    collection = halogen.Link("/events/activity-event", curie=em)
    uid = halogen.Attr()


class PublicationSchema(halogen.Schema):
    self = halogen.Link(attr=lambda publication: "/campaigns/activity-campaign/events/activity-event")
    event = halogen.Link(attr=lambda publication: "/events/activity-event", curie=em)
    campaign = halogen.Link(attr=lambda publication: "/campaign/activity-event", curie=em)


class EventCollection(halogen.Schema):
    self = halogen.Link("/events")
    events = halogen.Embedded(halogen.types.List(EventSchema), attr=lambda collection: collection["events"], curie=em)
    publications = halogen.Embedded(
        attr_type=halogen.types.List(PublicationSchema),
        attr=lambda collection: collection["publications"],
        curie=em
    )


collections = {
    'events': [
        {"uid": 'activity-event'}
    ],
    'publications': [
        {
            "event": {"uid": "activity-event"},
            "campaign": {"uid": "activity-campaign"}
        }
    ]
}

serialized = EventCollection.serialize(collections)

Result:

{
    "_embedded": {
        "em:events": [
            {
                "_links": {
                    "curies": [
                        {
                            "href": "https://docs.event-manager.com/{rel}.html",
                            "name": "em",
                            "templated": true,
                            "type": "text/html"
                        }
                    ],
                    "em:collection": {"href": "/events/activity-event"},
                    "self": {"href": "/events/activity-event"}
                },
                "uid": "activity-event"
            }
        ],
        "em:publications": [
            {
                "_links": {
                    "curies": [
                        {
                            "href": "https://docs.event-manager.com/{rel}.html",
                            "name": "em",
                            "templated": true,
                            "type": "text/html"
                        }
                    ],
                    "em:campaign": {"href": "/campaign/activity-event"},
                    "em:event": {"href": "/events/activity-event"},
                    "self": {"href": "/campaigns/activity-campaign/events/activity-event"}
                }
            }
        ]
    },
    "_links": {
        "curies": [
            {
                "href": "https://docs.event-manager.com/{rel}.html",
                "name": "em",
                "templated": true,
                "type": "text/html"
            }
        ],
        "self": {"href": "/events"}
    }
}

By default, embedded resources are required, you can make them not required by passing required=False to the constructor, and empty values will be omitted in the serialization:

import halogen

class Schema(halogen.Schema):
    user1 = halogen.Embedded(PersonSchema, required=False)
    user2 = halogen.Embedded(PersonSchema)

serialized = Schema.serialize({'user2': Person("John", "Smith")})

Result:

{
    "_embedded": {
        "user2": {
            "name": "John",
            "surname": "Smith"
        }
    }
}

Providing context

When serializing or deserializing an object, not all data required for (de)serialization may be available in the object itself. You can pass this data as separate keyword arguments to serialize or deserialize to provide context. This context will be available in all nested schema, types and attributes.

Serialize example:

class ErrorSchema(halogen.Schema):
    message = halogen.Attr(
        attr=lambda error, language: error["message"][language]
    )

error = ErrorSchema.serialize({
    "message": {
        "dut": "Ongeldig e-mailadres",
        "eng": "Invalid email address"
    }
}, language="dut")

print error

Result:

{"message": "Ongeldig e-mailadres"}

Deserialize example:

import halogen


class Book(halogen.Schema):

    @halogen.attr()
    def title(obj, language):
        return obj['title'][language]

class Author(halogen.Schema):
    name = halogen.Attr(attr='author.name')
    books = halogen.Attr(
        halogen.types.List(Book),
        attr='author.books',
    )

author = Author.deserialize({
    "author": {
        "name": "Roald Dahl",
        "books": [
            {
                "title": {
                    "dut": "De Heksen",
                    "eng": "The Witches"
                }
            },
            {
                "title": {
                    "dut": "Sjakie en de chocoladefabriek",
                    "eng": "Charlie and the Chocolate Factory"
                }
            }
        ]
    }
}, language="eng")

print author

Result:

{
    "name": "Roald Dahl",
    "books": [
        {"title": "The Witches"},
        {"title": "Charlie and the Chocolate Factory"}
    ]
}