Abstract classes for higher-level tools

Some higher-level tools aren’t explicitly implemented by Findig; rather abstract classes for how they are expected to behave are defined so that support libraries and applications can provide their own implementations.

Data sets

Data sets are one example of higher level tools without an explicit implementation. Abstractly, they’re collections of resource data that also encapsulate an implicit data model (i.e., instructions on data access). This makes them a powerful replacement for explicitly defining a data-model for each resource, since a resource function can instead return a data set and have Findig construct a resource from it:

@app.route("/items/<int:id>")
@app.resource(lazy=True)
def item(id):
    return items().fetch(id=id)

@app.route("/items")
@item.collection(lazy=True)
def items():
    return SomeDataSet()

Findig currently includes one concrete implementation: findig.extras.redis.RedisSet.

class findig.tools.dataset.AbstractDataSet

An abstract data set is a representation of a collection of items.

Concrete implementations must provide at least an implementation for __iter__, which should return an iterator of AbstractRecord instances.

fetch(**search_spec)

Fetch an AbstractRecord matching the search specification.

If this is called outside a request, a lazy record is returned immediately (i.e., the backend isn’t hit until the record is explicitly queried).

fetch_now(**search_spec)

Fetch an AbstractRecord matching the search specification.

Unlike fetch(), this function will always hit the backend.

filtered(**search_spec)

Return a filtered view of this data set.

Each keyword represents the name of a field that is checked, and the corresponding argument indicates what it is checked against. If the argument is Callable, then it should be a predicate that returns True if the field is valid (be aware that the predicate will passed be None if the field isn’t present on the record), otherwise it is compared against the field for equality.

limit(count, offset=0)

Return a limited version of this data set.

Parameters:

• offset – The number of items to skip from the beginning
• count – The maximum number of items to return

sorted(*sort_spec, descending=False)

Return a sorted view of this data set.

The method takes a variable number of arguments that specify its sort specification.

If a single, callable argument is provided, it is taken as a sort key for a record.

Otherwise, the arguments are taken as field names to be sorted, in the same order given in the argument list. Records that omit one of these fields appear later in the sorted set than those that don’t.

class findig.tools.dataset.MutableDataSet

An abstract data set that can add new child elements.

add(data)

Add a new child item to the data set.

class findig.tools.dataset.AbstractRecord

An representation of an item belonging to a collection.

read()

Read the record’s data and return a mapping of fields to values.

class findig.tools.dataset.MutableRecord

An abstract record that can update or delete itself.

close_edit_block(token)

End a transaction started by start_edit_block().

delete()

Delete the record’s data.

edit_block()

A context manager for grouping a chain of edits together. Some subclasses may not support performing reads inside an edit block.

patch(add_data, remove_fields)

Update the record’s data with the new data.

start_edit_block()

Start a transaction to the backend.

Backend edits made through this object should be grouped together until close_edit_block() is called.

Returns:A token that is passed into close_edit_block().