KDE 4.9 PyKDE API Reference

- KDE's Python API

# QueryServiceClient Class Reference

`from PyKDE4.nepomuk import *`

Inherits: QObject
Namespace: Nepomuk.Query

## Detailed Description

\class QueryServiceClient queryserviceclient.h Nepomuk/Query/QueryServiceClient

Convenience frontend to the %Nepomuk Query DBus Service

The QueryServiceClient provides an easy way to access the %Nepomuk Query Service without having to deal with any communication details. By default it monitors queries for changes.

Usage is simple: Create an instance of the client for each search you want to track. One instance may also be reused for subsequent queries if further updates of the persistent query are not necessary.

For quick queries which do not require any updates one of the static query methods can be used: syncQuery(), syncSparqlQuery(), or syncDesktopQuery().

Author:
  Sebastian Trueg <trueg@kde.org>

Since:
  4.4

## Signals

| entriesRemoved ([QUrl] entries)
| error (QString errorMessage)
| finishedListing ()
| newEntries ([Nepomuk.Query.Result] entries)
| resultCount (int count)
| serviceAvailabilityChanged (bool running)

## Methods

| __init__ (self, QObject parent=0)
bool | blockingDesktopQuery (self, QString query)
bool | blockingQuery (self, Nepomuk.Query.Query query)
bool | blockingSparqlQuery (self, QString query, {QString:Nepomuk.Types.Property} requestPropertyMap=Nepomuk.Query.RequestPropertyMap())
| close (self)
bool | desktopQuery (self, QString query)
QString | errorMessage (self)
bool | isListingFinished (self)
bool | query (self, Nepomuk.Query.Query query)
bool | sparqlQuery (self, QString query, {QString:Nepomuk.Types.Property} requestPropertyMap=Nepomuk.Query.RequestPropertyMap())

## Static Methods

bool | serviceAvailable ()
[Nepomuk.Query.Result] | syncDesktopQuery (QString query, bool ok=0)
[Nepomuk.Query.Result] | syncQuery (Nepomuk.Query.Query query, bool ok=0)
[Nepomuk.Query.Result] | syncSparqlQuery (QString query, {QString:Nepomuk.Types.Property} requestPropertyMap=Nepomuk.Query.RequestPropertyMap(), bool ok=0)

## Signal Documentation

entriesRemoved | ( | [QUrl] | entries
| ) |  |  |

Emitted if the search results changed when monitoring a query.

Parameters:

  | entries | A list of resource URIs identifying the resources that dropped out of the query results.

Signal syntax:
  `QObject.connect(source, SIGNAL("entriesRemoved(const QList<QUrl>&)"), target_slot)`

error | ( | QString | errorMessage
| ) |  |  |

Emitted when an error occurs. This typically happens in case the query service is not running or does not respond. No further signals will be emitted after this one.

Since:
  4.6

Signal syntax:
  `QObject.connect(source, SIGNAL("error(const QString&)"), target_slot)`

finishedListing | ( |  | ) |

Emitted when the initial listing has been finished, ie. if all results have been reported via newEntries. If no further updates are necessary the client should be closed now.

In case of an error this signal is not emitted.

\sa error()

Signal syntax:
  `QObject.connect(source, SIGNAL("finishedListing()"), target_slot)`

newEntries | ( | [Nepomuk.Query.Result] | entries
| ) |  |  |

Emitted for new search results. This signal is emitted both for the initial listing and for changes to the search.

Signal syntax:
  `QObject.connect(source, SIGNAL("newEntries(const QList<Nepomuk::Query::Result>&)"), target_slot)`

resultCount | ( | int | count
| ) |  |  |

The number of results that are reported via newEntries() before the finishedListing() signal.

Emitted once the count of the results is available. This might happen before the first result is emitted, in between the results, or in rare cases it could even happen after all results have been reported.

Also be aware that no count will be provided when using sparqlQuery()

Since:
  4.6

Signal syntax:
  `QObject.connect(source, SIGNAL("resultCount(int)"), target_slot)`

serviceAvailabilityChanged | ( | bool | running
| ) |  |  |

Emitted when the availability of the query service changes

Since:
  4.8

Signal syntax:
  `QObject.connect(source, SIGNAL("serviceAvailabilityChanged(bool)"), target_slot)`

## Method Documentation

__init__ | ( | self, |
|  | QObject | parent=0
| ) |  |  |

Create a new QueryServiceClient instance.

bool blockingDesktopQuery | ( | self, |
|  | QString | query
| ) |  |  |

Parameters:

  | query | a desktop query string which can be parsed by QueryParser.

\sa desktopQuery(const QString&), close()

bool blockingQuery | ( | self, |
|  | Nepomuk.Query.Query | query
| ) |  |  |

Start a query using the Nepomuk query service.

Results will be reported as with query(const QString&) but a local event loop will be started to block the method call until all results have been listed.

The client will be closed after the initial listing. Thus, changes to results will not be reported as it is the case with the non-blocking methods.

Parameters:

  | query | the query to perform.

Returns:
  true if the query service was found and the query was started. false otherwise.

\sa query(const Query&), close()

bool blockingSparqlQuery | ( | self, |
|  | QString | query,
|  | {QString:Nepomuk.Types.Property} | requestPropertyMap=Nepomuk.Query.RequestPropertyMap()
| ) |  |  |

Parameters:

  | query | a SPARQL query which binds results to variable 'r'.

Parameters:

  | requestPropertyMap | An optional mapping of variable binding names in query to their corresponding properties. For details see sparqlQuery.

\sa sparqlQuery(const Query&)

close | ( |  | self ) |

Close the client, thus stop to monitor the query for changes. Without closing the client it will continue signalling changes to the results.

This will also make any blockingQuery return immediately.

bool desktopQuery | ( | self, |
|  | QString | query
| ) |  |  |

Parameters:

  | query | a desktop query string which can be parsed by QueryParser.

QString errorMessage | ( |  | self ) |

The last error message which has been emitted via error() or an empty string if there was no error.

Since:
  4.6

bool isListingFinished | ( |  | self ) |

Returns:
  true if all results have been listed (ie. finishedListing() has been emitted), close() has been called, or no query was started.

Since:
  4.6

bool query | ( | self, |
|  | Nepomuk.Query.Query | query
| ) |  |  |

Start a query using the Nepomuk query service.

Results will be reported via newEntries. All results have been reported once finishedListing has been emitted.

Parameters:

  | query | the query to perform.

Returns:
  true if the query service was found and the query was started. false otherwise.

bool sparqlQuery | ( | self, |
|  | QString | query,
|  | {QString:Nepomuk.Types.Property} | requestPropertyMap=Nepomuk.Query.RequestPropertyMap()
| ) |  |  |

Parameters:

  | query | a SPARQL query which binds results to variable 'r'.

Parameters:

  | requestPropertyMap | An optional mapping of variable binding names in query to their corresponding properties. These bindings will then be reported via Result.requestProperties(). This map will be constructed automatically when using query(const Query&).

Examples:

Select a simple request property as can also be done via Query.Query:

     QString query = "select ?r ?mtime where { "
                     "?r a nfo:FileDataObject . "
                     "?r nie:lastModified ?mtime . "
                     "}";

     QueryServiceClient.RequestPropertyMap requestPropertyMap;
     requestPropertyMap.insert( "mtime", Vocabulary.NIE.lastModified() );

     sparqlQuery( query, requestPropertyMap );

This will report the resources themselves and their modification time in the result's request properties:

     void handleResult( const Query.Result& results ) {
         QDateTime lastModified = result.requestProperty( Vocabulary.NIE.lastModified() ).toDateTime();
         [...]

While using Query.Query restricts to request properties to diret properties of the results using a custom SPARQL query allows to use any binding as request property. The used property URI in the mapping does not even need to match anything in the query:

     QString query = "select ?r ?phone where { "
                     "?r a nco:PersonContact . "
                     "?r nco:hasPhoneNumber ?n . "
                     "?n nco:phoneNumber ?phone . "
                     "}";

     QueryServiceClient.RequestPropertyMap requestPropertyMap;
     requestPropertyMap.insert( "phone", Vocabulary.NCO.hasPhoneNumber() );

\sa Query.requestPropertyMap()

## Static Method Documentation

bool serviceAvailable | ( |  | ) |

Check if the Nepomuk query service is running.

Returns:
  true if the Nepomuk query service is running and could be contacted via DBus, false otherwise

[Nepomuk.Query.Result] syncDesktopQuery | ( | QString | query,
|  | bool | ok=0
| ) |  |  |

Parameters:

  | query | a desktop query string which can be parsed by QueryParser.

Parameters:

  | ok | a valid boolean pointer, which will be set to true if the query service was found and the query was started, false otherwise. If you don't want to track errors, you can pass a null pointer instead.

\sa desktopQuery(const QString&)

Since:
  4.5

[Nepomuk.Query.Result] syncQuery | ( | Nepomuk.Query.Query | query,
|  | bool | ok=0
| ) |  |  |

Start a query using the Nepomuk query service.

A local event loop will be started to block the method call until all results have been listed, and results will be returned. You can check if the query was successful through the ok pointer.

If updates to the query results are required an instance of QueryServiceClient should be created and one of the non-static query methods be used.

Parameters:

  | query | the query to perform.

Parameters:

  | ok | a valid boolean pointer, which will be set to true if the query service was found and the query was started, false otherwise. If you don't want to track errors, you can pass a null pointer instead.

Returns:
  a list of Result for the given query.

\sa query(const Query&)

Since:
  4.5

[Nepomuk.Query.Result] syncSparqlQuery | ( | QString | query,
|  | {QString:Nepomuk.Types.Property} | requestPropertyMap=Nepomuk.Query.RequestPropertyMap(),
|  | bool | ok=0
| ) |  |  |

Parameters:

  | query | a SPARQL query which binds results to variable 'r'.

Parameters:

  | ok | a valid boolean pointer, which will be set to true if the query service was found and the query was started, false otherwise. If you don't want to track errors, you can pass a null pointer instead.

Parameters:

  | requestPropertyMap | An optional mapping of variable binding names in query to their corresponding properties. For details see sparqlQuery.

\sa sparqlQuery(const Query&)

Since:
  4.5