@@ -12,7 +12,7 @@ Requirements
1212------------
1313
1414The kernel has only been tried with Jupyter 4.x. It works with Python 2.7 and
15- Python 3 (tested with Python 3.5 ).
15+ Python 3 (tested with Python 3.6 ).
1616
1717The above mentioned `SPARQLWrapper `_ & `rdflib `_ Python packages are required
1818dependencies (they are marked as such, so they will automatically be installed
@@ -82,142 +82,44 @@ keywords have contextual help, as of now.
8282It also installs menu entries in the HELP menu pointing to SPARQL documentation.
8383
8484
85- Output format
86- -------------
85+ Execution
86+ ---------
8787
8888The query results are displayed in the notebook as cell results; there are a
8989number of choices for the display format, controlled via magics (see below).
9090
91- Each SPARQL query is immediately launched, once the results are printed out it
91+ Each SPARQL query is immediately launched, and once the results are printed out it
9292is forgotten. Cells are thus completely independent from each other (except for
9393magics, which are persistent).
9494
95+ When a notebook is fully executed (e.g. *Cells * -> *Run all *), all code cells
96+ in the notebook, and hence all queries, are executed in sequence. To avoid
97+ execution of any particular cell, its type can be changed to RAW cell instead of
98+ CODE cell (in *Cells * -> *Cell Type * -> *Raw *).
99+
95100
96101Magics
97102------
98103
99- A number of line magics (lines starting with ``% ``) can be used to control the
100- kernel behaviour. These line magics must be placed at the start of the cell,
101- and there can be more than one per cell.
102- Valid combinations are thus:
103-
104- * a cell with only a SPARQL query,
105- * a cell consisting only of magics,
106- * and a cell containing both magics and then a SPARQL query (but after the
107- first SPARQL keyword the cell is assumed to be in SPARQL mode, and line
108- magics will *not * be recognized as such).
109-
110- Comment lines (lines starting with ``# ``) can be freely interspersed between
111- line magics or SPARQL queries.
112-
113- Magics also feature autocompletion and contextual help. Furthermore, there is
114- a special magic ``%lsmagics ``; when executed on a cell it will output the list
115- of all currently available magics. The same info can be obtained by requesting
116- contextual help (i.e. Shift-TAB) on a line containing only a percent sign.
117-
118- A few of the most relevant magics are explained in the following sections. The
119- complete set is always available in the notebook, by using the help or
120- autocompletion features.
121-
122-
123- ``%endpoint ``
124- .............
125-
126- This magic is special in the sense that it is compulsory: there needs to be an
127- endpoint defined *before * the first SPARQL query is launched, otherwise the
128- query will fail.
129-
130- Its syntax is::
131-
132- %endpoint <url>
133-
134- and it simply defines the SPARQL endpoint for all subsequent queries.
135- It remains active until superseded by another ``%endpoint `` magic.
136-
137-
138- ``%qparam ``
139- ...........
140-
141- Define a custom additional parameter to be sent with every query. Its syntax
142- is::
143-
144- %qparam <name> <value>
145-
146- and it will add the ``name=value `` parameter to every subsequent query (it can
147- be used e.g. to send API keys, or any parameter required by the endpoint).
148-
149- Any number of parameters can be defined; they will all be added to the queries
150- executed after their definitions. To remove a parameter, use a line with no
151- value::
152-
153- %qparam <name>
154-
155-
156- ``%header ``
157- ............
158- Adds a certain header to each sparql queries. This can be used to set some
159- (potentially non SPARQL) command in the query. For instance virtuoso endpoints
160- accept the _define_ keyword which can be used to trigger the server reasoner.
161-
162-
163-
164- ``%auth ``
165- ...........
166-
167- Define HTTP authentication to send to the backend. Its syntax is::
168-
169- %auth (basic | digest) <username> <password>
170-
171- Once defined, it will be sent to the backend on every subsequent query. To
172- remove a defined authentication, just use::
173-
174- %auth none
175-
176-
177- ``%format ``
178- ............
179-
180- Sets the data format requested to the SPARQL endpoint::
181-
182- %format JSON | XML | N3 | any | default
183-
184- where:
185-
186- * ``JSON `` requests *application/sparql-results+json * format
187- * ``XML `` requests *application/sparql-results+xml * format
188- * ``N3 `` requests the endpoint to provide results in *text/rdf+n3 * format
189- * ``any `` lets the endpoint return any format it pleases (note that if the
190- returned format is not JSON, XML or N3, it will be rendered as raw text)
191- * ``default `` selects a default format depending on the requested SPARQL
192- operation (N3 for ``DESCRIBE `` and ``CONSTRUCT ``, JSON for ``SELECT ``, *any *
193- for the rest)
194-
195-
196- ``%display ``
197- ............
198-
199- Sets the output rendering shape::
104+ The kernel behaviour can be controlled by the use of line magics (lines
105+ starting with ``% ``). See the `magics documentation `_ for details.
200106
201- %display raw | table [withtypes] | diagram [svg|png] [withliterals]
202107
203- There are three possible display formats:
108+ Logging
109+ -------
204110
205- * ``raw `` outputs the literal text returned by the SPARQL endpoint, in the
206- format that was requested (see ``%format `` magic)
207- * ``table `` generates a table with the result. The optional ``withtypes ``
208- modifier adds to each column an additional column that shows the data
209- type for each value
210- * ``diagram `` takes the RDF graph returned (makes sense only for N3 result
211- format) and generates an image with a rendering of the graph. For it to
212- work, the ``dot `` program from GraphViz must be available in the search path.
213- The modifier selects the image format. Default is SVG, which usually works
214- much better (PNG quality is lower, image size is fixed and cannot contain
215- hyperlinks).
111+ Settings defined by magics are always printed out in the cell result area
112+ (in red type) to inform what are the conditions in which a query is
113+ sent. Additionally, it is possible write logs that contain additional debug
114+ information.
216115
217- Default is ``table ``. Note that if the result format is not a supported format
218- for a table or diagram representation (i.e. it is not JSON/XML or N3), then raw
219- format will be used.
116+ The logging level is controlled by the ``%log `` magic. All logs are written to
117+ a single file, with the name ``sparqlkernel.log ``. Its default place is the
118+ machine temporal directory (e.g. ``/tmp `` in Linux, or ``C:/TMP `` in Windows).
119+ There are two possibilities to change its location:
220120
121+ * When installing the kernel, use the ``--logdir <dir> `` option
122+ * Before starting Jupyter, define the ``LOGDIR `` environment variable.
221123
222124
223125
@@ -227,3 +129,4 @@ format will be used.
227129.. _rdflib : https://github.com/RDFLib/rdflib
228130.. _Graphviz : http://www.graphviz.org/
229131.. _online Notebook viewer : http://nbviewer.jupyter.org/github/paulovn/sparql-kernel/blob/master/examples/
132+ .. _magics documentation : doc/magics.rst
0 commit comments