Skip to main content

Python HAL generation/parsing library

Project description

halogen

https://api.travis-ci.org/olegpidsadnyi/halogen.png https://pypip.in/v/halogen/badge.png https://coveralls.io/repos/olegpidsadnyi/halogen/badge.png?branch=master

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

halogen-0.0.3.tar.gz (6.9 kB view hashes)

Uploaded Source

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page