Metadata-Version: 2.4
Name: xmlcv
Version: 0.1.0
Summary: A flexible XML to document converter with dynamic element processing and plugin system
Home-page: https://github.com/trunghiahoang/xmlcv
Author: Trung Hia Hoang
Author-email: Trung Nghia Hoang <trunghia.hoang@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/trunghiahoang/xmlcv
Project-URL: Documentation, https://github.com/trunghiahoang/xmlcv#readme
Project-URL: Repository, https://github.com/trunghiahoang/xmlcv
Project-URL: Bug Tracker, https://github.com/trunghiahoang/xmlcv/issues
Project-URL: Changelog, https://github.com/trunghiahoang/xmlcv/blob/main/CHANGELOG.md
Keywords: xml,html,converter,document,format
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Text Processing :: Markup :: XML
Classifier: Topic :: Text Processing :: Markup :: HTML
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lxml>=4.9.0
Provides-Extra: pdf
Requires-Dist: weasyprint>=59.0; extra == "pdf"
Provides-Extra: pdfkit
Requires-Dist: pdfkit>=1.0.0; extra == "pdfkit"
Provides-Extra: docx
Requires-Dist: python-docx>=1.0.0; extra == "docx"
Provides-Extra: pptx
Requires-Dist: python-pptx>=0.6.0; extra == "pptx"
Provides-Extra: markdown
Requires-Dist: markdown>=3.4.0; extra == "markdown"
Provides-Extra: all
Requires-Dist: weasyprint>=59.0; extra == "all"
Requires-Dist: python-docx>=1.0.0; extra == "all"
Requires-Dist: python-pptx>=0.6.0; extra == "all"
Requires-Dist: markdown>=3.4.0; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: flake8>=6.0; extra == "dev"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 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
```bash
pip install xmlcv
```

### Optional Dependencies

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

```bash
# 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

```bash
xmlcv --list-plugins
```

## Quick Start

### Command Line

```bash
# 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)

```python
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)

```python
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

```python
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

```python
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

