Preparers¶
restless.preparers¶
-
class
restless.preparers.
CollectionSubPreparer
(lookup, preparer)¶ A preparation class designed to handle collections of data.
This is useful in the case where you have a 1-to-many or many-to-many relationship of data to expose as part of the parent data.
Example:
# First, set up a preparer that handles the data for each thing in # the broader collection. comment_preparer = FieldsPreparer(fields={ 'comment': 'comment_text', 'created': 'created', }) # Then use it with the ``CollectionSubPreparer`` to create a list # of prepared sub items. preparer = FieldsPreparer(fields={ # A normal blog post field. 'post': 'post_text', # All the comments on the post. 'comments': CollectionSubPreparer('comments.all', comment_preparer), })
-
prepare
(data)¶ Handles passing each item in the collection data to the configured subpreparer.
Uses a loop and the
get_inner_data
method to provide the correct item of the data.Returns a list of data as the response.
-
-
class
restless.preparers.
FieldsPreparer
(fields)¶ A more complex preparation object, this will return a given set of fields.
This takes a
fields
parameter, which should be a dictionary of keys (fieldnames to expose to the user) & values (a dotted lookup path to the desired attribute/key on the object).Example:
preparer = FieldsPreparer(fields={ # ``user`` is the key the client will see. # ``author.pk`` is the dotted path lookup ``FieldsPreparer`` # will traverse on the data to return a value. 'user': 'author.pk', })
-
lookup_data
(lookup, data)¶ Given a lookup string, attempts to descend through nested data looking for the value.
Can work with either dictionary-alikes or objects (or any combination of those).
Lookups should be a string. If it is a dotted path, it will be split on
.
& it will traverse through to find the final value. If not, it will simply attempt to find either a key or attribute of that name & return it.Example:
>>> data = { ... 'type': 'message', ... 'greeting': { ... 'en': 'hello', ... 'fr': 'bonjour', ... 'es': 'hola', ... }, ... 'person': Person( ... name='daniel' ... ) ... } >>> lookup_data('type', data) 'message' >>> lookup_data('greeting.en', data) 'hello' >>> lookup_data('person.name', data) 'daniel'
-
prepare
(data)¶ Handles transforming the provided data into the fielded data that should be exposed to the end user.
Uses the
lookup_data
method to traverse dotted paths.Returns a dictionary of data as the response.
-
-
class
restless.preparers.
Preparer
¶ A plain preparation object which just passes through data.
It also is relevant as the protocol subclasses should implement to work with Restless.
-
prepare
(data)¶ Handles actually transforming the data.
By default, this does nothing & simply returns the data passed to it.
-
-
class
restless.preparers.
SubPreparer
(lookup, preparer)¶ A preparation class designed to be used within other preparers.
This is primary to enable deeply-nested structures, allowing you to compose/share definitions as well. Typical usage consists of creating a configured instance of a FieldsPreparer, then use a SubPreparer to pull it in.
Example:
# First, define the nested fields you'd like to expose. author_preparer = FieldsPreparer(fields={ 'id': 'pk', 'username': 'username', 'name': 'get_full_name', }) # Then, in the main preparer, pull them in using `SubPreparer`. preparer = FieldsPreparer(fields={ 'author': SubPreparer('user', author_preparer), # Other fields can come before/follow as normal. 'content': 'post', 'created': 'created_at', })
-
get_inner_data
(data)¶ Used internally so that the correct data is extracted out of the broader dataset, allowing the preparer being called to deal with just the expected subset.
-
prepare
(data)¶ Handles passing the data to the configured preparer.
Uses the
get_inner_data
method to provide the correct subset of the data.Returns a dictionary of data as the response.
-