Package SPARQLWrapper
[hide private]
[frames] | no frames]

Package SPARQLWrapper

source code

This is a wrapper around a SPARQL service. It helps in creating the query URI and, possibly, convert the result into a more managable format.

The following packages are used:

These packages are imported in a lazy fashion, ie, only when needed. Ie, if the user never intends to use the JSON format, the simplejson package is not imported and the user does not have to install it.

The package can be downloaded in zip and .tar.gz formats from http://www.ivan-herman.net/Misc/PythonStuff/SPARQL/. It is also available from Sourceforge under the project named "sparql-wrapper". Documentation is included in the distribution.

Basic QUERY Usage

Simple query

The simplest usage of this module looks as follows (using the default, ie, XML return format, and special URI for the SPARQL Service):

from SPARQLWrapper import SPARQLWrapper
queryString = "SELECT * WHERE { ?s ?p ?o. }"
sparql = SPARQLWrapper("http://localhost:2020/sparql")
# add a default graph, though that can also be part of the query string
sparql.addDefaultGraph("http://www.example.com/data.rdf")
sparql.setQuery(queryString)
try :
   ret = sparql.query()
   # ret is a stream with the results in XML, see <http://www.w3.org/TR/rdf-sparql-XMLres/>
except :
   deal_with_the_exception()

If SPARQLWrapper("http://localhost:2020/sparql",returnFormat=SPARQLWrapper.JSON) was used, the result would be in JSON format instead of XML (provided the sparql processor can return JSON).

Automatic conversion of the results

To make processing somewhat easier, the package can do some conversions automatically from the return result. These are:

There are two ways to generate this conversion:

For example, in the code below:

try :
    sparql.setReturnFormat(SPARQLWrapper.JSON)
    ret = sparql.query()
    dict = ret.convert()
except:
    deal_with_the_exception()

the value of dict is a Python dictionary of the query result, based on the JSON format.

The SPARQLWrapper class can be subclassed by overriding the conversion routines if the user wants to use something else.

Partial interpretation of the results

A further help is to offer an extra, partial interpretation of the results, again to cover most of the practical use cases. Based on the JSON format, the SmartWrapper.Bindings class can perform some simple steps in decoding the JSON return results. If SPARQLWrapper2 is used instead of SPARQLWrapper, this result format is generated. Note that this relies on a JSON format only, ie, it has to be checked whether the SPARQL service can return JSON or not.

Here is a simple code that makes use of this feature:

from SPARQLWrapper import SPARQLWrapper2
queryString = "SELECT ?subj ?prop WHERE { ?subj ?prop ?o. }"
sparql = SPARQLWrapper2("http://localhost:2020/sparql")
# add a default graph, though that can also be in the query string
sparql.addDefaultGraph("http://www.example.com/data.rdf")
sparql.setQuery(queryString)
try :
    ret = sparql.query()
    print ret.variables  # this is an array consisting of "subj" and "prop"
    for binding in ret.bindings :
        # each binding is a dictionary. Let us just print the results
        print "%s: %s (of type %s)" % ("s",binding[u"subj"].value,binding[u"subj"].type)
        print "%s: %s (of type %s)" % ("p",binding[u"prop"].value,binding[u"prop"].type)
except:
    deal_with_the_exception()

To make this type of code even easier to realize, the [] and in operators are also implemented on the result of SmartWrapper.Bindings. This can be used to check and find a particular binding (ie, particular row in the return value). This features becomes particularly useful when the OPTIONAL feature of SPARQL is used. For example:

from SPARQLWrapper import SPARQLWrapper2
queryString = "SELECT ?subj ?o ?opt WHERE { ?subj <http://a.b.c> ?o. OPTIONAL { ?subj <http://d.e.f> ?opt }}"
sparql = SPARQLWrapper2("http://localhost:2020/sparql")
# add a default graph, though that can also be in the query string
sparql.addDefaultGraph("http://www.example.com/data.rdf")
sparql.setQuery(queryString)
try :
    ret = sparql.query()
    print ret.variables  # this is an array consisting of "subj", "o", "opt"
    if (u"subj",u"prop",u"opt") in ret :
       # there is at least one binding covering the optional "opt", too
       bindings = ret[u"subj",u"o",u"opt"]
       # bindings is an array of dictionaries with the full bindings
       for b in bindings :
           subj = b[u"subj"].value
           o    = b[u"o"].value
           opt  = b[u"opt"].value
           # do something nice with subj, o, and opt
    # another way of accessing to values for a single variable:
    # take all the bindings of the "subj"
    subjbind = ret.getValues(u"subj") # an array of Value instances
    ...
except:
    deal_with_the_exception()

CONSTRUCT, ASK, DESCRIBE

All the examples so far were based on the SELECT queries. If the query includes, eg, the CONSTRUCT keyword then the accepted return formats should be different: eg, SPARQLWrapper.XML means RDF/XML and most of the SPARQL engines can also return the results in Turtle. The package, though it does not contain a full SPARQL parser, makes an attempt to determine the query type when the query is set. This should work in most of the cases (but there is a possibility to set this manually, in case something goes wrong).

For RDF/XML, the RDFLib (http://rdflib.net) package is used to convert the result into a Graph instance.

GET or POST

By default, all SPARQL services are invoked using HTTP GET. However, POST might be useful if the size of the query extends a reasonable size; this can be set in the query instance.

Note that some combination may not work yet with all SPARQL processors (eg, there are implementations where POST+JSON return does not work). Hopefully, this problem will eventually disappear.

Note that SPARQLWrapper only supports nowadays query using POST via URL-encoded.

Acknowledgement

The package was greatly inspired by Lee Feigenbaum's similar package for Javascript.


See Also: SPARQL Specification

Author: Ivan Herman, Sergio Fernández, Carlos Tejo Alonso

Organization: World Wide Web Consortium, Salzburg Research and Foundation CTIC.

License: W3C® SOFTWARE NOTICE AND LICENSE

Requires:

Version: 1.7.6

Date: 2015-12-18

Contact: rdflib-dev@googlegroups.com

Submodules [hide private]

Variables [hide private]
  __version__ = '1.7.6'
The version of SPARQLWrapper
  __authors__ = 'Ivan Herman, Sergio Fern\xc3\xa1ndez, Carlos Te...
The primary authors of SPARQLWrapper
  __license__ = 'W3C\xc2\xae SOFTWARE NOTICE AND LICENSE, http:/...
The license governing the use and distribution of SPARQLWrapper
  __url__ = 'http://rdflib.github.io/sparqlwrapper'
The URL for SPARQLWrapper's homepage
  __contact__ = 'rdflib-dev@googlegroups.com'
Mail list to contact to other people RDFLib and SPARQLWrappers folks and developers
  __date__ = '2015-12-18'
Last update
  __agent__ = 'sparqlwrapper 1.7.6 (rdflib.github.io/sparqlwrapp...
  __package__ = 'SPARQLWrapper'
Variables Details [hide private]

__authors__

The primary authors of SPARQLWrapper

Value:
'Ivan Herman, Sergio Fern\xc3\xa1ndez, Carlos Tejo Alonso, Alexey Zakh\
lestin'

__license__

The license governing the use and distribution of SPARQLWrapper

Value:
'W3C\xc2\xae SOFTWARE NOTICE AND LICENSE, http://www.w3.org/Consortium\
/Legal/copyright-software'

__agent__

Value:
'sparqlwrapper 1.7.6 (rdflib.github.io/sparqlwrapper)'