{"id":4757,"library":"saxonche","title":"Saxon-HE Python Processor","description":"saxonche is the official Saxonica Python wheel package for the SaxonC-HE processor, an XML document processor. It provides APIs to run XSLT 3.0 transformations, XQuery 3.1 queries, XPath 3.1, and XML Schema validation. This library allows Python developers to leverage Saxon's robust and standards-compliant XML processing capabilities, including experimental support for draft 4.0 specifications.","status":"active","version":"12.9.0","language":"en","source_language":"en","source_url":"https://github.com/Saxonica/Saxon-HE","tags":["xml","xslt","xquery","xpath","xml-schema"],"install":[{"cmd":"pip install saxonche","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Required Python version for saxonche library.","package":"python","optional":false}],"imports":[{"note":"PySaxonProcessor is the main entry point for creating various XML processors (XSLT, XQuery, etc.).","symbol":"PySaxonProcessor","correct":"from saxonche import PySaxonProcessor"}],"quickstart":{"code":"import os\nfrom saxonche import PySaxonProcessor\n\n# Create dummy XML and XSLT files for the example\nxml_content = \"\"\"\n<doc>\n    <item>Value 1</item>\n    <item>Value 2</item>\n</doc>\n\"\"\"\nxstl_content = \"\"\"\n<xsl:stylesheet version=\"3.0\" xmlns:xsl=\"http://www.w3.org/1999/XSL/Transform\">\n    <xsl:template match=\"doc\">\n        <output>\n            <xsl:apply-templates select=\"item\"/>\n        </output>\n    </xsl:template>\n    <xsl:template match=\"item\">\n        <transformed-item>\n            <xsl:value-of select=\".\"/>\n        </transformed-item>\n    </xsl:template>\n</xsl:stylesheet>\n\"\"\"\n\nwith open(\"input.xml\", \"w\") as f:\n    f.write(xml_content)\nwith open(\"transform.xsl\", \"w\") as f:\n    f.write(xstl_content)\n\ntry:\n    # Initialize Saxon processor (license=False for open-source HE edition)\n    with PySaxonProcessor(license=False) as proc:\n        print(f\"SaxonC Version: {proc.version()}\")\n\n        # Create XSLT 3.0 processor\n        xslt_processor = proc.new_xslt30_processor()\n\n        # Parse XML source document\n        input_document = proc.parse_xml(xml_file_name=\"input.xml\")\n        if not input_document:\n            print(f\"Error parsing XML: {proc.error_message()}\")\n            exit(1)\n\n        # Compile XSLT stylesheet\n        stylesheet = xslt_processor.compile_stylesheet(stylesheet_file=\"transform.xsl\")\n        if not stylesheet:\n            print(f\"Error compiling XSLT: {xslt_processor.error_message()}\")\n            exit(1)\n\n        # Perform transformation\n        output = stylesheet.transform_to_string(xdm_node=input_document)\n        if not output:\n            print(f\"Error during transformation: {xslt_processor.error_message()}\")\n            exit(1)\n\n        print(\"Transformation Output:\")\n        print(output)\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\nfinally:\n    # Clean up dummy files\n    if os.path.exists(\"input.xml\"):\n        os.remove(\"input.xml\")\n    if os.path.exists(\"transform.xsl\"):\n        os.remove(\"transform.xsl\")","lang":"python","description":"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."},"warnings":[{"fix":"Ensure you install the correct package (`saxonche`, `saxoncpe`, or `saxoncee`) and manage licenses appropriately for commercial editions.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Set the `SAXONC_HOME` environment variable or programmatically set the `licenseFileLocation` property before performing any operations with a licensed processor.","message":"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\")`.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Configure Pylint to allow importing from the C extension by adding `--extension-pkg-allow-list=saxonche` to your Pylint command or configuration file.","message":"As `saxonche` is a C extension, linters like Pylint might report `E0611: No name 'PySaxonProcessor' in module 'saxonche'` errors.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Update your code to call `PyXdmFunctionItem.get_system_function()` as a static method and remove the `PySaxonProcessor` argument from calls to `PyXdmFunctionItem.call()`.","message":"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.","severity":"breaking","affected_versions":"12.5.0 and later"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}