The surf.resource.result_proxy Module

Module for ResultProxy.

class surf.resource.result_proxy.ResultProxy(params={}, store=None, instancemaker=None)

Bases: object

Interface to surf.store.Store.get_by().

ResultProxy collects filtering parameters. When iterated, it executes surf.store.Store.get_by() with collected parameters and yields results.

ResultProxy doesn’t know how to convert data returned by surf.store.Store.get_by() into surf.resource.Resource, URIRef and Literal objects. It delegates this task to instancemaker function.

context(context)

Specify context/graph that resources should be loaded from.

desc()

Set sorting order to descending.

filter(**kwargs)

Add filter conditions.

Expects arguments in form:

ns_predicate = "(%s > 15)"

ns_predicate specifies which predicate will be used for filtering, a query variable will be bound to it. %s is a placeholder for this variable.

Filter expression (in example: “(%s > 15)”) must follow SPARQL specification, on execution “%s” will be substituted with variable and the resulting string will be placed in query as-is. Because of string substitution percent signs need to be escaped. For example:

Person.all().filter(foaf_name = "(%s LIKE 'J%%')")

This Virtuoso-specific filter is intended to select persons with names starting with “J”. In generated query it will look like this:

...
?s <http://xmlns.com/foaf/0.1/name> ?f1 .
FILTER (?f1 LIKE 'J%')
...

first()

Return first resource or None if there aren’t any.

full(only_direct=False)

Enable eager-loading of resource attributes.

If full is set to True, returned resources will have attributes already loaded.

Whether setting this will bring performance improvements depends on reader plugin implementation. For example, sparql_protocol plugin is capable of using SPARQL subqueries to fully load multiple resources in one request.

get_by(**kwargs)

Add filter conditions.

Arguments are expected in form:

foaf_name = "John"

Multiple arguments are supported. An example that retrieves all persons named “John Smith”:

FoafPerson = session.get_class(surf.ns.FOAF.Person)
for person in FoafPerson.get_by(foaf_name = "John", foaf_surname = "Smith"):
    print person.subject

instancemaker(instancemaker_function)

Specify the function for converting triples into instances.

instancemaker_function function can also be specified as argument to constructor when instantiating ResultProxy.

instancemaker_function will be executed whenever ResultProxy needs to return a resource. It has to accept two arguments: params and instance_data.

params will be a dictionary containing query parameters gathered by ResultProxy. Information from params can be used by instancemaker_function, for example, to decide what context should be set for created instances.

instance_data will be a dictionary containing keys direct and inverse. These keys map to dictionaries describing direct and inverse attributes respectively.

limit(value)

Set the limit for returned result count.

offset(value)

Set the limit for returned results.

one()

Return the only resource or raise if resource count != 1.

If the query matches no resources, this method will raise surf.exc.NoResultFound exception. If the query matches more than one resource, this method will raise surf.exc.MultipleResultsFound exception.

order(value=True)

Request results to be ordered.

If no arguments are specified, resources will be ordered by their subject URIs.

If value is set to an URIRef, corresponding attribute will be used for sorting. For example, sorting persons by surname:

FoafPerson = session.get_class(surf.ns.FOAF.Person)
for person in FoafPerson.all().order(surf.ns.FOAF.surname):
    print person.foaf_name.first, person.foaf_surname.first

Currently only one sorting key is supported.