halogen 0.0.3

Python HAL generation/parsing library

halogen

Python HAL generation/parsing library.

Schemas can be defined to specify attributes to be exposed and a structure

Serialization

import halogen

spell = {
    "uid": "abracadabra",
    "name": "Abra Cadabra",
    "cost": 10,
}

class Spell(halogen.Schema):

    self = halogen.Link(URI("spells"), attr="uid")
    name = halogen.Attr()

serialized = Spell.serialize(spell)

This will produce HAL-like dictionary which can be serialized to json for the hal+json content type or to XML for the hal+xml content type.

{
    "_links": {
        "self": {"href": "spells/abracadabra"}
    },
    "name": "Abra Cadabra"
    // The extra wasn't in the schema and this way will be ignored
}

Embedded objects

import halogen

books = [
    {
        "id": "1",
        "name": "Game of Thrones",
    },
    {
        "id": "2",
        "name": "Harry Potter",
    }
]

class Book(halogen.Schema):

    self = halogen.Link(URI("books"), attr="id")
    name = halogen.Attr()

class BooksFeed(halogen.Schema):
    self = halogen.Link(URI("books"), attr=lambda value: "/")
    books = halogen.Embedded(halogen.types.List(Book))

feed = Spell.serialize(books)

The serialized data will look like this:

{
    "_links": {
        "self": {"href": "/books/"}
    },
    "_embedded": {
        "books": [
            {
                "_links": {
                    "self": {"href": "/books/1"}
                },
                "name": "Game of Thrones"

            },
            {
                "_links": {
                    "self": {"href": "/books/2"}
                },
                "name": "Harry Potter"
            }
        ]
    }
}

CURIEs

Curies can be declared in the global scope to be reused between schemas.

ACME = halogen.Curie(name="acme", href="/test/123")

data = {
    "warehouse": "/test/123",
}


class Schema(halogen.Schema):
    warehouse = halogen.Link(curie=ACME)

result = Schema.serialize(data)

Curies used in links or embedded will be collected and placed in the _links.curies section.

{
    _links: {
        curies: [{
            name: "acme",
            href: "/test/123"
        }],
        "acme:warehouse": {href: /test/123}
    }
}

Constant types

Sometimes it is convenient to render constants for example in links. In this case you can simply specify the constant value instead of the attribute type.

class Schema(halogen.Schema):
    self = halogen.Link("/test")

Deserialization

The HAL data can be deserialized into the output object. In case there are validation errors they will be collected and the ValidationError thrown.

import halogen

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

class Spell(halogen.Schema):

    self = halogen.Link(URI("spells"), attr="uid")
    name = halogen.Attr()

spell = {}
Spell.deserialize(hal, output=spell)

The deserialized data will look like this:

{
    "uid": "abracadabra",
    "name": "Abra Cadabra",
}

Error handling

The errors will be related to the attributes.

try:
    Spell.deserialize(hal, output=spell)
except halogen.ValidationError as e;
    print e.as_dict()

Changelog

0.0.3

• Support curies

0.0.2

• Deserialization implemented

• Docstrings updated

0.0.1

• Initial version