The surf.resource Module

Contents

• The surf.resource.value Module
• The surf.resource.result_proxy Module

The surf.resource base Module

class surf.resource.Resource(subject=None, block_auto_load=False, context=None, namespace=None)

Bases: object

The Resource class, represents the transparent proxy object that exposes sets of RDF triples under the form of <s,p,o> and <s’,p,s> as an object in python.

One can create resource directly by instantiating this class, but it is advisable to use the session to do so, as the session will create subclasses of Resource based on the <s,rdf:type,`concept`> pattern.

Triples that constitute a resource can be accessed via Resource instance attributes. SuRF uses the following naming convention for attribute names: nsprefix_predicate. Attribute name examples: “rdfs_label”, “foaf_name”, “owl_Class”.

Resource instance attributes can be set and get. If get, they will be structures of type surf.resource.value.ResourceValue. This class is subclass of list (to handle situations when there are several triples with the same subject and predicate but different objects) and have some some special features. Since ResourceValue is subtype of list, it can be iterated, sliced etc.

surf.resource.value.ResourceValue.first() will return first element of list or None if list is empty:

>>> resource.foaf_knows = [URIRef("http://p1"), URIRef("http://p2")]
>>> resource.foaf_knows.first
rdflib.URIRef('http://p1')

surf.resource.value.ResourceValue.one() will return first element of list or will raise if list is empty or has more than one element:

>>> resource.foaf_knows = [URIRef("http://p1"), URIRef("http://p2")]
>>> resource.foaf_knows.one
Traceback (most recent call last):
    ....
Exception: list has more elements than one

When setting resource attribute, it will accept about anything and translate it to ResourceValue. Attribute can be set to instance of URIRef:

>>> resource.foaf_knows = URIRef("http://p1")
>>> resource.foaf_knows
[rdflib.URIRef('http://p1')]

Attribute can be set to list or tuple:

>>> resource.foaf_knows = (URIRef("http://p1"), URIRef("http://p2"))
>>> resource.foaf_knows
[rdflib.Literal(u'http://p1', lang=rdflib.URIRef('http://p2'))]

Attribute can be set to string, integer, these will be converted into instances of Literal:

>>> resource.foaf_name = "John"
>>> resource.foaf_name
[rdflib.Literal(u'John')]

Attribute can be set to another SuRF resource. Values of different types can be mixed:

>>> resource.foaf_knows = (URIRef("http://p1"), another_resource)
>>> resource.foaf_knows
[rdflib.URIRef('http://p1'), <surf.session.FoafPerson object at 0xad049cc>]

Initialize a Resource, with the subject (a URI - either a string or a URIRef).

If subject is None than a unique subject will be generated using the surf.util.uuid_subject() function. If namespace is specified, generated subject will be in that namespace.

block_auto_load will prevent the resource from autoloading all rdf attributes associated with the subject of the resource.

classmethod all()

Retrieve all or limited number of instances.

bind_namespaces(*namespaces)

Bind the namespace to the resource.

Useful for pretty serialization of the resource.

bind_namespaces_to_graph(graph)

Bind the ‘resources’ registered namespaces to the supplied graph.

classmethod concept(subject, store=None)

Return the Resources concept uri (type).

If parameter store is specified, concept will be retrieved from there. If resource was retrieved via session, it contains reference to store it was retrieved from and this reference will be used. Otherwise, sessions default_store will be used to retrieve the concept.

context

Context (graph) where triples constituting this resource reside in.

In case of SPARQL and SPARUL, “context” is the same thing as “graph”.

Effects of having context set:

• When resource as whole or its individual attributes are loaded, triples will be only loaded from this context.
• When resource is saved, triples will be saved to this context.
• When existence of resource is checked (is_present()), only triples in this context will be considered.

context attribute would be usually set by store or session when instantiating resource, but it can also be set or changed on already instantiated resource. Here is an inefficient but workable example of how to move resource from one context to another:

Person = surf.ns.FOAF["Person"]
john_uri = "http://example/john"

old_graph_uri = URIRef("http://example/old_graph")
new_graph_uri = URIRef("http://example/new_graph")

instance = session.get_resource(john_uri, Person, old_graph_uri)
instance.context = new_graph_uri
instance.save()

# Now john is saved in the new graph but we still have to delete it
# from the old graph.

instance = session.get_resource(john_uri, Person, old_graph_uri)
instance.remove()

dirty

Reflects the dirty state of the resource.

classmethod get_by(**filters)

Retrieve all instances that match specified filters and class.

Filters are specified as keyword arguments, argument names follow SuRF naming convention (they take form namespace_name).

Example:

>>> Person = session.get_class(surf.ns.FOAF['Person'])
>>> johns = Person.get_by(foaf_name = u"John")

classmethod get_by_attribute(attributes, context=None)

Retrieve all instances from the data store that have the specified attributes and are of rdf:type of the resource class

classmethod get_dirty_instances()

Return all the unsaved (dirty) instances of type Resource.

graph(direct=True)

Return an rdflib ConjunctiveGraph represenation of the current resource

is_present()

Return True if the resource is present in data store.

Resource is assumed to be present if there is at least one triple having subject of this resource as subject.

load()

Load all attributes from the data store:

• direct attributes (where the subject is the subject of the resource)
• indirect attributes (where the object is the subject of the resource)

Note

This method resets the dirty state of the object.

load_from_source(data=None, file=None, location=None, format=None)

Load the resource from a source (uri, file or string rdf data).

classmethod namespace()

Return the namespace of the currenlt Resources class type.

namespaces

The namespaces.

query_attribute(attribute_name)

Return ResultProxy for querying attribute values.

rdf_direct

Direct predicates (outgoing predicates).

rdf_inverse

Inverse predicates (incoming predicates).

remove(inverse=False)

Remove the resource from the data store.

classmethod rest_api(resources_namespace)

Return a surf.rest.Rest class responsible for exposing REST api functions for integration into REST aware web frameworks.

Note

The REST API was modeled according to the pylons model but it is generic enough to eb used in other frameworks.

save()

Save the resource to the data store.

serialize(format='xml', direct=False)

Return a serialized version of the internal graph represenatation of the resource, the format is the same as expected by rdflib’s graph serialize method

supported formats:

• n3
• xml
• json (internal serializer)
• nt
• turtle

set(graph)

Load the resource from a graph. The graph must be a rdflib ConjunctiveGraph or Graph

subject

The subject of the resource.

classmethod to_rdf(value)

Convert any value to it’s appropriate rdflib construct.

update()

Update the resource in the data store.

This method does not remove other triples related to it (the inverse triples of type <s’,p,s>, where s is the subject of the resource)