XMLGenerator Documentation

Welcome to the documentation for the XMLGenerator package.

XMLGenerator

This project provides a Python package pyxmlgenerator, which generates XML instances matching the provided XML Schema (XSD) input. The package is written in Rust with PyO3 Python bindings allowing direct use from Python. The pyxmlgenerator package is a wrapper for the xmlgenerator Rust crate, which generates the XML from a given schema.

The project includes several additional Cargo crates to achieve this goal:

file_to_string - For reading text files
xsdvalidator - For validating input XSD
regextranslator - For translating from XSD pattern style regular expressions to Rust style
xsdtestdata - Test data manager for the xsdtests database

Additionally, the project also includes a Python wrapper for the xsdtestdata crate - pyxsdtestdata. This allows the test data to be accessed directly from Python.

Dependencies

System requirements:

Cargo - Installed via Rustup
libxml2-rs - Rust bindings for the libxml2 C library
Python - Required for Python bindings pyxmlgenerator
uv - Recommended for installation of Python packages (Optional)

Build

To build the Rust xmlgenerator library, simply run:

cargo build

To run the Rust test suite, use:

cargo test

To build the Python wrapper pyxmlgenerator, run:

uv sync --package pyxmlgenerator

To run the Python test suite, use:

uv run pytest

Usage

The library can be used either from Python or Rust. Here are examples of each:

Python

The following example illustrates a similar workflow in Python, using the built-in argparse and pathlib libraries to read and validate command-line input.

import pathlib
import argparse
import pyxmlgenerator

from xmlschema importXMLSchema

parser = argparse.ArgumentParser()
parser.add_argument("filepaths", type=pathlib.Path, nargs='+')

args = parser.parse_args()

paths = args.filepaths

xml_generator = pyxmlgeneratorXMLGenerator()

for path in paths:
    path_str = str(path)

    # Validate file
    try:
        xml_generator.validate(path_str)
    except pyxmlgenerator.XSDValidatorError:
        print(f"Invalid file: {path}")
        exit(0)

    print(f"Valid file: {path}")
    try:
        output = xml_generator.generate()
    except:
        print("Error running generator")
        exit(0)

    print("Output generated!")

    # Generate sc
    schema =XMLSchema(path_str)

    if schema.is_valid(output):
        print("Output is valid")
    else:
        print("Output does not match input schema")

This example uses Python’s xmlschema library to validate output XML strings.

Rust

The following is an example of a simplified program which reads a list of filepaths from command-line arguments and generates example XML output strings for each valid XSD.

use std::env;
use std::path::PathBuf;
use std::str::FromStr;
use xmlgenerator:XMLGenerator;

fn main() {
    let generator =XMLGenerator::new();
    let args: Vec<String> = env::args().collect();
    if args.is_empty() {
        println!("No files provided!");
        println!("Usage: ./example [files] ...");
        return;
    }

    println!("Reading {} input files...", args.len());
    for arg in args {
        let path = PathBuf::from_str(arg.as_str()).unwrap();

        // Validate file
        if let Err(error) = generator.validate(&path) {
            println!("Invalid file: {}", path);
            return;
        }

        println!("Valid input file: {}", path);
        let output = match generator.generate(&path, None) {
            Ok(out) => out,
            Err(e) => {
                eprintln!("Error running generator: {}", path);
                eprintln!("Error: {}", e);
                return;
            }
        };

        println!("Output generated!");
        println!("Output:");
        println!(output);
    }
}

NOTE: Only a single XMLGenerator` should be created. Multiple instances of this class cause undefined behaviour.

Limitations

Not all features of the XSD specification have been implemented, if these features are encountered, an unimplemented error is thrown.

Contents:

Index

Index