ddex-builder 0.2.0__tar.gz → 0.2.1__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.1/PKG-INFO +605 -0
  2. ddex_builder-0.2.1/packages/ddex-builder/bindings/python/README.md +569 -0
  3. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/pyproject.toml +2 -1
  4. ddex_builder-0.2.0/PKG-INFO +0 -34
  5. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/Cargo.lock +0 -0
  6. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/Cargo.toml +0 -0
  7. {ddex_builder-0.2.0/packages/ddex-builder/bindings/python → ddex_builder-0.2.1}/README.md +0 -0
  8. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/core/Cargo.toml +0 -0
  9. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/.clippy.toml +0 -0
  10. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/CHANGELOG.md +0 -0
  11. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/Cargo.toml +0 -0
  12. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/DETERMINISM.md +0 -0
  13. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/README.md +0 -0
  14. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/benches/building.rs +0 -0
  15. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/benches/canonicalization.rs +0 -0
  16. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/benches/determinism.rs +0 -0
  17. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/benches/performance.rs +0 -0
  18. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/benches/profiling.rs +0 -0
  19. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/bindings/README.md +0 -0
  20. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/bindings/api-consistency-report.md +0 -0
  21. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/bindings/build-bindings.sh +0 -0
  22. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/bindings/python/Cargo.toml +0 -0
  23. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/bindings/python/src/lib.rs +0 -0
  24. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/bindings/python/test_builder.py +0 -0
  25. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/bindings/python/test_import.py +0 -0
  26. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/bindings/test-all.js +0 -0
  27. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/bindings/test-all.py +0 -0
  28. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/clippy.toml +0 -0
  29. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/examples/README.md +0 -0
  30. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/examples/diff_comparison_example.rs +0 -0
  31. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/examples/spotify_album_example.rs +0 -0
  32. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/examples/streaming_catalog_example.rs +0 -0
  33. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/examples/youtube_video_example.rs +0 -0
  34. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/scripts/build-bindings.sh +0 -0
  35. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/scripts/profile.sh +0 -0
  36. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/api_security.rs +0 -0
  37. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/ast.rs +0 -0
  38. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/bin/ddex-builder.rs +0 -0
  39. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/builder.rs +0 -0
  40. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/caching.rs +0 -0
  41. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/canonical/mod.rs +0 -0
  42. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/determinism.rs +0 -0
  43. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/diff/diff_tests.rs +0 -0
  44. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/diff/formatter.rs +0 -0
  45. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/diff/mod.rs +0 -0
  46. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/diff/test_data.rs +0 -0
  47. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/diff/types.rs +0 -0
  48. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/error.rs +0 -0
  49. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/generator/mod.rs +0 -0
  50. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/generator/optimized_xml_writer.rs +0 -0
  51. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/generator/xml_writer.rs +0 -0
  52. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/guarantees.rs +0 -0
  53. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/id_generator.rs +0 -0
  54. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/lib.rs +0 -0
  55. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/linker/auto_linker.rs +0 -0
  56. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/linker/mod.rs +0 -0
  57. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/linker/reference_generator.rs +0 -0
  58. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/linker/relationship_manager.rs +0 -0
  59. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/linker/types.rs +0 -0
  60. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/memory_optimization.rs +0 -0
  61. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/messages/mod.rs +0 -0
  62. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/messages/test_data.rs +0 -0
  63. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/messages/update_release.rs +0 -0
  64. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/messages/update_tests.rs +0 -0
  65. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/optimized_strings.rs +0 -0
  66. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/parallel_processing.rs +0 -0
  67. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/preflight.rs +0 -0
  68. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/presets/mod.rs +0 -0
  69. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/presets/spotify.rs +0 -0
  70. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/presets/youtube.rs +0 -0
  71. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/schema/generators.rs +0 -0
  72. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/schema/mod.rs +0 -0
  73. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/schema/types.rs +0 -0
  74. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/schema/validation.rs +0 -0
  75. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/security.rs +0 -0
  76. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/streaming/buffer_manager.rs +0 -0
  77. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/streaming/mod.rs +0 -0
  78. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/streaming/reference_manager.rs +0 -0
  79. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/versions/converter.rs +0 -0
  80. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/versions/ern_382.rs +0 -0
  81. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/versions/ern_42.rs +0 -0
  82. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/versions/ern_43.rs +0 -0
  83. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/src/versions/mod.rs +0 -0
  84. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/tests/basic_test.rs +0 -0
  85. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/tests/cross_platform_determinism.rs +0 -0
  86. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/tests/determinism_tests.rs +0 -0
  87. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/tests/golden_files.rs +0 -0
  88. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/tests/integration/diff_engine_tests.rs +0 -0
  89. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/tests/integration/spotify_preset_tests.rs +0 -0
  90. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/tests/integration/streaming_performance_tests.rs +0 -0
  91. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/tests/integration/version_conversion_tests.rs +0 -0
  92. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/tests/integration/youtube_preset_tests.rs +0 -0
  93. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/tests/linker_test.rs +0 -0
  94. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/tests/linker_xml_integration_test.rs +0 -0
  95. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/tests/performance_regression.rs +0 -0
  96. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/tests/presets_test.rs +0 -0
  97. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/tests/snapshots/golden_files__audio_album_output.snap +0 -0
  98. {ddex_builder-0.2.0 → ddex_builder-0.2.1}/packages/ddex-builder/tests/xml_generation_test.rs +0 -0
@@ -0,0 +1,605 @@
1
+ Metadata-Version: 2.4
2
+ Name: ddex-builder
3
+ Version: 0.2.1
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 requirements automatically applied:
241
+ # - Explicit content flagging
242
+ # - Territory restrictions for streaming
243
+ # - Preferred audio quality specifications
244
+ # - Genre normalization to Spotify's taxonomy
245
+
246
+ xml = builder.build_from_dict(catalog_data, version='4.3')
247
+ ```
248
+
249
+ #### Apple Music Preset
250
+
251
+ ```python
252
+ builder = DDEXBuilder(preset='apple_music')
253
+
254
+ # Apple-specific optimizations:
255
+ # - iTunes Store compliance
256
+ # - Mastered for iTunes specifications
257
+ # - Region-specific pricing tiers
258
+ # - Album artwork requirements
259
+
260
+ xml = builder.build_from_dict(release_data, version='4.3')
261
+ ```
262
+
263
+ #### Custom Preset
264
+
265
+ ```python
266
+ from ddex_builder import DDEXBuilder, BuilderPreset
267
+
268
+ custom_preset = BuilderPreset(
269
+ default_territories=['US', 'CA', 'GB'],
270
+ require_isrc=True,
271
+ validate_durations=True,
272
+ normalize_genres=['Pop', 'Rock', 'Electronic'],
273
+ max_track_duration=600, # 10 minutes
274
+ required_fields=['title', 'main_artist', 'duration']
275
+ )
276
+
277
+ builder = DDEXBuilder(preset=custom_preset)
278
+ ```
279
+
280
+ ## Advanced Usage
281
+
282
+ ### Streaming Large Catalogs
283
+
284
+ ```python
285
+ from ddex_builder import DDEXBuilder
286
+ import pandas as pd
287
+
288
+ def build_large_catalog(csv_file: str) -> str:
289
+ """Build DDEX from large CSV catalog."""
290
+ builder = DDEXBuilder(streaming=True, max_memory=50_000_000)
291
+
292
+ # Read CSV in chunks to manage memory
293
+ chunk_size = 1000
294
+ xml_parts = []
295
+
296
+ for chunk in pd.read_csv(csv_file, chunksize=chunk_size):
297
+ # Process each chunk
298
+ chunk_xml = builder.build_from_dataframe(chunk, schema='catalog')
299
+ xml_parts.append(chunk_xml)
300
+
301
+ # Combine chunks into final DDEX message
302
+ return builder.merge_xml_chunks(xml_parts)
303
+
304
+ # Process 100,000+ track catalog
305
+ catalog_xml = build_large_catalog('massive_catalog.csv')
306
+ ```
307
+
308
+ ### Validation and Error Handling
309
+
310
+ ```python
311
+ from ddex_builder import DDEXBuilder, ValidationError, BuilderError
312
+
313
+ builder = DDEXBuilder(validate=True)
314
+
315
+ try:
316
+ xml = builder.build_from_dict(release_data)
317
+ print("✅ DDEX built successfully")
318
+ except ValidationError as e:
319
+ print(f"❌ Validation failed: {e.details}")
320
+ for error in e.field_errors:
321
+ print(f" - {error.field}: {error.message}")
322
+ except BuilderError as e:
323
+ print(f"❌ Builder error: {e.message}")
324
+ if hasattr(e, 'suggestions'):
325
+ print("💡 Suggestions:")
326
+ for suggestion in e.suggestions:
327
+ print(f" - {suggestion}")
328
+ ```
329
+
330
+ ### Round-Trip with ddex-parser
331
+
332
+ Perfect integration for complete Parse → Modify → Build workflows:
333
+
334
+ ```python
335
+ from ddex_parser import DDEXParser
336
+ from ddex_builder import DDEXBuilder
337
+
338
+ def round_trip_example():
339
+ # Parse original DDEX file
340
+ parser = DDEXParser()
341
+ original = parser.parse_file('original.xml')
342
+
343
+ # Modify specific fields
344
+ modified_data = original.to_dict()
345
+ modified_data['releases'][0]['title'] = 'Remastered Edition'
346
+
347
+ # Add new track
348
+ new_track = {
349
+ 'title': 'Bonus Track',
350
+ 'position': len(modified_data['releases'][0]['tracks']) + 1,
351
+ 'duration': 240,
352
+ 'isrc': 'US9876543210'
353
+ }
354
+ modified_data['releases'][0]['tracks'].append(new_track)
355
+
356
+ # Build new deterministic XML
357
+ builder = DDEXBuilder(canonical=True)
358
+ new_xml = builder.build_from_dict(modified_data)
359
+
360
+ # Verify round-trip integrity
361
+ reparsed = parser.parse_string(new_xml)
362
+ assert reparsed.releases[0].title == 'Remastered Edition'
363
+ assert len(reparsed.tracks) == len(original.tracks) + 1
364
+
365
+ return new_xml
366
+
367
+ # Guaranteed deterministic output
368
+ xml1 = round_trip_example()
369
+ xml2 = round_trip_example()
370
+ assert xml1 == xml2 # ✅ Byte-perfect reproducibility
371
+ ```
372
+
373
+ ### DataFrame Workflows
374
+
375
+ #### Complex Catalog Processing
376
+
377
+ ```python
378
+ import pandas as pd
379
+ from ddex_builder import DDEXBuilder
380
+
381
+ def process_music_catalog(artists_df, albums_df, tracks_df):
382
+ """Build DDEX from normalized database tables."""
383
+ builder = DDEXBuilder(preset='universal', validate=True)
384
+
385
+ # Merge dataframes to create hierarchical structure
386
+ catalog = tracks_df.merge(albums_df, on='album_id') \
387
+ .merge(artists_df, on='artist_id')
388
+
389
+ # Group by release for DDEX structure
390
+ releases = []
391
+ for album_id, album_tracks in catalog.groupby('album_id'):
392
+ release = {
393
+ 'release_id': album_id,
394
+ 'title': album_tracks.iloc[0]['album_title'],
395
+ 'main_artist': album_tracks.iloc[0]['artist_name'],
396
+ 'release_date': album_tracks.iloc[0]['release_date'],
397
+ 'tracks': album_tracks.to_dict('records')
398
+ }
399
+ releases.append(release)
400
+
401
+ # Build DDEX XML
402
+ ddex_data = {
403
+ 'message_header': {
404
+ 'sender_name': 'My Label',
405
+ 'message_id': f'CATALOG_{pd.Timestamp.now().strftime("%Y%m%d_%H%M%S")}'
406
+ },
407
+ 'releases': releases
408
+ }
409
+
410
+ return builder.build_from_dict(ddex_data, version='4.3')
411
+
412
+ # Load data from your database/CSV files
413
+ artists = pd.read_csv('artists.csv')
414
+ albums = pd.read_csv('albums.csv')
415
+ tracks = pd.read_csv('tracks.csv')
416
+
417
+ # Generate DDEX catalog
418
+ catalog_xml = process_music_catalog(artists, albums, tracks)
419
+ ```
420
+
421
+ #### Analytics Integration
422
+
423
+ ```python
424
+ import pandas as pd
425
+ from ddex_builder import DDEXBuilder
426
+
427
+ def build_from_analytics(streaming_data: pd.DataFrame) -> str:
428
+ """Build DDEX from streaming analytics data."""
429
+ builder = DDEXBuilder(preset='spotify')
430
+
431
+ # Aggregate streaming data to releases
432
+ release_stats = streaming_data.groupby(['release_id', 'release_title']).agg({
433
+ 'streams': 'sum',
434
+ 'revenue': 'sum',
435
+ 'territories': lambda x: list(x.unique())
436
+ }).reset_index()
437
+
438
+ # Convert to DDEX format
439
+ releases = []
440
+ for _, row in release_stats.iterrows():
441
+ release = {
442
+ 'release_id': row['release_id'],
443
+ 'title': row['release_title'],
444
+ 'territories': row['territories'],
445
+ 'usage_rights': {
446
+ 'stream_count': int(row['streams']),
447
+ 'revenue': float(row['revenue'])
448
+ }
449
+ }
450
+ releases.append(release)
451
+
452
+ ddex_data = {
453
+ 'message_header': {
454
+ 'sender_name': 'Analytics Export',
455
+ 'message_id': f'ANALYTICS_{pd.Timestamp.now().isoformat()}'
456
+ },
457
+ 'releases': releases
458
+ }
459
+
460
+ return builder.build_from_dict(ddex_data, version='4.3')
461
+ ```
462
+
463
+ ## Performance Benchmarks
464
+
465
+ Building performance on different dataset sizes:
466
+
467
+ | Dataset Size | Build Time | Memory Usage | Output Size |
468
+ |--------------|------------|-------------|------------|
469
+ | Single release (10 tracks) | 2ms | 5MB | 25KB |
470
+ | Album catalog (100 releases) | 15ms | 25MB | 2.5MB |
471
+ | Label catalog (1000 releases) | 120ms | 80MB | 25MB |
472
+ | Large catalog (10000 releases) | 1.2s | 200MB | 250MB |
473
+
474
+ Memory usage scales linearly, with streaming mode keeping usage constant for any dataset size.
475
+
476
+ ## DataFrame Schema Reference
477
+
478
+ ### Standard Schemas
479
+
480
+ #### `release_tracks` Schema
481
+
482
+ ```python
483
+ # Required columns for release_tracks schema
484
+ df_columns = [
485
+ 'release_title', # str: Album/EP title
486
+ 'release_artist', # str: Main artist name
487
+ 'track_title', # str: Song title
488
+ 'track_position', # int: Track number
489
+ 'duration', # int: Duration in seconds
490
+ 'isrc', # str: International Standard Recording Code
491
+ ]
492
+
493
+ # Optional columns
494
+ optional_columns = [
495
+ 'release_date', # str: ISO date (YYYY-MM-DD)
496
+ 'label_name', # str: Record label
497
+ 'genres', # list[str]: Genre classifications
498
+ 'territories', # list[str]: Territory codes
499
+ 'explicit', # bool: Explicit content flag
500
+ ]
501
+ ```
502
+
503
+ #### `catalog` Schema
504
+
505
+ ```python
506
+ # Multi-release catalog schema
507
+ catalog_columns = [
508
+ 'release_id', # str: Unique release identifier
509
+ 'release_title', # str: Release title
510
+ 'release_artist', # str: Main artist
511
+ 'release_date', # str: Release date
512
+ 'track_id', # str: Unique track identifier
513
+ 'track_title', # str: Track title
514
+ 'track_position', # int: Position in release
515
+ 'duration', # int: Duration in seconds
516
+ 'isrc', # str: ISRC code
517
+ 'artists', # list[str]: All participating artists
518
+ ]
519
+ ```
520
+
521
+ ## Migration from v0.1.0
522
+
523
+ v0.2.0 introduces significant improvements:
524
+
525
+ ```python
526
+ # v0.1.0 (deprecated)
527
+ from ddex_builder import build_ddex
528
+ xml = build_ddex(data, version='4.3')
529
+
530
+ # v0.2.0+ (current)
531
+ from ddex_builder import DDEXBuilder
532
+ builder = DDEXBuilder()
533
+ xml = builder.build_from_dict(data, version='4.3')
534
+ ```
535
+
536
+ ### New Features in v0.2.0
537
+
538
+ - **Industry presets** for major streaming platforms
539
+ - **DataFrame integration** with pandas
540
+ - **Async support** for large datasets
541
+ - **Enhanced validation** with detailed error messages
542
+ - **Deterministic output** with DB-C14N/1.0
543
+ - **Streaming mode** for memory efficiency
544
+ - **Round-trip compatibility** with ddex-parser
545
+
546
+ ## Troubleshooting
547
+
548
+ ### Common Issues
549
+
550
+ **ValidationError: Required field missing**
551
+ ```python
552
+ # Ensure all required fields are present
553
+ required_fields = builder.get_required_fields(version='4.3')
554
+ print(f"Required fields: {required_fields}")
555
+
556
+ # Check your data
557
+ missing_fields = builder.validate_dict(your_data)
558
+ print(f"Missing: {missing_fields}")
559
+ ```
560
+
561
+ **Memory issues with large catalogs**
562
+ ```python
563
+ # Enable streaming mode
564
+ builder = DDEXBuilder(streaming=True, max_memory=50_000_000)
565
+ xml = builder.build_from_dataframe(large_df, schema='catalog')
566
+ ```
567
+
568
+ **Inconsistent XML output**
569
+ ```python
570
+ # Enable canonical mode for deterministic output
571
+ builder = DDEXBuilder(canonical=True)
572
+ xml = builder.build_from_dict(data, version='4.3')
573
+ ```
574
+
575
+ **Import errors**
576
+ ```bash
577
+ pip install --upgrade ddex-builder
578
+ # If still failing:
579
+ pip install --force-reinstall ddex-builder
580
+ ```
581
+
582
+ ### Getting Help
583
+
584
+ - 📖 [Full Documentation](https://github.com/ddex-suite/ddex-suite/tree/main/packages/ddex-builder)
585
+ - 🐛 [Report Issues](https://github.com/ddex-suite/ddex-suite/issues)
586
+ - 💬 [GitHub Discussions](https://github.com/ddex-suite/ddex-suite/discussions)
587
+ - 📧 Email: support@ddex-suite.com
588
+
589
+ ## Contributing
590
+
591
+ We welcome contributions! See our [Contributing Guide](https://github.com/ddex-suite/ddex-suite/blob/main/CONTRIBUTING.md) for details.
592
+
593
+ ## License
594
+
595
+ This project is licensed under the MIT License - see the [LICENSE](https://github.com/ddex-suite/ddex-suite/blob/main/LICENSE) file for details.
596
+
597
+ ## Related Projects
598
+
599
+ - **[ddex-parser](https://pypi.org/project/ddex-parser/)** - Parse DDEX XML files to Python structures
600
+ - **[ddex-builder (npm)](https://www.npmjs.com/package/ddex-builder)** - JavaScript/TypeScript bindings
601
+ - **[DDEX Suite](https://github.com/ddex-suite/ddex-suite)** - Complete DDEX processing toolkit
602
+
603
+ ---
604
+
605
+ Built with ❤️ for the music industry. Engineered for deterministic, industry-grade DDEX generation.