saxonche

library13.0.0pypypi✓ verified 21d ago

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.

serialization data

pip install saxonche

package ↗homepage ↗docs ↗

INSTALL

IMPORT

SIG · SAXONCHE

saxonche

serializationpythonv13.0.0

Install

3.0s avg

Import

10ms

Disk

135MB

Pass rate

5/ 10

Env Coverage5 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v13.0.0 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

py 3.10–3.95 runs

build_error

glibc

py 3.10–3.95 runs

installs and imports cleanly · install 3.0s · import 0.010s · 137MB

135MB installed

● package 135MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

PySaxonProcessor

✓ from saxonche import PySaxonProcessor

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

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")

Debug

Known issues

gotchasaxonche 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.

affects: All versions

gotchaWhen 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.

affects: All versions

gotchaConverting 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.

affects: All versions

gotchaAs `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.

affects: All versions

breakingIn 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()`.

affects: 12.5.0 and later

gotchaWhen 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.

affects: All versions

Errors

Common errors & fixes

ModuleNotFoundError: No module named 'saxonche'

The `saxonche` package is not installed in the current Python environment or the environment is not active.

fix

Run `pip install saxonche` to install the library.

OSError: Could not find the Saxon-C library. Please ensure it is correctly installed and accessible.

The underlying Saxon-C shared library, which `saxonche` depends on, could not be located or loaded, possibly due to an incomplete or corrupted installation, or platform incompatibility.

fix

Reinstall `saxonche` using `pip install --no-cache-dir saxonche` to ensure a fresh download and installation. Verify Python version and system architecture compatibility.

AttributeError: 'XsltProcessor' object has no attribute 'transform'

An attempt was made to call a method named `transform` which does not exist on the `XsltProcessor` object; the correct method for transforming to a string is `transform_to_string`.

fix

Use the correct method name according to the `saxonche` API, such as `transform_to_string`, `transform_to_file`, or `transform_to_xdm_value`.
```python
import saxonche

with saxonche.PySaxonProcessor(license=False) as saxon:
    xsltproc = saxon.new_xslt30_processor()
    xml_doc = saxon.parse_xml(xml_text='<data/>')
    xslt_doc = saxon.parse_xml(xml_text='<xsl:stylesheet version="3.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform"><xsl:template match="/"><output/></xsl:template></xsl:stylesheet>')
    result = xsltproc.transform_to_string(source=xml_doc, stylesheet=xslt_doc)
```

saxonche.SaxonApiException: XSLT compilation failed: XTSE0010: A stylesheet must start with xsl:stylesheet or xsl:transform

The provided XSLT stylesheet (or XQuery expression, or XPath expression) is syntactically or semantically invalid according to Saxon's rules, causing the underlying Saxon-C processor to fail compilation or execution.

fix

Carefully review and correct the XSLT stylesheet for syntax errors, missing root elements (`xsl:stylesheet` or `xsl:transform`), or structural issues. Refer to XSLT specifications for guidance.

Upgrade

Version history

13.0.0latest on PyPI · released May 29, 2026

Audit

Dependencies

pythonrequiredRequired Python version for saxonche library.

Agent activity

17 hits · last 30 days

node

OpenAI (training)

Resources

packagehttps://pypi.org/project/saxonche/ ↗

homepagehttps://www.saxonica.com/saxon-c/index.xml ↗

docshttps://www.saxonica.com/saxon-c/documentation12/index.html ↗