<div align="center">
  <img src="https://github.com/mitsuhiko/sloppy-xml-py/raw/main/logo.svg" alt="" width=240>
  <p><strong>A sloppy XML parser for Python designed to handle malformed XML gracefully.</strong></p>

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/mitsuhiko/sloppy-xml-py/blob/main/LICENSE)
[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://python.org)
[![Tests](https://img.shields.io/badge/tests-passing-green.svg)](https://github.com/mitsuhiko/sloppy-xml-py)

</div>

Sloppy XML is a single-file XML parser library that prioritizes resilience over strict XML compliance. In fact it tries not to be XML compliant at all. It's specifically designed to handle malformed XML commonly generated by LLMs, automated systems, and other sources where perfect XML structure cannot be guaranteed.

The parser provides both streaming and tree-building capabilities with robust error recovery mechanisms, making it ideal for parsing XML from unreliable sources while maintaining reasonable performance.

**Note:** this library was 100% AI generated with Claude Code and used experimentally for some evals I'm doing.  I will try to fix it up as good as possible as I ran into issues, but I cannot vouch for the quality of it.

## Goals

* **Graceful Error Recovery**: Handle malformed XML without crashing
* **Dual API**: Both streaming events and ElementTree construction
* **Zero Dependencies**: Single file with only standard library dependencies
* **LLM-Friendly**: Specifically designed for XML generated by language models
* **Detailed Diagnostics**: Rich error reporting with line/column information

## Quick Example

```python
import sloppy_xml

# Streaming API - handle malformed XML gracefully
xml_content = '''
<root>
    <item name="test" broken-attr=>
        Some text with <unclosed-tag>
        <!-- Malformed comment --
    </item>
</root>
'''

# Stream parsing with error recovery
for event in sloppy_xml.stream_parse(xml_content):
    if isinstance(event, sloppy_xml.StartElement):
        print(f"Start: {event.name}, attrs: {event.attrs}")
    elif isinstance(event, sloppy_xml.EndElement):
        print(f"End: {event.name}")
    elif isinstance(event, sloppy_xml.Text):
        print(f"Text: {repr(event.content)}")
    elif isinstance(event, sloppy_xml.ParseError):
        print(f"Error recovered: {event.message} at {event.line}:{event.column}")

# Tree parsing - get an ElementTree despite malformed input
root = sloppy_xml.tree_parse(xml_content)
print(f"Parsed tree with root: {root.tag}")
```

## Event Types

The streaming parser emits these event types:

* **`StartElement`** - Opening tags with attributes and position info
* **`EndElement`** - Closing tags (including auto-closed mismatched tags)
* **`Text`** - Text content with CDATA detection
* **`Comment`** - XML comments
* **`ProcessingInstruction`** - Processing instructions like `<?xml?>`
* **`EntityRef`** - Entity references with automatic resolution
* **`ParseError`** - Recoverable parsing errors with diagnostic information

## Error Recovery Features

* **Tag Stack Management**: Automatically closes mismatched opening tags
* **Malformed Attribute Handling**: Recovers from broken attribute syntax
* **Entity Resolution**: Handles standard HTML entities and numeric references
* **CDATA Fallback**: Treats malformed CDATA as regular text
* **Comment Recovery**: Handles unclosed comments gracefully
* **State Recovery**: Returns parser to valid state after errors

## API Functions

### Streaming API

```python
sloppy_xml.stream_parse(xml_input)
```

Returns an iterator of events for streaming XML processing.

### Tree API  

```python
sloppy_xml.tree_parse(xml_input)
```

Returns an `xml.etree.ElementTree.Element` root node.

## Installation

```bash
uv add sloppy-xml-py
```

## Development

This project uses [uv](https://github.com/astral-sh/uv) for dependency management:

```bash
# Setup
uv sync

# Run tests
uv run pytest

# Format code
uv run ruff format

# Check code quality
uv run ruff check

# Build package
uv build
```

## Similar Projects

* **xml.etree.ElementTree** (stdlib) - Strict XML parsing, no error recovery
* **lxml** - Fast XML parsing with some error tolerance
* **BeautifulSoup** - HTML/XML parsing with tag soup handling

Sloppy XML fills the gap for applications that need structured XML parsing with aggressive error recovery, particularly for machine-generated content.

## Sponsor

If you like the project and find it useful you can [become a
sponsor](https://github.com/sponsors/mitsuhiko).

## License and Links

- [Issue Tracker](https://github.com/mitsuhiko/sloppy-xml-py/issues)
- License: [Apache-2.0](https://github.com/mitsuhiko/sloppy-xml-py/blob/main/LICENSE)
