xmlcv 0.1.0

A flexible XML to document converter with dynamic element processing and plugin system

XMLCV

A flexible Python library for converting XML files to various document formats with dynamic element processing and plugin system.

Features

• 🔄 Dynamic Element Processing: Automatically analyzes XML structure and processes elements accordingly
• 📄 Multiple Format Support: Handles various XML schemas by loading element definitions from XML
• 🎨 Customizable Styling: Support for custom CSS and styling options
• 📑 Table of Contents: Automatic TOC generation
• 📊 PDF Export: Optional PDF conversion using WeasyPrint or pdfkit
• 🔧 Extensible: Easy to add custom element processors

Installation

Basic Installation

pip install xmlcv

Optional Dependencies

The package has optional dependencies for different output formats. You can install them individually or all at once:

# Install specific formats
pip install 'xmlcv[pdf]'      # PDF support
pip install 'xmlcv[docx]'      # DOCX support
pip install 'xmlcv[pptx]'    # PPTX support
pip install 'xmlcv[markdown]' # Markdown support

# Install multiple formats
pip install 'xmlcv[pdf,docx]'

# Install all formats
pip install 'xmlcv[all]'

List Available Plugins

xmlcv --list-plugins

Quick Start

Command Line

# List available output formats
xmlcv --list-plugins

# Convert single file to HTML (default)
xmlcv input.xml -o output.html

# Convert to different formats
xmlcv input.xml --format pdf -o output.pdf
xmlcv input.xml --format docx -o output.docx

# Convert directory
xmlcv input_dir/ -o output_dir/

# Analyze XML structure
xmlcv input.xml --analyze

Python API

Using XMLConverter (New Plugin System)

from xmlcv import XMLConverter, ConverterConfig
from pathlib import Path

# Basic usage with plugin system
converter = XMLConverter()

# List available plugins
plugins = converter.list_plugins()
for plugin in plugins:
    print(f"{plugin.name}: {plugin.description}")

# Convert to different formats
converter.convert(Path("input.xml"), Path("output.html"), output_format="html")
converter.convert(Path("input.xml"), Path("output.pdf"), output_format="pdf")

# Convert to multiple formats at once
converter.convert_to_multiple_formats(
    Path("input.xml"),
    output_formats=["html", "pdf"]
)

Using XMLToHTMLConverter (Legacy API)

from xmlcv import XMLToHTMLConverter, ConverterConfig
from pathlib import Path

# Basic usage
converter = XMLToHTMLConverter()
html = converter.convert_file(
    Path("input.xml"),
    Path("output.html")
)

# With custom configuration
config = ConverterConfig(
    convert_to_pdf=True,
    include_navigation=True,
    custom_css="/* your custom CSS */"
)
converter = XMLToHTMLConverter(config)
html = converter.convert_file(Path("input.xml"), Path("output.html"))

# Convert entire directory
converter.convert_directory(
    Path("xml_files/"),
    Path("html_output/")
)

Advanced Usage

Custom Element Processors

from xmlcv import XMLToHTMLConverter, ConverterConfig
import xml.etree.ElementTree as ET

def custom_processor(element: ET.Element, context: dict) -> str:
    """Custom processor for a specific element"""
    text = element.text or ""
    return f'<div class="custom">{text}</div>'

# Register custom processor
config = ConverterConfig()
config.element_processors['CustomElement'] = custom_processor

converter = XMLToHTMLConverter(config)

Analyzing XML Structure

from xmlcv import XMLToHTMLConverter
from pathlib import Path

converter = XMLToHTMLConverter()
structure = converter.analyze_xml(Path("input.xml"))

print(f"Elements found: {structure['elements']}")
print(f"Hierarchy: {structure['hierarchy']}")

Supported Elements

The converter dynamically supports various XML elements including:

• Structure: Document, Title, Body, MainContent
• Organization: Chapter, Section, Subsection, Article
• Content: Paragraph, Sentence, Item, Subitem1, Subitem2
• Tables: TableStruct, Table, TableRow, TableColumn
• Special: Statement, Provision, Appendix, TOC
• Formatting: Ruby (annotations), Sub (subscript), and more

Configuration

ConverterConfig Options

• output_dir: Output directory path
• create_index: Create index.html page
• convert_to_pdf: Enable PDF conversion
• css_file: Path to custom CSS file
• custom_css: Custom CSS string
• include_toc: Include table of contents
• include_navigation: Include navigation sidebar
• element_processors: Dictionary of custom element processors
• pdf_options: PDF generation options

Requirements

• Python 3.8+
• lxml >= 4.9.0

Optional:

• weasyprint >= 59.0 (for PDF export)
• pdfkit >= 1.0.0 (alternative PDF export)

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Changelog

0.1.0

• Initial release
• Dynamic element processing
• Support for various XML structures
• PDF export support
• CLI interface