Skip to content

CLAUDE.md

Latest commit

 

History

History
86 lines (66 loc) · 3.4 KB

CLAUDE.md

File metadata and controls

86 lines (66 loc) · 3.4 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a sloppy XML parser library for Python - a single-file XML parser designed to handle malformed XML gracefully while maintaining high performance through pre-compiled regular expressions. The library provides both streaming and tree-building XML parsing capabilities with robust error recovery mechanisms for handling malformed XML commonly generated by LLMs and other automated systems.

Development Commands

Package Management

This project uses uv as the package manager:

  • uv sync - Install/update dependencies and sync the environment
  • uv add <package> - Add a new dependency
  • uv add --dev <package> - Add a dev only dependency
  • uv remove <package> - Remove a dependency
  • uv remove --dev <package> - Remove a dev only dependency
  • uv run <command> - Run commands in the project environment

Testing

  • uv run pytest - Run all tests
  • uv run pytest tests/test_sloppy_xml.py - Run specific test file
  • uv run pytest -v - Run tests with verbose output
  • uv run pytest tests/test_enhanced_recovery.py - Run enhanced recovery tests

Linting & Formatting

  • uv run ruff check - Check code style and quality
  • uv run ruff format - Format code automatically
  • uv run ruff check --fix - Fix auto-fixable issues

Building

  • uv build - Build source distribution and wheel packages

Architecture

The parser implements an event-based streaming architecture with these key components:

Core Event Types (Named Tuples)

  • StartElement - Opening XML tags with attributes, line/column info
  • EndElement - Closing XML tags with auto-close detection
  • Text - Text content between tags with CDATA flag
  • Comment - XML comments
  • ProcessingInstruction - Processing instructions like <?xml?>
  • EntityRef - Entity references with resolution
  • ParseError - Error events with recovery information

State Machine

Parser uses enum-based states: INITIAL, IN_TAG, IN_TEXT, IN_COMMENT, IN_CDATA, IN_PI, ERROR_RECOVERY, COMPLETE

Error Recovery

  • Tag stack management for auto-closing mismatched tags
  • Graceful handling of malformed attributes and entities
  • CDATA fallback mechanisms
  • Entity resolution for HTML entities and numeric entities

API Functions

  • stream_parse() - Main streaming parser returning event iterator
  • tree_parse() - Convenience function for ElementTree construction
  • ETreeBuilder - Tree builder for constructing ElementTree objects

File Structure

  • sloppy_xml.py - Main parser implementation (single file)
  • tests/test_sloppy_xml.py - Comprehensive test suite
  • tests/test_enhanced_recovery.py - Enhanced error recovery tests
  • ARCHITECTURE.md - Detailed architectural specification
  • TODO.md - Development todo list
  • pyproject.toml - Project configuration with dependencies

Current Development Status

See TODO.md for pending tasks. Key areas of active development:

  • Optimizing text event emission
  • Making ElementTreeBuilder generic for lxml compatibility
  • Improving error handling and reporting
  • Performance optimizations

Testing Strategy

The test suite covers:

  • Well-formed XML parsing validation
  • Malformed XML recovery scenarios
  • Entity resolution (standard HTML entities + numeric)
  • Performance benchmarks
  • Edge cases and boundary conditions
  • Real-world malformed XML from LLM outputs