API

flask_hal

Flask-HAL provides support for the HAL Specification within Flask allowing you to build REST API responses which fulfil this specification.

Read more at the Official Draft

class flask_hal.HAL(app=None, response_class=None)

Bases: object

Enables Flask-HAL integration into Flask Applications, either by the Application Factory Pattern or directly into an already created Flask Application instance.

This will set a custom response_class for the Application which handles the conversion of a HAL document response from a view into it’s JSON representation.

__init__(app=None, response_class=None)

Initialise Flask-HAL with a Flask Application. Acts as a proxy to flask_hal.HAL.init_app().

Example

>>> from flask import Flask
>>> from flask_hal import HAL
>>> app = Flask(__name__)
>>> HAL(app=app)

Keyword Arguments:  

• app (flask.app.Flask) – Optional Flask application instance
• response_class (class) – Optional custom response_class

init_app(app, response_class=None)

Initialise Flask-HAL with a Flask Application. This is designed to be used with the Flask Application Factory Pattern.

Example

>>> from flask import Flask
>>> from flask_hal import HAL
>>> app = Flask(__name__)
>>> HAL().init_app(app)

Parameters:app (flask.app.Flask) – Flask application instance Keyword Arguments:  response_class (class) – Optional custom response_class

class flask_hal.HALResponse(response=None, status=None, headers=None, mimetype=None, content_type=None, direct_passthrough=False)

Bases: flask.wrappers.Response

A custom response class which overrides the default Response class wrapper.

Example

>>> from flask import Flask()
>>> from flask_hal import HALResponse
>>> app = Flask(__name__)
>>> app.response_class = HALResponse

static force_type(rv, env)

Called by flask.make_response when a view returns a none byte, string or unicode value. This method takes the views return value and converts into a standard Response.

Parameters:

• rv (flask_hal.document.Document) – View return value
• env (dict) – Request environment

Returns:

A standard Flask response

Return type:

flask.wrappers.Response

flask_hal.document

Module for constructing HAL documents.

Example

>>> from flask_hal.document import Document
>>> d = Document()
>>> d.to_dict()

class flask_hal.document.BaseDocument(data=None, links=None, embedded=None)

Bases: object

Constructs a HAL document.

__init__(data=None, links=None, embedded=None)

Base HAL Document. If no arguments are provided a minimal viable HAL Document is created.

Keyword Arguments:  

• data (dict) – Data for the document
• links (flask_hal.link.Collection) – A collection of HAL links
• embedded – TBC

Raises:

TypeError – If links is not a flask_hal.link.Collection

to_dict()

Converts the Document instance into an appropriate data structure for HAL formatted documents.

Returns:The HAL document data structure Return type:dict

to_json()

Converts Document to a JSON data structure.

Returns:JSON document Return type:str

class flask_hal.document.Document(data=None, links=None, embedded=None)

Bases: flask_hal.document.BaseDocument

Constructs a HAL document.

__init__(data=None, links=None, embedded=None)

Initialises a new HAL Document instance. If no arguments are provided a minimal viable HAL Document is created.

Keyword Arguments:  

• data (dict) – Data for the document
• links (flask_hal.link.Collection) – A collection of HAL links
• embedded – TBC

Raises:

TypeError – If links is not a flask_hal.link.Collection

class flask_hal.document.Embedded(data=None, links=None, embedded=None)

Bases: flask_hal.document.BaseDocument

Constructs a HAL embedded.

Example

>>> document = Document(
>>>     embedded={
>>>         'orders': Embedded(
>>>             embedded={'details': Embedded(
>>>                 data={'details': {}}
>>>             )},
>>>             links=link.Collection(
>>>                 link.Link('foo', 'www.foo.com'),
>>>                 link.Link('boo', 'www.boo.com')
>>>             ),
>>>             data={'total': 30},
>>>         )
>>>     },
>>>     data={'currentlyProcessing': 14}
>>> )
>>> document.to_json()
... {
        "_links": {
            "self": {"href": "http://localhost/entity/231"}
        },
        "_embedded": {
            "orders": {
                "_embedded": {
                    "details": {"details": {}}
                },
                "total": 30,
                "_links": {
                    "foo": {"href": "www.foo.com"},
                    "boo": {"href": "www.boo.com"}
                }
            }
        },
        "currentlyProcessing": 14
    }

to_dict()

Converts the Document instance into an appropriate data structure for HAL formatted documents.

Returns:The HAL document data structure Return type:dict

flask_hal.link

Implements the HAL Link specification.

class flask_hal.link.Collection(*args)

Bases: list

Build a collection of HAL link objects.

Example

>>> from flask_hal.link import Collection, Link
>>> l = Collection(
...     Link('foo', 'http://foo.com'),
...     Link('bar', 'http://bar.com'))
>>> print l.to_dict()
... {
...     '_links': {
...         'foo': {
...             'href": "http://foo.com'
...         },
...         'bar': {
...             'href': 'http://bar.com'
...         }
...     }
... }

__init__(*args)

Initialise a new Collection object.

Example

>>> l = Collection(
...     Link('foo', 'http://foo.com'),
...     Link('bar', 'http://bar.com'))

Raises:TypeError – If a link is not a flask_hal.link.Link instance

to_dict()

Returns the Python dict representation of the Collection instance.

Example

>>> from flask_hal.link import Collection, Link
>>> l = Collection(
...     Link('foo', 'http://foo.com'),
...     Link('bar', 'http://bar.com'))
>>> l.to_dict()
... {'_links': {'bar': {'href': 'http://bar.com'},
... 'foo': {'href': 'http://foo.com'}}}

Returns:dict

to_json()

Returns the JSON representation of the instance.

Example

>>> from flask_hal.link import Collection, Link
>>> l = Collection(
...     Link('foo', 'http://foo.com'),
...     Link('bar', 'http://bar.com'))
>>> l.to_json()
... '{"_links":
        {
            "foo": {"href": "http://foo.com"},
            "bar": {"href": "http://bar.com"}
        }
    }'

Returns:The JSON representation of the instance Return type:str

class flask_hal.link.Link(rel, href, **kwargs)

Bases: object

Build HAL specification _links object.

Example

>>> from flask_hal.link import Link
>>> l = Link('foo', 'http://foo.com/bar')
>>> print l.to_json()
... '{"foo": {"href": "http://foo.com/bar"}}'
>>> l.title = 'Foo'
>>> print l.to_json()
... '{"foo": {"href": "http://foo.com/bar", "name": "Foo"}}'

__init__(rel, href, **kwargs)

Initialise a new Link object.

Parameters:

• rel (str) – The links rel or name
• href (str) – The URI to the resource

Keyword Arguments:  

• name (str) – The links name attribute, optional
• title (str) – The links title attribute, optional
• type (str) – The links type attribute, optional
• deprecation (str) – The deprecation attribute, optional
• profile (str) – The profile attribute, optional
• templated (bool) – The templated attribute, optional
• hreflang (str) – The hreflang attribute, optional

to_dict()

Returns the Python dict representation of the Link instance.

Example

>>> from flask_hal.link import Link
>>> l = Link('foo', 'http://foo.com')
>>> l.to_dict()
... {'foo': {'href': 'http://foo.com'}}

Returns:dict

to_json()

Returns the JSON encoded representation of the Link object.

Example

>>> from flask_hal.link import Link
>>> l = Link('foo', 'http://foo.com', name='Foo')
>>> print l.to_json()
... '{"foo": {"href": "http://foo.com", "name": "Foo"}}'

Returns:The JSON encoded object Return type:str

class flask_hal.link.Self(**kwargs)

Bases: flask_hal.link.Link

A class to create the required self link from the current request URL.

__init__(**kwargs)

Initialises a new Self link instance. Accepts the same Keyword Arguments as Link.

See also

Link