XSLT transformations from a Python application

You can perform a transformation using the SaxonC Python interface as follows:

Create a PySaxonProcessor and set any global configuration options on the PySaxonProcessor object. If your stylesheet uses any features that require saxoncpe or saxoncee, be sure to use the constructor proc = PySaxonProcessor(license=True).
Call new_xslt30_processor() to create an PyXslt30Processor, and set any options that are local to a specific compilation (for example, the destination of error messages).

Error messages that occur during the compile phase are handled internally in SaxonC and thrown as the Python exception PySaxonApiError. Throwing exceptions is fine for an application run from a console, but not so good if it's executing on a web server, or behind a graphical interface. In such cases you'll want to catch the exception and handle it accordingly.
Call the compile_stylesheet() method to compile a stylesheet. The result is a pointer to the PyXsltExecutable object, which can be used as often as you like, in the same thread or in different threads.

The PyXsltExecutable class was introduced in SaxonC 11.1, and provides new ways of executing stylesheet code that are defined in the XSLT 3.0 specification, though Saxon also allows you to use the same entry points with 1.0 or 2.0 stylesheets. Among the new capabilities are:
- You can invoke a specific stylesheet function, with parameters, rather than invoking a named template or template rule.
- If you start execution with a named template or template rule, you can supply values for the parameters defined on that template, as well as the global stylesheet parameters, using the set_parameter() method. The PySaxonProcessor has a number of utility methods to create XDM objects, for example make_string_value() to create an PyXdmAtomicValue object from a char pointer array, which can be used for the values of parameters.
- Whether you execute a template or a function, you can return the results in raw string as a char pointer array, to file or as an XDM type. For example, a function (or template) might return a sequence of strings, or a single boolean, or a map, or even a function.
  
  It is possible to capture the secondary result documents into an std:map (as the pair URI key and PyXdmNode) using the set_capture_result_documents() method. This overrides the default mechanism of writing the result documents to file. To retrieve the result documents call the method get_result_documents() after the execution of the stylesheet.
- There is no longer any necessary relationship between the "principal source document" (if it still exists) and the context item for evaluating global variables. The two things are quite independent of each other.
  
  The principal source document can be set on the PyXsltExecutable using the set_initial_match_selection() method. The PySaxonProcessor provides a method parse_xml() for parsing XML documents from file or from a string literal; while the PyDocumentBuilder class is more feature rich, for instance it can be used to parse and validate XML documents by setting a PySchemaValidator.
  
  It is sometimes a requirement to supply the context item to be used when evaluating global variables and parameters; which can be done using the set_global_context_item() method.
For more details about the configuration options available, and how to set these properties and parameters, see Configuration in the SaxonC documentation.
To run a transformation, there are several methods available on the PyXsltExecutable to execute the compiled stylesheet. For example, to evaluate a stylesheet using apply-templates invocation there are three methods available: apply_templates_returning_string(), apply_templates_returning_value() and apply_templates_returning_file(). As the names suggest these methods return the output of the transformation as a serialized string (str), PyXdmValue object or file on disk, respectively. Similarly there are other methods available to initiate call-template invocation or function call invocation.

Alternatively, it is also possible to run one shot transformations using the methods transform_to_file(), transform_to_string() and transform_to_value() directly on the PyXslt30Processor without going through an explicit compilation process. But note that these methods have limited features and are not designed for XSLT 3.0. For XSLT 3.0 it is advisable to use the compile_stylesheet() method as above to create a PyXsltExecutable.