Module views

Once a data model has been defined, you can begin to retrieve individual module instance from the server, which are called records. The main way to do this is using the find() method directly on the module class:

>>> Contact.find()
<view on Contact>

What you get here is a View. Views point to a subset of records in a module. They contain filtering information and may also be refined using ranges (see below). An important thing to note here is that views are lazy, which means that no data will be fetched until it is explicitly requested. For example, a view doesn’t know it’s own length until len() is called. Views can therefore be copied, modified and refined without actually hitting the server.

Note

If you’re familiar with Django, you will find that a View is much like a QuerySet, although the filtering syntax is a bit different.

Basic view operations

To get items out of a view, use the same syntax as with regular lists:

>>> view = Contact.find()
>>> view[4]
<Contact object at ...>
>>> list(view[2:6])
[<Contact object at ...>, <Contact object at ...>, <Contact object at ...>, <Contact object at ...>]

Hint

When using the asynchronous API, you will need to await all methods that (potentially) return record objects, including the array syntax. The example above would be:

>>> await view[4]

For the sake of brevity, the documentation will use the synchronous syntax.

These indexes adhere to whatever order the view is currently in. If you know the ID of a record, you can also retrieve it directly:

>>> view["17b245ae-b5d9-4b50-8bfb-32d8ce64c1f8"]
<Contact object at ...>

Any objects you take out of a view this way will be of the Module subtype that initially created the view. In this case, you will receive Contact objects.

Alternative to the array syntax, you can also use the get_by_index() or get_by_id() methods. Both raise errors (IndexError or KeyError) when no matching record is found.

To get the size of a view, use len() or length(), depending on the paradigm:

>>> len(view)
>>> await async_view.length()

Iteration

When iterating over a view, it will yield all records one by one:

>>> for record in view:
...     # Do something

Views also support the reversed() protocol for iterating backwards:

>>> for record in reversed(view):
...     # Do something

Slicing

While large views will only fetch necessary data when, it is also possible to limit a view to a specific subset using the normal slice syntax. Here are some typical examples:

>>> view[4:] # Start with the fourth item
>>> view[2:6] # Limit to items 2, 3, 4 and 5 (if present)
>>> view[:20] # Return at most 20 entries

The step parameter is also supported, which makes a fully valid way to swap the view’s ordering. This is how reversed() is implemented:

>>> view[::-1] # Reverse the entire view order

Another use for the step option is to skip every n-th item (although this may not be as efficient resource-wise because these requests are not batched):

>>> view[::2] # Only return evenly-indexed items
>>> view[2::3] # Skip until index 2, and from then take only every third item

When slicing like this, a new view is created. Since views are immutable, each change will produce a new copy. This also means that slicing can be chained with other calls:

>>> new_view = view.reversed()[2:]
>>> for record in view[:4]:
...     # Do something

Full API

class zucker.model.view.View(module: Type[ModuleType], base_endpoint: str = '')

Generic view class.

The first generic argument should be passed when initializing a view and point to the module’s type. The other two are only used internally and set by SyncView and AsyncView. They determine the type of results that are returned from the abstract methods.

filtered(*filters: Union[JsonMapping, GenericFilter]) → Self

Return a clone of this view which contains additional filters.

Parameters:

filters – Additional filters for the new view. These should be provided as filter-type objects (for example those generated by fields). Alternatively, naive dictionaries (those available from Sugar) are also supported. When multiple filters are provided, they will be AND-ed together.

reversed() → Self

Return a clone of this view, but with reversed iteration order.

This is identical to view[::-1].

abstract get_by_id(key: str) → GetReturn

Retrieve a record object by it’s ID.

abstract get_by_index(index: int) → GetReturn

Retrieve a record object by it’s index in this view.