1
2
3 u"""
4
5 This is a wrapper around a SPARQL service. It helps in creating the query URI and,
6 possibly, convert the result into a more manageable format.
7
8 The following packages are used:
9
10 - for JSON, the U{simplejson<https://pypi.python.org/pypi/simplejson>} package
11 - for RDF/XML, the U{RDFLib<https://rdflib.readthedocs.io>}
12
13 These packages are imported in a lazy fashion, ie, only when needed. Ie, if the user never intends to use the
14 JSON format, the C{simplejson} package is not imported and the user does not have to install it.
15
16 The package can be downloaded in C{zip} and C{.tar.gz} formats from
17 U{https://github.com/RDFLib/sparqlwrapper/releases<https://github.com/RDFLib/sparqlwrapper/releases>}.
18 Documentation is included in the distribution.
19
20
21 Basic QUERY Usage (SELECT)
22 ==========================
23
24 Simple query
25 ------------
26
27 The simplest usage of this module looks as follows (using the default, ie, U{XML return format<http://www.w3.org/TR/rdf-sparql-XMLres/>}, and special URI for the
28 SPARQL Service)::
29
30 from SPARQLWrapper import SPARQLWrapper
31 queryString = "SELECT * WHERE { ?s ?p ?o. }"
32 sparql = SPARQLWrapper("http://example.org/sparql")
33 # add a default graph, though that can also be part of the query string
34 sparql.addDefaultGraph("http://www.example.org/graph-selected")
35 sparql.setQuery(queryString)
36 try :
37 ret = sparql.query()
38 # ret is a stream with the results in XML, see <http://www.w3.org/TR/rdf-sparql-XMLres/>
39 except :
40 deal_with_the_exception()
41
42 If C{SPARQLWrapper("http://example.org/sparql",returnFormat=SPARQLWrapper.JSON)} was used, the result would be in
43 U{JSON format<http://www.w3.org/TR/rdf-sparql-json-res/>} instead of XML (provided the sparql
44 processor can return JSON).
45
46 Automatic conversion of the results
47 -----------------------------------
48
49 To make processing somewhat easier, the package can do some conversions automatically from the return result. These are:
50
51 - for XML, the U{xml.dom.minidom<http://docs.python.org/library/xml.dom.minidom.html>} (C{http://docs.python.org/library/xml.dom.minidom.html}) is
52 used to convert the result stream into a Python representation of a DOM tree
53 - for JSON, the U{simplejson<https://pypi.python.org/pypi/simplejson>} package (C{https://pypi.python.org/pypi/simplejson}) to generate a Python dictionary
54 - for CSV/TSV, a simple C{string}
55
56 There are two ways to generate this conversion:
57
58 - use C{ret.convert()} in the return result from C{sparql.query()} in the code above
59 - use C{sparql.queryAndConvert()} to get the converted result right away if the intermediate stream is not used
60
61 For example, in the code below::
62 try :
63 sparql.setReturnFormat(SPARQLWrapper.JSON)
64 ret = sparql.query()
65 dict = ret.convert()
66 except:
67 deal_with_the_exception()
68 the value of C{dict} is a Python dictionary of the query result, based on the U{JSON format<http://www.w3.org/TR/rdf-sparql-json-res/>}.
69
70 The L{SPARQLWrapper} class can be subclassed by overriding the conversion routines if the user wants to use something else.
71
72 Partial interpretation of the results
73 -------------------------------------
74
75 A further help is to offer an extra, partial interpretation of the results, again to cover
76 most of the practical use cases.
77 Based on the U{JSON format<http://www.w3.org/TR/rdf-sparql-json-res/>}, the L{SmartWrapper.Bindings} class
78 can perform some simple steps in decoding the JSON return results. If L{SPARQLWrapper2}
79 is used instead of L{SPARQLWrapper}, this result format is generated. Note that this relies on a JSON format only,
80 ie, it has to be checked whether the SPARQL service can return JSON or not.
81
82 Here is a simple code that makes use of this feature::
83
84 from SPARQLWrapper import SPARQLWrapper2
85 queryString = "SELECT ?subj ?prop WHERE { ?subj ?prop ?o. }"
86 sparql = SPARQLWrapper2("http://example.org/sparql")
87 # add a default graph, though that can also be in the query string
88 sparql.addDefaultGraph("http://www.example.org/graph-selected")
89 sparql.setQuery(queryString)
90 try :
91 ret = sparql.query()
92 print ret.variables # this is an array consisting of "subj" and "prop"
93 for binding in ret.bindings :
94 # each binding is a dictionary. Let us just print the results
95 print "%s: %s (of type %s)" % ("s",binding[u"subj"].value,binding[u"subj"].type)
96 print "%s: %s (of type %s)" % ("p",binding[u"prop"].value,binding[u"prop"].type)
97 except:
98 deal_with_the_exception()
99
100 To make this type of code even easier to realize, the C{[]} and C{in} operators are also implemented
101 on the result of L{SmartWrapper.Bindings}. This can be used to check and find a particular binding (ie, particular row
102 in the return value). This features becomes particularly useful when the C{OPTIONAL} feature of SPARQL is used. For example::
103
104 from SPARQLWrapper import SPARQLWrapper2
105 queryString = "SELECT ?subj ?o ?opt WHERE { ?subj <http://a.b.c> ?o. OPTIONAL { ?subj <http://d.e.f> ?opt }}"
106 sparql = SPARQLWrapper2("http://example.org/sparql")
107 # add a default graph, though that can also be in the query string
108 sparql.addDefaultGraph("http://www.example.org/graph-selected")
109 sparql.setQuery(queryString)
110 try :
111 ret = sparql.query()
112 print ret.variables # this is an array consisting of "subj", "o", "opt"
113 if (u"subj",u"prop",u"opt") in ret :
114 # there is at least one binding covering the optional "opt", too
115 bindings = ret[u"subj",u"o",u"opt"]
116 # bindings is an array of dictionaries with the full bindings
117 for b in bindings :
118 subj = b[u"subj"].value
119 o = b[u"o"].value
120 opt = b[u"opt"].value
121 # do something nice with subj, o, and opt
122 # another way of accessing to values for a single variable:
123 # take all the bindings of the "subj"
124 subjbind = ret.getValues(u"subj") # an array of Value instances
125 ...
126 except:
127 deal_with_the_exception()
128
129
130 CONSTRUCT, ASK, DESCRIBE
131 ========================
132
133 All the examples so far were based on the SELECT queries. If the query includes, eg, the C{CONSTRUCT} keyword then the accepted
134 return formats should be different: eg, C{SPARQLWrapper.XML} means C{RDF/XML} and most of the SPARQL engines can also return the
135 results in C{Turtle}. The package, though it does not contain a full SPARQL parser, makes an attempt to determine the query type
136 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
137 goes wrong).
138
139 For RDF/XML and JSON-LD, the U{RDFLib<https://rdflib.readthedocs.io>} package is used to convert the result into a C{Graph} instance.
140 For Turtle, a string is returned.
141
142 GET or POST
143 ===========
144
145 By default, all SPARQL services are invoked using HTTP GET. However, POST might be useful if the size of the query
146 extends a reasonable size; this can be set in the query instance.
147
148 Note that some combination may not work yet with all SPARQL processors
149 (eg, there are implementations where POST+JSON return does not work). Hopefully, this problem will eventually disappear.
150
151 Acknowledgement
152 ===============
153
154 The package was greatly inspired by U{Lee Feigenbaum's similar package for Javascript<http://thefigtrees.net/lee/blog/2006/04/sparql_calendar_demo_a_sparql.html>}.
155
156 @summary: Python interface to SPARQL services
157 @see: U{SPARQL Specification<http://www.w3.org/TR/rdf-sparql-query/>}
158 @authors: U{Ivan Herman<http://www.ivan-herman.net>}, U{Sergio Fernández<http://www.wikier.org>}, U{Carlos Tejo Alonso<http://www.dayures.net>}, U{Alexey Zakhlestin<https://indeyets.ru/>}
159 @organization: U{World Wide Web Consortium<http://www.w3.org>}, U{Salzburg Research<http://www.salzburgresearch.at>} and U{Foundation CTIC<http://www.fundacionctic.org/>}.
160 @license: U{W3C® SOFTWARE NOTICE AND LICENSE<href="http://www.w3.org/Consortium/Legal/copyright-software">}
161 @requires: U{simplejson<https://pypi.python.org/pypi/simplejson>} package.
162 @requires: U{RDFLib<https://rdflib.readthedocs.io>} package.
163 """
164
165 __version__ = "1.8.2"
166 """The version of SPARQLWrapper"""
167
168 __authors__ = "Ivan Herman, Sergio Fernández, Carlos Tejo Alonso, Alexey Zakhlestin"
169 """The primary authors of SPARQLWrapper"""
170
171 __license__ = "W3C® SOFTWARE NOTICE AND LICENSE, http://www.w3.org/Consortium/Legal/copyright-software"
172 """The license governing the use and distribution of SPARQLWrapper"""
173
174 __url__ = "http://rdflib.github.io/sparqlwrapper"
175 """The URL for SPARQLWrapper's homepage"""
176
177 __contact__ = "rdflib-dev@googlegroups.com"
178 """Mail list to contact to other people RDFLib and SPARQLWrappers folks and developers"""
179
180 __date__ = "2018-05-16"
181 """Last update"""
182
183 __agent__ = "sparqlwrapper %s (rdflib.github.io/sparqlwrapper)" % __version__
184
185
186 from Wrapper import SPARQLWrapper
187 from Wrapper import XML, JSON, TURTLE, N3, JSONLD, RDF, RDFXML, CSV, TSV
188 from Wrapper import GET, POST
189 from Wrapper import SELECT, CONSTRUCT, ASK, DESCRIBE, INSERT, DELETE
190 from Wrapper import URLENCODED, POSTDIRECTLY
191 from Wrapper import BASIC, DIGEST
192
193 from SmartWrapper import SPARQLWrapper2
194