ddex-builder 0.2.0__tar.gz → 0.2.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ddex_builder-0.2.2/PKG-INFO +600 -0
- {ddex_builder-0.2.0/packages/ddex-builder/bindings/python → ddex_builder-0.2.2}/README.md +7 -12
- ddex_builder-0.2.2/packages/ddex-builder/bindings/python/README.md +564 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/pyproject.toml +2 -1
- ddex_builder-0.2.0/PKG-INFO +0 -34
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/Cargo.lock +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/Cargo.toml +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/core/Cargo.toml +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/.clippy.toml +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/CHANGELOG.md +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/Cargo.toml +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/DETERMINISM.md +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/README.md +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/benches/building.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/benches/canonicalization.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/benches/determinism.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/benches/performance.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/benches/profiling.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/bindings/README.md +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/bindings/api-consistency-report.md +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/bindings/build-bindings.sh +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/bindings/python/Cargo.toml +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/bindings/python/src/lib.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/bindings/python/test_builder.py +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/bindings/python/test_import.py +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/bindings/test-all.js +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/bindings/test-all.py +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/clippy.toml +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/examples/README.md +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/examples/diff_comparison_example.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/examples/spotify_album_example.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/examples/streaming_catalog_example.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/examples/youtube_video_example.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/scripts/build-bindings.sh +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/scripts/profile.sh +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/api_security.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/ast.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/bin/ddex-builder.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/builder.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/caching.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/canonical/mod.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/determinism.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/diff/diff_tests.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/diff/formatter.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/diff/mod.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/diff/test_data.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/diff/types.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/error.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/generator/mod.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/generator/optimized_xml_writer.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/generator/xml_writer.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/guarantees.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/id_generator.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/lib.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/linker/auto_linker.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/linker/mod.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/linker/reference_generator.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/linker/relationship_manager.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/linker/types.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/memory_optimization.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/messages/mod.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/messages/test_data.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/messages/update_release.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/messages/update_tests.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/optimized_strings.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/parallel_processing.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/preflight.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/presets/mod.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/presets/spotify.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/presets/youtube.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/schema/generators.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/schema/mod.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/schema/types.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/schema/validation.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/security.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/streaming/buffer_manager.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/streaming/mod.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/streaming/reference_manager.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/versions/converter.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/versions/ern_382.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/versions/ern_42.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/versions/ern_43.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/versions/mod.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/basic_test.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/cross_platform_determinism.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/determinism_tests.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/golden_files.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/integration/diff_engine_tests.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/integration/spotify_preset_tests.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/integration/streaming_performance_tests.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/integration/version_conversion_tests.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/integration/youtube_preset_tests.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/linker_test.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/linker_xml_integration_test.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/performance_regression.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/presets_test.rs +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/snapshots/golden_files__audio_album_output.snap +0 -0
- {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/xml_generation_test.rs +0 -0
|
@@ -0,0 +1,600 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ddex-builder
|
|
3
|
+
Version: 0.2.2
|
|
4
|
+
Classifier: Development Status :: 4 - Beta
|
|
5
|
+
Classifier: Intended Audience :: Developers
|
|
6
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
7
|
+
Classifier: Programming Language :: Python :: 3
|
|
8
|
+
Classifier: Programming Language :: Python :: 3.8
|
|
9
|
+
Classifier: Programming Language :: Python :: 3.9
|
|
10
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
11
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
13
|
+
Classifier: Programming Language :: Rust
|
|
14
|
+
Classifier: Topic :: Multimedia :: Sound/Audio
|
|
15
|
+
Classifier: Topic :: Software Development :: Libraries :: Python Modules
|
|
16
|
+
Classifier: Topic :: Text Processing :: Markup :: XML
|
|
17
|
+
Requires-Dist: pytest>=6.0 ; extra == 'dev'
|
|
18
|
+
Requires-Dist: pandas>=1.0 ; extra == 'dev'
|
|
19
|
+
Requires-Dist: numpy>=1.20 ; extra == 'dev'
|
|
20
|
+
Requires-Dist: pandas>=1.0 ; extra == 'pandas'
|
|
21
|
+
Requires-Dist: numpy>=1.20 ; extra == 'pandas'
|
|
22
|
+
Requires-Dist: pytest>=6.0 ; extra == 'test'
|
|
23
|
+
Requires-Dist: pytest-asyncio>=0.18 ; extra == 'test'
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Provides-Extra: pandas
|
|
26
|
+
Provides-Extra: test
|
|
27
|
+
Summary: High-performance DDEX XML builder with deterministic output and DB-C14N/1.0 canonicalization
|
|
28
|
+
Keywords: ddex,xml,builder,music,deterministic,canonicalization
|
|
29
|
+
Author: Kevin Marques Moo
|
|
30
|
+
License: MIT
|
|
31
|
+
Requires-Python: >=3.8
|
|
32
|
+
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
|
|
33
|
+
Project-URL: homepage, https://github.com/daddykev/ddex-suite
|
|
34
|
+
Project-URL: repository, https://github.com/daddykev/ddex-suite
|
|
35
|
+
Project-URL: documentation, https://github.com/daddykev/ddex-suite/tree/main/packages/ddex-builder
|
|
36
|
+
|
|
37
|
+
# DDEX Builder - Python Bindings
|
|
38
|
+
|
|
39
|
+
[](https://pypi.org/project/ddex-builder/)
|
|
40
|
+
[](https://pypi.org/project/ddex-builder/)
|
|
41
|
+
[](https://pypi.org/project/ddex-builder/)
|
|
42
|
+
[](https://opensource.org/licenses/MIT)
|
|
43
|
+
|
|
44
|
+
Generate deterministic, industry-compliant DDEX XML files from Python data structures with byte-perfect reproducibility. Build DDEX messages from dictionaries, DataFrames, or parsed objects with built-in validation and partner-specific presets.
|
|
45
|
+
|
|
46
|
+
## Installation
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
pip install ddex-builder
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Quick Start
|
|
53
|
+
|
|
54
|
+
```python
|
|
55
|
+
from ddex_builder import DDEXBuilder
|
|
56
|
+
import pandas as pd
|
|
57
|
+
|
|
58
|
+
# Create builder with validation
|
|
59
|
+
builder = DDEXBuilder(validate=True)
|
|
60
|
+
|
|
61
|
+
# Build from dictionary
|
|
62
|
+
release_data = {
|
|
63
|
+
'message_header': {
|
|
64
|
+
'sender_name': 'My Label',
|
|
65
|
+
'message_id': 'MSG123',
|
|
66
|
+
},
|
|
67
|
+
'releases': [{
|
|
68
|
+
'title': 'My Album',
|
|
69
|
+
'main_artist': 'Great Artist',
|
|
70
|
+
'tracks': [{
|
|
71
|
+
'title': 'Track 1',
|
|
72
|
+
'duration': 180,
|
|
73
|
+
'isrc': 'US1234567890'
|
|
74
|
+
}]
|
|
75
|
+
}]
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
xml_output = builder.build_from_dict(release_data, version='4.3')
|
|
79
|
+
print(xml_output[:100] + '...')
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
## Features
|
|
83
|
+
|
|
84
|
+
### 🎯 Deterministic Output
|
|
85
|
+
- **100% reproducible** XML generation with stable hash IDs
|
|
86
|
+
- DB-C14N/1.0 canonicalization for byte-perfect consistency
|
|
87
|
+
- IndexMap-based ordering ensures identical output across runs
|
|
88
|
+
- Content-addressable resource IDs for reliable references
|
|
89
|
+
|
|
90
|
+
### 🏭 Industry Presets
|
|
91
|
+
- **Spotify**: Optimized for streaming platform requirements
|
|
92
|
+
- **Apple Music**: iTunes Store compliance and best practices
|
|
93
|
+
- **Amazon Music**: Prime Music and Unlimited specifications
|
|
94
|
+
- **YouTube Music**: Content ID and monetization standards
|
|
95
|
+
- **Universal**: Generic preset suitable for most distributors
|
|
96
|
+
|
|
97
|
+
### 📊 DataFrame Integration
|
|
98
|
+
- Build directly from pandas DataFrames
|
|
99
|
+
- Automatic schema detection and validation
|
|
100
|
+
- Support for hierarchical data structures
|
|
101
|
+
- Export/import workflows with CSV and Parquet
|
|
102
|
+
|
|
103
|
+
### 🔒 Built-in Validation
|
|
104
|
+
- Comprehensive DDEX schema validation
|
|
105
|
+
- Business rule enforcement
|
|
106
|
+
- Reference integrity checking
|
|
107
|
+
- Territory and rights validation
|
|
108
|
+
|
|
109
|
+
### 🚀 High Performance
|
|
110
|
+
- Native Rust implementation with Python bindings
|
|
111
|
+
- Streaming generation for large catalogs
|
|
112
|
+
- Memory-efficient processing
|
|
113
|
+
- Parallel resource processing
|
|
114
|
+
|
|
115
|
+
## API Reference
|
|
116
|
+
|
|
117
|
+
### DDEXBuilder
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
from ddex_builder import DDEXBuilder
|
|
121
|
+
|
|
122
|
+
builder = DDEXBuilder(
|
|
123
|
+
validate=True, # Enable validation (recommended)
|
|
124
|
+
preset='universal', # Use industry preset
|
|
125
|
+
canonical=True, # Generate canonical XML
|
|
126
|
+
streaming=False, # Enable streaming mode for large data
|
|
127
|
+
max_memory=100_000_000 # Memory limit in bytes
|
|
128
|
+
)
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
### Building Methods
|
|
132
|
+
|
|
133
|
+
#### `build_from_dict(data: dict, version: str = '4.3') -> str`
|
|
134
|
+
|
|
135
|
+
Build DDEX XML from a Python dictionary.
|
|
136
|
+
|
|
137
|
+
```python
|
|
138
|
+
release = {
|
|
139
|
+
'message_header': {
|
|
140
|
+
'sender_name': 'Label Records',
|
|
141
|
+
'message_id': 'RELEASE_2024_001',
|
|
142
|
+
'sent_date': '2024-01-15T10:30:00Z'
|
|
143
|
+
},
|
|
144
|
+
'releases': [{
|
|
145
|
+
'release_id': 'REL001',
|
|
146
|
+
'title': 'Amazing Album',
|
|
147
|
+
'main_artist': 'Incredible Artist',
|
|
148
|
+
'label_name': 'Label Records',
|
|
149
|
+
'release_date': '2024-02-01',
|
|
150
|
+
'genres': ['Pop', 'Electronic'],
|
|
151
|
+
'tracks': [{
|
|
152
|
+
'track_id': 'TRK001',
|
|
153
|
+
'title': 'Hit Song',
|
|
154
|
+
'position': 1,
|
|
155
|
+
'duration': 195,
|
|
156
|
+
'isrc': 'US1234567890',
|
|
157
|
+
'artists': ['Incredible Artist']
|
|
158
|
+
}]
|
|
159
|
+
}]
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
xml = builder.build_from_dict(release, version='4.3')
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
#### `build_from_dataframe(df: pd.DataFrame, schema: str = 'auto') -> str`
|
|
166
|
+
|
|
167
|
+
Build DDEX XML from a pandas DataFrame.
|
|
168
|
+
|
|
169
|
+
```python
|
|
170
|
+
import pandas as pd
|
|
171
|
+
|
|
172
|
+
# Create DataFrame with release data
|
|
173
|
+
tracks_df = pd.DataFrame([
|
|
174
|
+
{
|
|
175
|
+
'release_title': 'My Album',
|
|
176
|
+
'release_artist': 'Artist Name',
|
|
177
|
+
'track_title': 'Song One',
|
|
178
|
+
'track_position': 1,
|
|
179
|
+
'duration': 180,
|
|
180
|
+
'isrc': 'US1234567890'
|
|
181
|
+
},
|
|
182
|
+
{
|
|
183
|
+
'release_title': 'My Album',
|
|
184
|
+
'release_artist': 'Artist Name',
|
|
185
|
+
'track_title': 'Song Two',
|
|
186
|
+
'track_position': 2,
|
|
187
|
+
'duration': 220,
|
|
188
|
+
'isrc': 'US1234567891'
|
|
189
|
+
}
|
|
190
|
+
])
|
|
191
|
+
|
|
192
|
+
xml = builder.build_from_dataframe(tracks_df, schema='release_tracks')
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
#### `build_from_parsed(result: DDEXResult) -> str`
|
|
196
|
+
|
|
197
|
+
Build DDEX XML from a parsed ddex-parser result.
|
|
198
|
+
|
|
199
|
+
```python
|
|
200
|
+
from ddex_parser import DDEXParser
|
|
201
|
+
from ddex_builder import DDEXBuilder
|
|
202
|
+
|
|
203
|
+
# Parse existing DDEX file
|
|
204
|
+
parser = DDEXParser()
|
|
205
|
+
result = parser.parse_file('input.xml')
|
|
206
|
+
|
|
207
|
+
# Modify the parsed data
|
|
208
|
+
result.flattened.releases[0].title = 'Updated Title'
|
|
209
|
+
|
|
210
|
+
# Build new XML with modifications
|
|
211
|
+
builder = DDEXBuilder()
|
|
212
|
+
new_xml = builder.build_from_parsed(result)
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
#### `build_async(data: dict) -> Awaitable[str]`
|
|
216
|
+
|
|
217
|
+
Asynchronous building for large datasets.
|
|
218
|
+
|
|
219
|
+
```python
|
|
220
|
+
import asyncio
|
|
221
|
+
|
|
222
|
+
async def build_large_catalog():
|
|
223
|
+
large_catalog = load_catalog_data() # Load your data
|
|
224
|
+
xml = await builder.build_async(large_catalog)
|
|
225
|
+
return xml
|
|
226
|
+
|
|
227
|
+
# Usage
|
|
228
|
+
xml_result = asyncio.run(build_large_catalog())
|
|
229
|
+
```
|
|
230
|
+
|
|
231
|
+
### Industry Presets
|
|
232
|
+
|
|
233
|
+
#### Spotify Preset
|
|
234
|
+
|
|
235
|
+
```python
|
|
236
|
+
from ddex_builder import DDEXBuilder, SpotifyPreset
|
|
237
|
+
|
|
238
|
+
builder = DDEXBuilder(preset='spotify')
|
|
239
|
+
|
|
240
|
+
# Spotify-specific optimizations:
|
|
241
|
+
# - Spotify Artist ID
|
|
242
|
+
|
|
243
|
+
xml = builder.build_from_dict(catalog_data, version='4.3')
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
#### YouTube Preset
|
|
247
|
+
|
|
248
|
+
```python
|
|
249
|
+
builder = DDEXBuilder(preset='youtube_music')
|
|
250
|
+
|
|
251
|
+
# YouTube-specific optimizations:
|
|
252
|
+
# - ContentID tracking
|
|
253
|
+
# - Territory restrictions
|
|
254
|
+
|
|
255
|
+
xml = builder.build_from_dict(release_data, version='4.3')
|
|
256
|
+
```
|
|
257
|
+
|
|
258
|
+
#### Custom Preset
|
|
259
|
+
|
|
260
|
+
```python
|
|
261
|
+
from ddex_builder import DDEXBuilder, BuilderPreset
|
|
262
|
+
|
|
263
|
+
custom_preset = BuilderPreset(
|
|
264
|
+
default_territories=['US', 'CA', 'GB'],
|
|
265
|
+
require_isrc=True,
|
|
266
|
+
validate_durations=True,
|
|
267
|
+
normalize_genres=['Pop', 'Rock', 'Electronic'],
|
|
268
|
+
max_track_duration=600, # 10 minutes
|
|
269
|
+
required_fields=['title', 'main_artist', 'duration']
|
|
270
|
+
)
|
|
271
|
+
|
|
272
|
+
builder = DDEXBuilder(preset=custom_preset)
|
|
273
|
+
```
|
|
274
|
+
|
|
275
|
+
## Advanced Usage
|
|
276
|
+
|
|
277
|
+
### Streaming Large Catalogs
|
|
278
|
+
|
|
279
|
+
```python
|
|
280
|
+
from ddex_builder import DDEXBuilder
|
|
281
|
+
import pandas as pd
|
|
282
|
+
|
|
283
|
+
def build_large_catalog(csv_file: str) -> str:
|
|
284
|
+
"""Build DDEX from large CSV catalog."""
|
|
285
|
+
builder = DDEXBuilder(streaming=True, max_memory=50_000_000)
|
|
286
|
+
|
|
287
|
+
# Read CSV in chunks to manage memory
|
|
288
|
+
chunk_size = 1000
|
|
289
|
+
xml_parts = []
|
|
290
|
+
|
|
291
|
+
for chunk in pd.read_csv(csv_file, chunksize=chunk_size):
|
|
292
|
+
# Process each chunk
|
|
293
|
+
chunk_xml = builder.build_from_dataframe(chunk, schema='catalog')
|
|
294
|
+
xml_parts.append(chunk_xml)
|
|
295
|
+
|
|
296
|
+
# Combine chunks into final DDEX message
|
|
297
|
+
return builder.merge_xml_chunks(xml_parts)
|
|
298
|
+
|
|
299
|
+
# Process 100,000+ track catalog
|
|
300
|
+
catalog_xml = build_large_catalog('massive_catalog.csv')
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
### Validation and Error Handling
|
|
304
|
+
|
|
305
|
+
```python
|
|
306
|
+
from ddex_builder import DDEXBuilder, ValidationError, BuilderError
|
|
307
|
+
|
|
308
|
+
builder = DDEXBuilder(validate=True)
|
|
309
|
+
|
|
310
|
+
try:
|
|
311
|
+
xml = builder.build_from_dict(release_data)
|
|
312
|
+
print("✅ DDEX built successfully")
|
|
313
|
+
except ValidationError as e:
|
|
314
|
+
print(f"❌ Validation failed: {e.details}")
|
|
315
|
+
for error in e.field_errors:
|
|
316
|
+
print(f" - {error.field}: {error.message}")
|
|
317
|
+
except BuilderError as e:
|
|
318
|
+
print(f"❌ Builder error: {e.message}")
|
|
319
|
+
if hasattr(e, 'suggestions'):
|
|
320
|
+
print("💡 Suggestions:")
|
|
321
|
+
for suggestion in e.suggestions:
|
|
322
|
+
print(f" - {suggestion}")
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
### Round-Trip with ddex-parser
|
|
326
|
+
|
|
327
|
+
Perfect integration for complete Parse → Modify → Build workflows:
|
|
328
|
+
|
|
329
|
+
```python
|
|
330
|
+
from ddex_parser import DDEXParser
|
|
331
|
+
from ddex_builder import DDEXBuilder
|
|
332
|
+
|
|
333
|
+
def round_trip_example():
|
|
334
|
+
# Parse original DDEX file
|
|
335
|
+
parser = DDEXParser()
|
|
336
|
+
original = parser.parse_file('original.xml')
|
|
337
|
+
|
|
338
|
+
# Modify specific fields
|
|
339
|
+
modified_data = original.to_dict()
|
|
340
|
+
modified_data['releases'][0]['title'] = 'Remastered Edition'
|
|
341
|
+
|
|
342
|
+
# Add new track
|
|
343
|
+
new_track = {
|
|
344
|
+
'title': 'Bonus Track',
|
|
345
|
+
'position': len(modified_data['releases'][0]['tracks']) + 1,
|
|
346
|
+
'duration': 240,
|
|
347
|
+
'isrc': 'US9876543210'
|
|
348
|
+
}
|
|
349
|
+
modified_data['releases'][0]['tracks'].append(new_track)
|
|
350
|
+
|
|
351
|
+
# Build new deterministic XML
|
|
352
|
+
builder = DDEXBuilder(canonical=True)
|
|
353
|
+
new_xml = builder.build_from_dict(modified_data)
|
|
354
|
+
|
|
355
|
+
# Verify round-trip integrity
|
|
356
|
+
reparsed = parser.parse_string(new_xml)
|
|
357
|
+
assert reparsed.releases[0].title == 'Remastered Edition'
|
|
358
|
+
assert len(reparsed.tracks) == len(original.tracks) + 1
|
|
359
|
+
|
|
360
|
+
return new_xml
|
|
361
|
+
|
|
362
|
+
# Guaranteed deterministic output
|
|
363
|
+
xml1 = round_trip_example()
|
|
364
|
+
xml2 = round_trip_example()
|
|
365
|
+
assert xml1 == xml2 # ✅ Byte-perfect reproducibility
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
### DataFrame Workflows
|
|
369
|
+
|
|
370
|
+
#### Complex Catalog Processing
|
|
371
|
+
|
|
372
|
+
```python
|
|
373
|
+
import pandas as pd
|
|
374
|
+
from ddex_builder import DDEXBuilder
|
|
375
|
+
|
|
376
|
+
def process_music_catalog(artists_df, albums_df, tracks_df):
|
|
377
|
+
"""Build DDEX from normalized database tables."""
|
|
378
|
+
builder = DDEXBuilder(preset='universal', validate=True)
|
|
379
|
+
|
|
380
|
+
# Merge dataframes to create hierarchical structure
|
|
381
|
+
catalog = tracks_df.merge(albums_df, on='album_id') \
|
|
382
|
+
.merge(artists_df, on='artist_id')
|
|
383
|
+
|
|
384
|
+
# Group by release for DDEX structure
|
|
385
|
+
releases = []
|
|
386
|
+
for album_id, album_tracks in catalog.groupby('album_id'):
|
|
387
|
+
release = {
|
|
388
|
+
'release_id': album_id,
|
|
389
|
+
'title': album_tracks.iloc[0]['album_title'],
|
|
390
|
+
'main_artist': album_tracks.iloc[0]['artist_name'],
|
|
391
|
+
'release_date': album_tracks.iloc[0]['release_date'],
|
|
392
|
+
'tracks': album_tracks.to_dict('records')
|
|
393
|
+
}
|
|
394
|
+
releases.append(release)
|
|
395
|
+
|
|
396
|
+
# Build DDEX XML
|
|
397
|
+
ddex_data = {
|
|
398
|
+
'message_header': {
|
|
399
|
+
'sender_name': 'My Label',
|
|
400
|
+
'message_id': f'CATALOG_{pd.Timestamp.now().strftime("%Y%m%d_%H%M%S")}'
|
|
401
|
+
},
|
|
402
|
+
'releases': releases
|
|
403
|
+
}
|
|
404
|
+
|
|
405
|
+
return builder.build_from_dict(ddex_data, version='4.3')
|
|
406
|
+
|
|
407
|
+
# Load data from your database/CSV files
|
|
408
|
+
artists = pd.read_csv('artists.csv')
|
|
409
|
+
albums = pd.read_csv('albums.csv')
|
|
410
|
+
tracks = pd.read_csv('tracks.csv')
|
|
411
|
+
|
|
412
|
+
# Generate DDEX catalog
|
|
413
|
+
catalog_xml = process_music_catalog(artists, albums, tracks)
|
|
414
|
+
```
|
|
415
|
+
|
|
416
|
+
#### Analytics Integration
|
|
417
|
+
|
|
418
|
+
```python
|
|
419
|
+
import pandas as pd
|
|
420
|
+
from ddex_builder import DDEXBuilder
|
|
421
|
+
|
|
422
|
+
def build_from_analytics(streaming_data: pd.DataFrame) -> str:
|
|
423
|
+
"""Build DDEX from streaming analytics data."""
|
|
424
|
+
builder = DDEXBuilder(preset='spotify')
|
|
425
|
+
|
|
426
|
+
# Aggregate streaming data to releases
|
|
427
|
+
release_stats = streaming_data.groupby(['release_id', 'release_title']).agg({
|
|
428
|
+
'streams': 'sum',
|
|
429
|
+
'revenue': 'sum',
|
|
430
|
+
'territories': lambda x: list(x.unique())
|
|
431
|
+
}).reset_index()
|
|
432
|
+
|
|
433
|
+
# Convert to DDEX format
|
|
434
|
+
releases = []
|
|
435
|
+
for _, row in release_stats.iterrows():
|
|
436
|
+
release = {
|
|
437
|
+
'release_id': row['release_id'],
|
|
438
|
+
'title': row['release_title'],
|
|
439
|
+
'territories': row['territories'],
|
|
440
|
+
'usage_rights': {
|
|
441
|
+
'stream_count': int(row['streams']),
|
|
442
|
+
'revenue': float(row['revenue'])
|
|
443
|
+
}
|
|
444
|
+
}
|
|
445
|
+
releases.append(release)
|
|
446
|
+
|
|
447
|
+
ddex_data = {
|
|
448
|
+
'message_header': {
|
|
449
|
+
'sender_name': 'Analytics Export',
|
|
450
|
+
'message_id': f'ANALYTICS_{pd.Timestamp.now().isoformat()}'
|
|
451
|
+
},
|
|
452
|
+
'releases': releases
|
|
453
|
+
}
|
|
454
|
+
|
|
455
|
+
return builder.build_from_dict(ddex_data, version='4.3')
|
|
456
|
+
```
|
|
457
|
+
|
|
458
|
+
## Performance Benchmarks
|
|
459
|
+
|
|
460
|
+
Building performance on different dataset sizes:
|
|
461
|
+
|
|
462
|
+
| Dataset Size | Build Time | Memory Usage | Output Size |
|
|
463
|
+
|--------------|------------|-------------|------------|
|
|
464
|
+
| Single release (10 tracks) | 2ms | 5MB | 25KB |
|
|
465
|
+
| Album catalog (100 releases) | 15ms | 25MB | 2.5MB |
|
|
466
|
+
| Label catalog (1000 releases) | 120ms | 80MB | 25MB |
|
|
467
|
+
| Large catalog (10000 releases) | 1.2s | 200MB | 250MB |
|
|
468
|
+
|
|
469
|
+
Memory usage scales linearly, with streaming mode keeping usage constant for any dataset size.
|
|
470
|
+
|
|
471
|
+
## DataFrame Schema Reference
|
|
472
|
+
|
|
473
|
+
### Standard Schemas
|
|
474
|
+
|
|
475
|
+
#### `release_tracks` Schema
|
|
476
|
+
|
|
477
|
+
```python
|
|
478
|
+
# Required columns for release_tracks schema
|
|
479
|
+
df_columns = [
|
|
480
|
+
'release_title', # str: Album/EP title
|
|
481
|
+
'release_artist', # str: Main artist name
|
|
482
|
+
'track_title', # str: Song title
|
|
483
|
+
'track_position', # int: Track number
|
|
484
|
+
'duration', # int: Duration in seconds
|
|
485
|
+
'isrc', # str: International Standard Recording Code
|
|
486
|
+
]
|
|
487
|
+
|
|
488
|
+
# Optional columns
|
|
489
|
+
optional_columns = [
|
|
490
|
+
'release_date', # str: ISO date (YYYY-MM-DD)
|
|
491
|
+
'label_name', # str: Record label
|
|
492
|
+
'genres', # list[str]: Genre classifications
|
|
493
|
+
'territories', # list[str]: Territory codes
|
|
494
|
+
'explicit', # bool: Explicit content flag
|
|
495
|
+
]
|
|
496
|
+
```
|
|
497
|
+
|
|
498
|
+
#### `catalog` Schema
|
|
499
|
+
|
|
500
|
+
```python
|
|
501
|
+
# Multi-release catalog schema
|
|
502
|
+
catalog_columns = [
|
|
503
|
+
'release_id', # str: Unique release identifier
|
|
504
|
+
'release_title', # str: Release title
|
|
505
|
+
'release_artist', # str: Main artist
|
|
506
|
+
'release_date', # str: Release date
|
|
507
|
+
'track_id', # str: Unique track identifier
|
|
508
|
+
'track_title', # str: Track title
|
|
509
|
+
'track_position', # int: Position in release
|
|
510
|
+
'duration', # int: Duration in seconds
|
|
511
|
+
'isrc', # str: ISRC code
|
|
512
|
+
'artists', # list[str]: All participating artists
|
|
513
|
+
]
|
|
514
|
+
```
|
|
515
|
+
|
|
516
|
+
## Migration from v0.1.0
|
|
517
|
+
|
|
518
|
+
v0.2.0 introduces significant improvements:
|
|
519
|
+
|
|
520
|
+
```python
|
|
521
|
+
# v0.1.0 (deprecated)
|
|
522
|
+
from ddex_builder import build_ddex
|
|
523
|
+
xml = build_ddex(data, version='4.3')
|
|
524
|
+
|
|
525
|
+
# v0.2.0+ (current)
|
|
526
|
+
from ddex_builder import DDEXBuilder
|
|
527
|
+
builder = DDEXBuilder()
|
|
528
|
+
xml = builder.build_from_dict(data, version='4.3')
|
|
529
|
+
```
|
|
530
|
+
|
|
531
|
+
### New Features in v0.2.0
|
|
532
|
+
|
|
533
|
+
- **Industry presets** for major streaming platforms
|
|
534
|
+
- **DataFrame integration** with pandas
|
|
535
|
+
- **Async support** for large datasets
|
|
536
|
+
- **Enhanced validation** with detailed error messages
|
|
537
|
+
- **Deterministic output** with DB-C14N/1.0
|
|
538
|
+
- **Streaming mode** for memory efficiency
|
|
539
|
+
- **Round-trip compatibility** with ddex-parser
|
|
540
|
+
|
|
541
|
+
## Troubleshooting
|
|
542
|
+
|
|
543
|
+
### Common Issues
|
|
544
|
+
|
|
545
|
+
**ValidationError: Required field missing**
|
|
546
|
+
```python
|
|
547
|
+
# Ensure all required fields are present
|
|
548
|
+
required_fields = builder.get_required_fields(version='4.3')
|
|
549
|
+
print(f"Required fields: {required_fields}")
|
|
550
|
+
|
|
551
|
+
# Check your data
|
|
552
|
+
missing_fields = builder.validate_dict(your_data)
|
|
553
|
+
print(f"Missing: {missing_fields}")
|
|
554
|
+
```
|
|
555
|
+
|
|
556
|
+
**Memory issues with large catalogs**
|
|
557
|
+
```python
|
|
558
|
+
# Enable streaming mode
|
|
559
|
+
builder = DDEXBuilder(streaming=True, max_memory=50_000_000)
|
|
560
|
+
xml = builder.build_from_dataframe(large_df, schema='catalog')
|
|
561
|
+
```
|
|
562
|
+
|
|
563
|
+
**Inconsistent XML output**
|
|
564
|
+
```python
|
|
565
|
+
# Enable canonical mode for deterministic output
|
|
566
|
+
builder = DDEXBuilder(canonical=True)
|
|
567
|
+
xml = builder.build_from_dict(data, version='4.3')
|
|
568
|
+
```
|
|
569
|
+
|
|
570
|
+
**Import errors**
|
|
571
|
+
```bash
|
|
572
|
+
pip install --upgrade ddex-builder
|
|
573
|
+
# If still failing:
|
|
574
|
+
pip install --force-reinstall ddex-builder
|
|
575
|
+
```
|
|
576
|
+
|
|
577
|
+
### Getting Help
|
|
578
|
+
|
|
579
|
+
- 📖 [Full Documentation](https://github.com/ddex-suite/ddex-suite/tree/main/packages/ddex-builder)
|
|
580
|
+
- 🐛 [Report Issues](https://github.com/ddex-suite/ddex-suite/issues)
|
|
581
|
+
- 💬 [GitHub Discussions](https://github.com/ddex-suite/ddex-suite/discussions)
|
|
582
|
+
- 📧 Email: support@ddex-suite.com
|
|
583
|
+
|
|
584
|
+
## Contributing
|
|
585
|
+
|
|
586
|
+
We welcome contributions! See our [Contributing Guide](https://github.com/ddex-suite/ddex-suite/blob/main/CONTRIBUTING.md) for details.
|
|
587
|
+
|
|
588
|
+
## License
|
|
589
|
+
|
|
590
|
+
This project is licensed under the MIT License - see the [LICENSE](https://github.com/ddex-suite/ddex-suite/blob/main/LICENSE) file for details.
|
|
591
|
+
|
|
592
|
+
## Related Projects
|
|
593
|
+
|
|
594
|
+
- **[ddex-parser](https://pypi.org/project/ddex-parser/)** - Parse DDEX XML files to Python structures
|
|
595
|
+
- **[ddex-builder (npm)](https://www.npmjs.com/package/ddex-builder)** - JavaScript/TypeScript bindings
|
|
596
|
+
- **[DDEX Suite](https://github.com/ddex-suite/ddex-suite)** - Complete DDEX processing toolkit
|
|
597
|
+
|
|
598
|
+
---
|
|
599
|
+
|
|
600
|
+
Built with ❤️ for the music industry. Engineered for deterministic, industry-grade DDEX generation.
|
|
@@ -201,25 +201,20 @@ from ddex_builder import DDEXBuilder, SpotifyPreset
|
|
|
201
201
|
|
|
202
202
|
builder = DDEXBuilder(preset='spotify')
|
|
203
203
|
|
|
204
|
-
# Spotify-specific
|
|
205
|
-
# -
|
|
206
|
-
# - Territory restrictions for streaming
|
|
207
|
-
# - Preferred audio quality specifications
|
|
208
|
-
# - Genre normalization to Spotify's taxonomy
|
|
204
|
+
# Spotify-specific optimizations:
|
|
205
|
+
# - Spotify Artist ID
|
|
209
206
|
|
|
210
207
|
xml = builder.build_from_dict(catalog_data, version='4.3')
|
|
211
208
|
```
|
|
212
209
|
|
|
213
|
-
####
|
|
210
|
+
#### YouTube Preset
|
|
214
211
|
|
|
215
212
|
```python
|
|
216
|
-
builder = DDEXBuilder(preset='
|
|
213
|
+
builder = DDEXBuilder(preset='youtube_music')
|
|
217
214
|
|
|
218
|
-
#
|
|
219
|
-
# -
|
|
220
|
-
# -
|
|
221
|
-
# - Region-specific pricing tiers
|
|
222
|
-
# - Album artwork requirements
|
|
215
|
+
# YouTube-specific optimizations:
|
|
216
|
+
# - ContentID tracking
|
|
217
|
+
# - Territory restrictions
|
|
223
218
|
|
|
224
219
|
xml = builder.build_from_dict(release_data, version='4.3')
|
|
225
220
|
```
|