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 aHAL
document response from a view into it’sJSON
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
-
static
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 viableHAL
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
– Iflinks
is not aflask_hal.link.Collection
-
to_dict
()¶ Converts the
Document
instance into an appropriate data structure for HAL formatted documents.Returns: The HAL
document data structureReturn type: dict
-
-
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 viableHAL
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
– Iflinks
is not aflask_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 structureReturn 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 aflask_hal.link.Link
instance
-
to_dict
()¶ Returns the Python
dict
representation of theCollection
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 instanceReturn 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
- rel (str) – The links
-
to_dict
()¶ Returns the Python
dict
representation of theLink
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 theLink
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 objectReturn 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.