Skip to content

PythonQt.QtXmlPatterns.QXmlQuery

QXmlQuery

PythonQtInstanceWrapper object

Native bases: PythonQtInstanceWrapper

Supplemental documentation: Qt 5 reference:

Detailed Description

The QXmlQuery class compiles and executes queries written in the XQuery language. QXmlQuery is typically used to query XML data, but it can also query non-XML data that has been modeled to look like XML.

Using QXmlQuery to query XML data, as in the snippet below, is simple because it can use the built-in XML data model as its delegate to the underlying query engine for traversing the data. The built-in data model is specified in XQuery 1.0 and XPath 2.0 Data Model.

QXmlQuery query;
query.setQuery("doc('index.html')/html/body/p[1]");

QXmlSerializer serializer(query, myOutputDevice);
query.evaluateTo(&serializer);

The example uses QXmlQuery to match the first paragraph of an XML document and then output the result to a device as XML.

Using QXmlQuery to query non-XML data requires writing a subclass of QAbstractXmlNodeModel to use as a replacement for the built-in XML data model. The custom data model will be able to traverse the non-XML data as required by the QAbstractXmlNodeModel interface. An instance of this custom data model then becomes the delegate used by the query engine to traverse the non-XML data. For an example of how to use QXmlQuery to query non-XML data, see the documentation for QAbstractXmlNodeModel.

Running XQueries

To run a query set up with QXmlQuery, call one of the evaluation functions.

  • evaluateTo(QAbstractXmlReceiver *) is called with a pointer to an XML receiver, which receives the query results as a sequence of callbacks. The receiver callback class is like the callback class used for translating the output of a SAX parser. QXmlSerializer, for example, is a receiver callback class for translating the sequence of callbacks for output as unformatted XML text.

  • evaluateTo(QXmlResultItems *) is called with a pointer to an iterator for an empty sequence of query result items. The Java-like iterator allows the query results to be accessed sequentially.

  • evaluateTo(QStringList *) is like evaluateTo(QXmlResultItems *), but the query must evaluate to a sequence of strings.

Running XPath Expressions

The XPath language is a subset of the XQuery language, so running an XPath expression is the same as running an XQuery query. Pass the XPath expression to QXmlQuery using setQuery().

Running XSLT Stylesheets

Running an XSLT stylesheet is like running an XQuery, except that when you construct your QXmlQuery, you must pass QXmlQuery::XSLT20 to tell QXmlQuery to interpret whatever it gets from setQuery() as an XSLT stylesheet instead of as an XQuery. You must also set the input document by calling setFocus().

    QXmlQuery query(QXmlQuery::XSLT20);
    query.setFocus(QUrl("myInput.xml"));
    query.setQuery(QUrl("myStylesheet.xsl"));
    query.evaluateTo(out);

Note: Currently, setFocus() must be called before setQuery() when using XSLT.

Another way to run an XSLT stylesheet is to use the xmlpatterns command line utility.

xmlpatterns myStylesheet.xsl myInput.xml

Note: For the current release, XSLT support should be considered experimental. See section XSLT conformance for details.

Stylesheet parameters are bound using bindVariable().

Binding A Query To A Starting Node

When a query is run on XML data, as in the snippet above, the doc() function returns the node in the built-in data model where the query evaluation will begin. But when a query is run on a custom node model containing non-XML data, one of the bindVariable() functions must be called to bind a variable name to a starting node in the custom model. A $variable reference is used in the XQuery text to access the starting node in the custom model. It is not necessary to declare the variable name external in the query. See the example in the documentation for QAbstractXmlNodeModel.

Reentrancy and Thread-Safety

QXmlQuery is reentrant but not thread-safe. It is safe to use the QxmlQuery copy constructor to create a copy of a query and run the same query multiple times. Behind the scenes, QXmlQuery will reuse resources such as opened files and compiled queries to the extent possible. But it is not safe to use the same instance of QXmlQuery in multiple threads.

Error Handling

Errors can occur during query evaluation. Examples include type errors and file loading errors. When an error occurs:

Resource Management

When a query runs, it parses documents, allocating internal data structures to hold them, and it may load other resources over the network. It reuses these allocated resources when possible, to avoid having to reload and reparse them.

When setQuery() is called, the query text is compiled into an internal data structure and optimized. The optimized form can then be reused for multiple evaluations of the query. Since the compile-and-optimize process can be expensive, repeating it for the same query should be avoided by using a separate instance of QXmlQuery for each query text.

Once a document has been parsed, its internal representation is maintained in the QXmlQuery instance and shared among multiple QXmlQuery instances.

An instance of QCoreApplication must exist before QXmlQuery can be used.

Event Handling

When QXmlQuery accesses resources (e.g., calling fn:doc() to load a file, or accessing a device via a bound variable), the event loop is used, which means events will be processed. To avoid processing events when QXmlQuery accesses resources, create your QXmlQuery instance in a separate thread.

Source: https://doc.qt.io/archives/qt-5.15/qxmlquery.html

Complete member index

Every captured member retains its own identity. Identical captured declaration text is linked once; this does not establish native inheritance or interchangeable objects.

Member Kind Signature Summary
QueryLanguage attribute type Convert a number or string to an integer, or return 0 if no arguments are given.
XPath20 attribute QueryLanguage
XQuery10 attribute QueryLanguage
XSLT20 attribute QueryLanguage
XmlSchema11IdentityConstraintField attribute QueryLanguage
XmlSchema11IdentityConstraintSelector attribute QueryLanguage
__init__ function (self, *args: Any, **kwargs: Any) -> None Native constructor; consult class documentation for supported overloads. (shared captured text)
bindVariable function (self, localName: Any, arg__2: Any) -> None X.bindVariable(localName, arg__2)
className function (self, *args: Any, **kwargs: Any) -> Any Return the classname of the object (shared captured text)
delete function (self, *args: Any, **kwargs: Any) -> Any Deletes the C++ object (at your own risk, my friend!) (shared captured text)
evaluateTo function (self, target: Any) -> bool X.evaluateTo(target) -> bool
help function (self, *args: Any, **kwargs: Any) -> Any Shows the help of available methods for this class (shared captured text)
inherits function (self, *args: Any, **kwargs: Any) -> Any Returns if the class inherits or is of given type name (shared captured text)
initialTemplateName function (self) -> Any X.initialTemplateName() -> PythonQt.QtXmlPatterns.QXmlName
isValid function (self) -> bool X.isValid() -> bool
messageHandler function (self) -> Any X.messageHandler() -> PythonQt.QtXmlPatterns.QAbstractMessageHandler
namePool function (self) -> Any X.namePool() -> PythonQt.QtXmlPatterns.QXmlNamePool
networkAccessManager function (self) -> Any X.networkAccessManager() -> PythonQt.QtNetwork.QNetworkAccessManager
operator_assign function (self, other: Any) -> Any X.operator_assign(other) -> PythonQt.QtXmlPatterns.QXmlQuery
queryLanguage function (self) -> Any Returns a value indicating what this [QXmlQuery](https://doc.qt.io/archives/qt-5.15/qxmlquery.html) is being used for.
setFocus function (self, document: Any) -> bool X.setFocus(document) -> bool
setInitialTemplateName function (self, name: Any) -> None Sets the name of the initial template.
setMessageHandler function (self, messageHandler: Any) -> None Changes the [message handler](https://doc.qt.io/archives/qt-5.15/qabstractmessagehandler.html) for this [QXmlQuery](https://doc.qt.io/archives/qt-5.15/qxmlquery.html) to aMessageHandler.
setNetworkAccessManager function (self, newManager: Any) -> Any Sets the network manager to newManager.
setQuery function (self, sourceCode: Any, documentURI: Any) -> None X.setQuery(sourceCode, documentURI)
setUriResolver function (self, resolver: Any) -> None Sets the URI resolver to resolver.
uriResolver function (self) -> Any X.uriResolver() -> PythonQt.QtXmlPatterns.QAbstractUriResolver