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:
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