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.
Files changed (98) hide show
  1. ddex_builder-0.2.2/PKG-INFO +600 -0
  2. {ddex_builder-0.2.0/packages/ddex-builder/bindings/python → ddex_builder-0.2.2}/README.md +7 -12
  3. ddex_builder-0.2.2/packages/ddex-builder/bindings/python/README.md +564 -0
  4. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/pyproject.toml +2 -1
  5. ddex_builder-0.2.0/PKG-INFO +0 -34
  6. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/Cargo.lock +0 -0
  7. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/Cargo.toml +0 -0
  8. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/core/Cargo.toml +0 -0
  9. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/.clippy.toml +0 -0
  10. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/CHANGELOG.md +0 -0
  11. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/Cargo.toml +0 -0
  12. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/DETERMINISM.md +0 -0
  13. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/README.md +0 -0
  14. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/benches/building.rs +0 -0
  15. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/benches/canonicalization.rs +0 -0
  16. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/benches/determinism.rs +0 -0
  17. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/benches/performance.rs +0 -0
  18. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/benches/profiling.rs +0 -0
  19. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/bindings/README.md +0 -0
  20. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/bindings/api-consistency-report.md +0 -0
  21. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/bindings/build-bindings.sh +0 -0
  22. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/bindings/python/Cargo.toml +0 -0
  23. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/bindings/python/src/lib.rs +0 -0
  24. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/bindings/python/test_builder.py +0 -0
  25. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/bindings/python/test_import.py +0 -0
  26. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/bindings/test-all.js +0 -0
  27. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/bindings/test-all.py +0 -0
  28. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/clippy.toml +0 -0
  29. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/examples/README.md +0 -0
  30. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/examples/diff_comparison_example.rs +0 -0
  31. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/examples/spotify_album_example.rs +0 -0
  32. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/examples/streaming_catalog_example.rs +0 -0
  33. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/examples/youtube_video_example.rs +0 -0
  34. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/scripts/build-bindings.sh +0 -0
  35. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/scripts/profile.sh +0 -0
  36. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/api_security.rs +0 -0
  37. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/ast.rs +0 -0
  38. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/bin/ddex-builder.rs +0 -0
  39. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/builder.rs +0 -0
  40. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/caching.rs +0 -0
  41. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/canonical/mod.rs +0 -0
  42. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/determinism.rs +0 -0
  43. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/diff/diff_tests.rs +0 -0
  44. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/diff/formatter.rs +0 -0
  45. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/diff/mod.rs +0 -0
  46. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/diff/test_data.rs +0 -0
  47. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/diff/types.rs +0 -0
  48. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/error.rs +0 -0
  49. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/generator/mod.rs +0 -0
  50. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/generator/optimized_xml_writer.rs +0 -0
  51. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/generator/xml_writer.rs +0 -0
  52. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/guarantees.rs +0 -0
  53. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/id_generator.rs +0 -0
  54. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/lib.rs +0 -0
  55. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/linker/auto_linker.rs +0 -0
  56. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/linker/mod.rs +0 -0
  57. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/linker/reference_generator.rs +0 -0
  58. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/linker/relationship_manager.rs +0 -0
  59. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/linker/types.rs +0 -0
  60. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/memory_optimization.rs +0 -0
  61. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/messages/mod.rs +0 -0
  62. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/messages/test_data.rs +0 -0
  63. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/messages/update_release.rs +0 -0
  64. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/messages/update_tests.rs +0 -0
  65. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/optimized_strings.rs +0 -0
  66. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/parallel_processing.rs +0 -0
  67. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/preflight.rs +0 -0
  68. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/presets/mod.rs +0 -0
  69. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/presets/spotify.rs +0 -0
  70. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/presets/youtube.rs +0 -0
  71. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/schema/generators.rs +0 -0
  72. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/schema/mod.rs +0 -0
  73. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/schema/types.rs +0 -0
  74. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/schema/validation.rs +0 -0
  75. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/security.rs +0 -0
  76. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/streaming/buffer_manager.rs +0 -0
  77. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/streaming/mod.rs +0 -0
  78. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/streaming/reference_manager.rs +0 -0
  79. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/versions/converter.rs +0 -0
  80. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/versions/ern_382.rs +0 -0
  81. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/versions/ern_42.rs +0 -0
  82. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/versions/ern_43.rs +0 -0
  83. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/src/versions/mod.rs +0 -0
  84. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/basic_test.rs +0 -0
  85. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/cross_platform_determinism.rs +0 -0
  86. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/determinism_tests.rs +0 -0
  87. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/golden_files.rs +0 -0
  88. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/integration/diff_engine_tests.rs +0 -0
  89. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/integration/spotify_preset_tests.rs +0 -0
  90. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/integration/streaming_performance_tests.rs +0 -0
  91. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/integration/version_conversion_tests.rs +0 -0
  92. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/integration/youtube_preset_tests.rs +0 -0
  93. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/linker_test.rs +0 -0
  94. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/linker_xml_integration_test.rs +0 -0
  95. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/performance_regression.rs +0 -0
  96. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/presets_test.rs +0 -0
  97. {ddex_builder-0.2.0 → ddex_builder-0.2.2}/packages/ddex-builder/tests/snapshots/golden_files__audio_album_output.snap +0 -0
  98. {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
+ [![PyPI version](https://img.shields.io/pypi/v/ddex-builder.svg)](https://pypi.org/project/ddex-builder/)
40
+ [![Python versions](https://img.shields.io/pypi/pyversions/ddex-builder.svg)](https://pypi.org/project/ddex-builder/)
41
+ [![Downloads](https://img.shields.io/pypi/dm/ddex-builder.svg)](https://pypi.org/project/ddex-builder/)
42
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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 requirements automatically applied:
205
- # - Explicit content flagging
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
- #### Apple Music Preset
210
+ #### YouTube Preset
214
211
 
215
212
  ```python
216
- builder = DDEXBuilder(preset='apple_music')
213
+ builder = DDEXBuilder(preset='youtube_music')
217
214
 
218
- # Apple-specific optimizations:
219
- # - iTunes Store compliance
220
- # - Mastered for iTunes specifications
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
  ```