Saxon-HE Python Processor

Warnings

• gotcha saxonche is the open-source Home Edition (HE). For Professional (PE) or Enterprise (EE) editions, you must install `saxoncpe` or `saxoncee` respectively, and set `license=True` on the `PySaxonProcessor`. These commercial editions require a valid license key.
  Fix: Ensure you install the correct package (`saxonche`, `saxoncpe`, or `saxoncee`) and manage licenses appropriately for commercial editions.
• gotcha When using `PySaxonProcessor(license=True)` for commercial editions, SaxonC requires a license file. By default, it looks for the license key in the directory identified by the `SAXONC_HOME` environment variable. You can also explicitly set the license file location using `proc.set_configuration_property("http://saxon.sf.net/feature/licenseFileLocation", "/path/to/saxon-license.lic")`.
  Fix: Set the `SAXONC_HOME` environment variable or programmatically set the `licenseFileLocation` property before performing any operations with a licensed processor.
• gotcha Converting between Python data types and XDM (XML Data Model) types is not always direct. For some types like strings and booleans, there's a close correspondence, but for numbers, dates, URIs, etc., it's less exact. Explicit conversion methods (e.g., `make_string_value`) might be necessary.
  Fix: Refer to the SaxonC Python API documentation for details on data type conversions and use appropriate `PySaxonProcessor` methods (like `make_string_value`, `make_boolean_value`, etc.) when passing values between Python and Saxon's XDM.
• gotcha As `saxonche` is a C extension, linters like Pylint might report `E0611: No name 'PySaxonProcessor' in module 'saxonche'` errors.
  Fix: Configure Pylint to allow importing from the C extension by adding `--extension-pkg-allow-list=saxonche` to your Pylint command or configuration file.
• breaking In SaxonC 12.5.0, breaking changes were introduced to `PyXdmFunctionItem` methods: `get_system_function()` is now a static method (previously an instance method), and the `PySaxonProcessor` argument has been removed from the `call()` method.
  Fix: Update your code to call `PyXdmFunctionItem.get_system_function()` as a static method and remove the `PySaxonProcessor` argument from calls to `PyXdmFunctionItem.call()`.
• gotcha When using the Python API on Windows, the specific `PySaxonApiError` exception is not available. Instead, a generic `RuntimeError` is thrown if any failures occur internally within SaxonC.
  Fix: On Windows, catch `RuntimeError` for Saxon-specific errors. For cross-platform compatibility, consider catching a broader `Exception` and inspecting the `proc.error_message()` for detailed error information.

Install

• pip install saxonche Install latest version

Imports

• PySaxonProcessor

  from saxonche import PySaxonProcessor

  PySaxonProcessor is the main entry point for creating various XML processors (XSLT, XQuery, etc.).

Quickstart

This example demonstrates how to perform an XSLT 3.0 transformation using `saxonche`. It initializes a `PySaxonProcessor`, parses an XML document, compiles an XSLT stylesheet, and then applies the transformation to produce an output string. It uses `license=False` to indicate the open-source Home Edition.

import os
from saxonche import PySaxonProcessor

# Create dummy XML and XSLT files for the example
xml_content = """
<doc>
    <item>Value 1</item>
    <item>Value 2</item>
</doc>
"""
xstl_content = """
<xsl:stylesheet version="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
    <xsl:template match="doc">
        <output>
            <xsl:apply-templates select="item"/>
        </output>
    </xsl:template>
    <xsl:template match="item">
        <transformed-item>
            <xsl:value-of select="."/>
        </transformed-item>
    </xsl:template>
</xsl:stylesheet>
"""

with open("input.xml", "w") as f:
    f.write(xml_content)
with open("transform.xsl", "w") as f:
    f.write(xstl_content)

try:
    # Initialize Saxon processor (license=False for open-source HE edition)
    with PySaxonProcessor(license=False) as proc:
        print(f"SaxonC Version: {proc.version()}")

        # Create XSLT 3.0 processor
        xslt_processor = proc.new_xslt30_processor()

        # Parse XML source document
        input_document = proc.parse_xml(xml_file_name="input.xml")
        if not input_document:
            print(f"Error parsing XML: {proc.error_message()}")
            exit(1)

        # Compile XSLT stylesheet
        stylesheet = xslt_processor.compile_stylesheet(stylesheet_file="transform.xsl")
        if not stylesheet:
            print(f"Error compiling XSLT: {xslt_processor.error_message()}")
            exit(1)

        # Perform transformation
        output = stylesheet.transform_to_string(xdm_node=input_document)
        if not output:
            print(f"Error during transformation: {xslt_processor.error_message()}")
            exit(1)

        print("Transformation Output:")
        print(output)

except Exception as e:
    print(f"An error occurred: {e}")
finally:
    # Clean up dummy files
    if os.path.exists("input.xml"):
        os.remove("input.xml")
    if os.path.exists("transform.xsl"):
        os.remove("transform.xsl")