DDEX Builder - Python Bindings

Generate deterministic, industry-compliant DDEX XML files from Python data structures with consistent reproducibility. Build DDEX messages from dictionaries, DataFrames, or parsed objects with built-in validation and partner-specific presets.

Installation

pip install ddex-builder
# or for specific version
pip install ddex-builder==0.4.4

Version Notes

v0.4.4: Enhanced compatibility with ddex-parser v0.4.4's strict validation. Improved round-trip workflows with better error handling.

v0.4.0: PyO3 0.24 upgrade for enhanced security and compatibility.

Quick Start

from ddex_builder import DDEXBuilder
import pandas as pd

# Create builder with validation
builder = DDEXBuilder(validate=True)

# Build from dictionary
release_data = {
    'message_header': {
        'sender_name': 'My Label',
        'message_id': 'MSG123',
    },
    'releases': [{
        'title': 'My Album',
        'main_artist': 'Great Artist',
        'tracks': [{
            'title': 'Track 1',
            'duration': 180,
            'isrc': 'US1234567890'
        }]
    }]
}

xml_output = builder.build_from_dict(release_data, version='4.3')
print(xml_output[:100] + '...')

Features

🎯 Deterministic Output

• 100% reproducible XML generation with stable hash IDs
• DB-C14N/1.0 canonicalization for deterministic consistency
• IndexMap-based ordering ensures identical output across runs
• Content-addressable resource IDs for reliable references

🏭 Industry Presets

• YouTube Music: Content ID and monetization standards
• Generic: Default preset suitable for most distributors

📊 DataFrame Integration

• Build directly from pandas DataFrames
• Automatic schema detection and validation
• Support for hierarchical data structures
• Export/import workflows with CSV and Parquet

🔒 Built-in Validation

• Comprehensive DDEX schema validation
• Business rule enforcement
• Reference integrity checking
• Territory and rights validation

🚀 High Performance

• Native Rust implementation with Python bindings
• Streaming generation for large catalogs
• Memory-efficient processing
• Parallel resource processing

API Reference

DDEXBuilder

from ddex_builder import DDEXBuilder

builder = DDEXBuilder(
    validate=True,           # Enable validation (recommended)
    preset='generic',        # Use generic industry preset
    canonical=True,          # Generate canonical XML
    streaming=False,         # Enable streaming mode for large data
    max_memory=100_000_000   # Memory limit in bytes
)

Performance Benchmarks

Building performance on different dataset sizes:

Memory usage scales linearly, with streaming mode keeping usage constant for any dataset size.

Integration with ddex-parser

Round-trip compatibility with ddex-parser for complete workflows:

from ddex_parser import DDEXParser
from ddex_builder import DDEXBuilder

# Parse existing DDEX file
parser = DDEXParser()
original = parser.parse_file("input.xml")

# Modify data
modified_data = original.to_dict()
modified_data['tracks'][0]['title'] = "New Title"

# Build new DDEX file
builder = DDEXBuilder()
new_xml = builder.build_from_dict(modified_data)

# Verify round-trip integrity
new_result = parser.parse_string(new_xml)
assert new_result.tracks[0].title == "New Title"

Requirements

• Python 3.8+
• pandas (optional, for DataFrame support)
• PyO3 0.24 compatible runtime

License

This project is licensed under the MIT License - see the LICENSE file for details.

Related Projects

• ddex-parser - Parse DDEX XML files to Python structures
• ddex-builder (npm) - JavaScript/TypeScript bindings
• DDEX Suite - Complete DDEX processing toolkit

Built with ❤️ for the music industry. Engineered for deterministic, industry-grade DDEX generation.