halogen 1.7.0

Attr()

模式中属性成员的名称是结果序列化到的键的名称。默认情况下，使用相同的属性名称访问源模型。

示例

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)

结果

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

Attr("const")

如果属性表示一个常量，则可以将值指定为第一个参数。这个第一个参数是属性的类型的实例或子类。如果类型不是 halogen.types.Type 的实例或子类，则会被忽略。

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)

结果

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

在某些情况下，也可以将 attr 指定为可调用的函数，它返回一个常量值。

Attr(attr="foo")

如果属性名称与您的模型不匹配，则可以覆盖它

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)

结果

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

attr 参数接受源属性名称的字符串或点分隔的属性路径。这对于嵌套字典、相关对象和 Python 属性都有效。

import halogen

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

Attr(attr=lambda value: value)

attr 参数接受可调用的函数，该函数接受整个源模型并可以访问必要的属性。您可以通过传递函数或 lambda 来返回所需值，该值也可以只是一个常量。

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)

结果

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

属性作为装饰器

有时访问器函数太大，不能使用 lambda。在这种情况下，可以将类的方法装饰为获取器访问器。

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)

如果模式用于双向序列化和反序列化，则可以传递 halogen.schema.Accessor，其中指定了 getter 和 setter。 Getter 是一个字符串或可调用的函数，用于从模型中获取值，而 setter 是一个字符串或可调用的函数，它知道反序列化的值应该存储在哪里。

Attr(Type())

属性获取值后，将其传递给其类型以完成序列化。卤素提供基本类型，例如 halogen.types.List 以实现值或模式的列表。模式也是一种类型，可以传递给属性以实现复杂结构。

示例

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)

结果

{
    "_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]))

类型可以获取可选的 validators 参数，它是一个包含 halogen.validators.Validator 对象的列表，其单个接口方法 validate 将在反序列化期间调用给定值。如果值无效，应引发 halogen.exceptions.ValidationError。卤素提供基本验证器，例如 halogen.validators.Range 以验证值是否在特定范围内。

Attr(default=value)

如果属性无法获取，将使用提供的 default 值；如果 default 值是可调用的，则将调用它以获取默认值。

Attr(required=False)

默认情况下，属性是必需的，因此在序列化期间无法获取属性且未提供默认值时，将引发异常（AttributeError 或 KeyError，具体取决于输入）。可以通过将 required=False 传递给属性构造函数来放宽此限制。对于反序列化，适用相同的逻辑，但异常类型将变为 halogen.exceptions.ValidationError 以便人类可读（参见 反序列化）。

类型子类化

在您的应用程序中常见的类型可以在 schema 之间共享。这可能包括日期时间类型、特定 URL 类型、国际化字符串以及任何需要特定格式的其他表示。

Type.serialize

Type.serialize 的默认实现是一个绕过。

类型的序列化方法是序列化值时的最后一次转换机会

示例

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)

结果

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

可空类型

如果访问器返回 None 且不希望类型或嵌套 schema 进行进一步序列化，则可以将类型包装到 Nullable 类型中。

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

结果

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

CURIE

CURIE 提供了对资源文档的链接。

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 也可以是链接的参数

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” 属性是可选的。它是一个对象，其属性名称是链接关系类型（如 [RFC5988] 中定义的）和值是资源对象或资源对象的数组。

嵌入资源可以是来自目标 URI 的表示的全版本、部分版本或不一致版本。

为了在您的模式中创建 _embedded，您应该使用 halogen.Embedded。

示例

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)

结果

{
    "_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"}
    }
}

默认情况下，嵌入式资源是必需的，您可以通过将 required=False 传递给构造函数来使它们不是必需的，并且在序列化中会省略空值。

import halogen

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

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

结果

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

提供上下文

在序列化或反序列化对象时，并非所有用于（反）序列化的数据都存在于对象本身中。您可以将此数据作为单独的关键字参数传递给 serialize 或 deserialize，以提供上下文。此上下文将在所有嵌套模式、类型和属性中可用。

序列化示例

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

结果

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

反序列化示例

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

结果

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