ddex-workbench 1.0.0__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.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024 DDEX Workbench Contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,44 @@
1
+ # packages/python-sdk/MANIFEST.in
2
+ # Include/exclude rules for package distribution
3
+
4
+ # Include documentation
5
+ include README.md
6
+ include LICENSE
7
+ include CHANGELOG.md
8
+
9
+ # Include requirements files
10
+ include requirements.txt
11
+ include requirements-dev.txt
12
+
13
+ # Include type information
14
+ include ddex_workbench/py.typed
15
+
16
+ # Include test configuration
17
+ include tox.ini
18
+ include .coveragerc
19
+ include pytest.ini
20
+ include mypy.ini
21
+
22
+ # Include examples
23
+ recursive-include examples *.py *.xml *.md
24
+
25
+ # Include tests in source distribution (but not in wheel)
26
+ recursive-include tests *.py *.xml *.json
27
+
28
+ # Include docs
29
+ recursive-include docs *.rst *.py *.md Makefile
30
+
31
+ # Exclude unnecessary files
32
+ global-exclude __pycache__
33
+ global-exclude *.py[co]
34
+ global-exclude .DS_Store
35
+ global-exclude .git*
36
+ global-exclude .coverage
37
+ global-exclude .pytest_cache
38
+ global-exclude .mypy_cache
39
+ global-exclude .tox
40
+ global-exclude .vscode
41
+ global-exclude .idea
42
+ global-exclude *.egg-info
43
+ recursive-exclude tests *
44
+ recursive-exclude docs/_build *
@@ -0,0 +1,456 @@
1
+ Metadata-Version: 2.1
2
+ Name: ddex-workbench
3
+ Version: 1.0.0
4
+ Summary: Official Python SDK for DDEX Workbench - Open-source DDEX validation tools
5
+ Home-page: https://github.com/daddykev/ddex-workbench
6
+ Author: DDEX Workbench Contributors
7
+ Author-email: DDEX Workbench Contributors <support@ddex-workbench.org>
8
+ License: MIT
9
+ Project-URL: Homepage, https://ddex-workbench.org
10
+ Project-URL: Documentation, https://ddex-workbench.org/docs
11
+ Project-URL: Repository, https://github.com/daddykev/ddex-workbench
12
+ Project-URL: Issues, https://github.com/daddykev/ddex-workbench/issues
13
+ Keywords: ddex,ern,music,metadata,validation,xml,music-industry,sdk
14
+ Classifier: Development Status :: 5 - Production/Stable
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: License :: OSI Approved :: MIT License
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3.7
19
+ Classifier: Programming Language :: Python :: 3.8
20
+ Classifier: Programming Language :: Python :: 3.9
21
+ Classifier: Programming Language :: Python :: 3.10
22
+ Classifier: Programming Language :: Python :: 3.11
23
+ Classifier: Programming Language :: Python :: 3.12
24
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
25
+ Classifier: Topic :: Multimedia :: Sound/Audio
26
+ Requires-Python: >=3.7
27
+ Description-Content-Type: text/markdown
28
+ License-File: LICENSE
29
+ Requires-Dist: requests>=2.28.0
30
+ Requires-Dist: typing-extensions>=4.0.0; python_version < "3.8"
31
+ Requires-Dist: dataclasses>=0.6; python_version < "3.7"
32
+ Provides-Extra: dev
33
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
34
+ Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
35
+ Requires-Dist: pytest-mock>=3.10.0; extra == "dev"
36
+ Requires-Dist: black>=23.0.0; extra == "dev"
37
+ Requires-Dist: mypy>=1.0.0; extra == "dev"
38
+ Requires-Dist: flake8>=6.0.0; extra == "dev"
39
+ Requires-Dist: tox>=4.0.0; extra == "dev"
40
+ Requires-Dist: twine>=4.0.0; extra == "dev"
41
+
42
+ # DDEX Workbench Python SDK
43
+
44
+ [![PyPI version](https://img.shields.io/pypi/v/ddex-workbench.svg)](https://pypi.org/project/ddex-workbench/)
45
+ [![Python versions](https://img.shields.io/pypi/pyversions/ddex-workbench.svg)](https://pypi.org/project/ddex-workbench/)
46
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
47
+ [![Documentation](https://img.shields.io/badge/docs-latest-blue.svg)](https://ddex-workbench.org/docs)
48
+
49
+ Official Python SDK for [DDEX Workbench](https://ddex-workbench.org) - Open-source DDEX validation and processing tools for the music industry.
50
+
51
+ ## Features
52
+
53
+ - 🚀 **Simple API** - Intuitive methods for all DDEX operations
54
+ - 🔧 **Type Safety** - Full type hints and dataclass models
55
+ - 🌐 **Async Support** - Built-in connection pooling and retry logic
56
+ - 📊 **Batch Processing** - Validate multiple files efficiently
57
+ - 🎯 **Auto-detection** - Automatic ERN version detection
58
+ - 📈 **Detailed Reports** - Comprehensive validation reports in multiple formats
59
+ - 🔑 **API Key Management** - Built-in authentication handling
60
+
61
+ ## Installation
62
+
63
+ ```bash
64
+ pip install ddex-workbench
65
+ ```
66
+
67
+ For development:
68
+ ```bash
69
+ pip install ddex-workbench[dev]
70
+ ```
71
+
72
+ ## Quick Start
73
+
74
+ ```python
75
+ from ddex_workbench import DDEXClient
76
+
77
+ # Initialize client (API key optional for higher rate limits)
78
+ client = DDEXClient(api_key="ddex_your-api-key")
79
+
80
+ # Validate ERN XML
81
+ with open("release.xml", "r") as f:
82
+ xml_content = f.read()
83
+
84
+ result = client.validate(xml_content, version="4.3", profile="AudioAlbum")
85
+
86
+ if result.valid:
87
+ print("✅ Validation passed!")
88
+ else:
89
+ print(f"❌ Found {len(result.errors)} errors:")
90
+ for error in result.errors[:5]:
91
+ print(f" Line {error.line}: {error.message}")
92
+ ```
93
+
94
+ ## Usage Examples
95
+
96
+ ### Basic Validation
97
+
98
+ ```python
99
+ from ddex_workbench import DDEXClient
100
+
101
+ client = DDEXClient()
102
+
103
+ # Validate with specific version
104
+ result = client.validate(xml_content, version="4.3")
105
+
106
+ # Validate with profile
107
+ result = client.validate(xml_content, version="4.3", profile="AudioAlbum")
108
+
109
+ # Validate file directly
110
+ result = client.validate_file("path/to/release.xml", version="4.3")
111
+
112
+ # Validate from URL
113
+ result = client.validate_url("https://example.com/release.xml", version="4.3")
114
+ ```
115
+
116
+ ### Auto-detect Version
117
+
118
+ ```python
119
+ # Automatically detect ERN version
120
+ result = client.validator.validate_auto(xml_content)
121
+ print(f"Detected version: {result.metadata.schema_version}")
122
+ ```
123
+
124
+ ### Batch Processing
125
+
126
+ ```python
127
+ from pathlib import Path
128
+
129
+ # Validate all XML files in a directory
130
+ xml_files = Path("releases").glob("*.xml")
131
+
132
+ for xml_file in xml_files:
133
+ result = client.validate_file(xml_file, version="4.3")
134
+ status = "✅ Valid" if result.valid else f"❌ {len(result.errors)} errors"
135
+ print(f"{xml_file.name}: {status}")
136
+ ```
137
+
138
+ ### Parallel Batch Validation
139
+
140
+ ```python
141
+ # Validate multiple files in parallel
142
+ items = [
143
+ (xml1_content, "4.3", "AudioAlbum"),
144
+ (xml2_content, "4.3", "AudioSingle"),
145
+ (xml3_content, "4.2", None)
146
+ ]
147
+
148
+ results = client.validator.validate_batch(items, max_workers=5)
149
+
150
+ for i, result in enumerate(results):
151
+ print(f"File {i+1}: {'Valid' if result.valid else 'Invalid'}")
152
+ ```
153
+
154
+ ### Directory Validation
155
+
156
+ ```python
157
+ from pathlib import Path
158
+
159
+ # Validate entire directory
160
+ results = client.validator.validate_directory(
161
+ Path("releases"),
162
+ version="4.3",
163
+ pattern="*.xml",
164
+ recursive=True
165
+ )
166
+
167
+ # Generate summary
168
+ valid_count = sum(1 for r in results.values() if r.valid)
169
+ print(f"Valid: {valid_count}/{len(results)}")
170
+ ```
171
+
172
+ ### Error Analysis
173
+
174
+ ```python
175
+ # Group errors by severity
176
+ errors_by_severity = result.get_errors_by_severity()
177
+ for severity, errors in errors_by_severity.items():
178
+ print(f"{severity}: {len(errors)} errors")
179
+
180
+ # Group errors by line
181
+ errors_by_line = result.get_errors_by_line()
182
+ for line, errors in errors_by_line.items():
183
+ print(f"Line {line}: {len(errors)} errors")
184
+
185
+ # Filter specific errors
186
+ from ddex_workbench.utils import filter_errors
187
+
188
+ critical_errors = filter_errors(
189
+ result.errors,
190
+ severity="error",
191
+ rule_pattern="ERN.*"
192
+ )
193
+ ```
194
+
195
+ ### Generate Reports
196
+
197
+ ```python
198
+ from ddex_workbench.utils import format_validation_report
199
+
200
+ # Text report
201
+ text_report = format_validation_report(result, format_type="text")
202
+ print(text_report)
203
+
204
+ # JSON report
205
+ json_report = format_validation_report(result, format_type="json")
206
+ with open("report.json", "w") as f:
207
+ f.write(json_report)
208
+
209
+ # CSV report
210
+ csv_report = format_validation_report(result, format_type="csv")
211
+ with open("report.csv", "w") as f:
212
+ f.write(csv_report)
213
+ ```
214
+
215
+ ### API Key Management
216
+
217
+ ```python
218
+ # For authenticated endpoints (requires Firebase auth token)
219
+ auth_token = "your_firebase_auth_token"
220
+
221
+ # List API keys
222
+ keys = client.list_api_keys(auth_token)
223
+ for key in keys:
224
+ print(f"{key.name}: {key.request_count} requests")
225
+
226
+ # Create new API key
227
+ new_key = client.create_api_key("Production Key", auth_token)
228
+ print(f"New API key: {new_key.key}") # Save this! Only shown once
229
+
230
+ # Revoke API key
231
+ client.revoke_api_key(key_id, auth_token)
232
+ ```
233
+
234
+ ### Utility Functions
235
+
236
+ ```python
237
+ from ddex_workbench.utils import (
238
+ detect_ern_version,
239
+ extract_message_id,
240
+ calculate_file_hash,
241
+ create_summary_statistics
242
+ )
243
+
244
+ # Detect version
245
+ version = detect_ern_version(xml_content)
246
+ print(f"Detected version: {version}")
247
+
248
+ # Extract message ID
249
+ message_id = extract_message_id(xml_content)
250
+ print(f"Message ID: {message_id}")
251
+
252
+ # Calculate file hash
253
+ file_hash = calculate_file_hash(Path("release.xml"))
254
+ print(f"SHA256: {file_hash}")
255
+
256
+ # Create summary statistics
257
+ results = [result1, result2, result3]
258
+ stats = create_summary_statistics(results)
259
+ print(f"Validity rate: {stats['validity_rate']:.1f}%")
260
+ ```
261
+
262
+ ## Command Line Interface
263
+
264
+ ```bash
265
+ # Validate a file
266
+ ddex-validate release.xml --version 4.3 --profile AudioAlbum
267
+
268
+ # Validate directory
269
+ ddex-validate releases/ --version 4.3 --recursive
270
+
271
+ # Auto-detect version
272
+ ddex-validate release.xml --auto
273
+
274
+ # Generate report
275
+ ddex-validate release.xml --version 4.3 --report report.json --format json
276
+ ```
277
+
278
+ ## Configuration
279
+
280
+ ```python
281
+ from ddex_workbench import DDEXClient
282
+
283
+ # Full configuration
284
+ client = DDEXClient(
285
+ api_key="ddex_your-api-key", # Optional API key
286
+ base_url="https://api.ddex-workbench.org/v1", # API endpoint
287
+ timeout=30, # Request timeout in seconds
288
+ max_retries=3, # Max retry attempts
289
+ retry_delay=1.0, # Initial retry delay
290
+ verify_ssl=True # SSL verification
291
+ )
292
+
293
+ # Update API key
294
+ client.set_api_key("new_api_key")
295
+
296
+ # Remove API key
297
+ client.clear_api_key()
298
+ ```
299
+
300
+ ## Error Handling
301
+
302
+ ```python
303
+ from ddex_workbench.errors import (
304
+ DDEXError,
305
+ RateLimitError,
306
+ ValidationError,
307
+ AuthenticationError,
308
+ NotFoundError
309
+ )
310
+
311
+ try:
312
+ result = client.validate(xml_content, version="4.3")
313
+ except RateLimitError as e:
314
+ print(f"Rate limited. Retry after {e.retry_after} seconds")
315
+ print(e.get_retry_message())
316
+ except AuthenticationError:
317
+ print("Invalid API key")
318
+ except ValidationError as e:
319
+ print(f"Validation error: {e.get_summary()}")
320
+ except DDEXError as e:
321
+ print(f"DDEX error: {e}")
322
+ ```
323
+
324
+ ## Advanced Features
325
+
326
+ ### Context Manager
327
+
328
+ ```python
329
+ # Automatic session cleanup
330
+ with DDEXClient(api_key="ddex_key") as client:
331
+ result = client.validate(xml_content, version="4.3")
332
+ # Session automatically closed after block
333
+ ```
334
+
335
+ ### Connection Pooling
336
+
337
+ The SDK automatically manages connection pooling for optimal performance:
338
+
339
+ ```python
340
+ # Reuses connections for multiple requests
341
+ client = DDEXClient()
342
+ for xml_file in xml_files:
343
+ result = client.validate_file(xml_file, version="4.3")
344
+ ```
345
+
346
+ ### Retry Logic
347
+
348
+ Built-in exponential backoff retry for transient failures:
349
+
350
+ ```python
351
+ # Automatically retries on 5xx errors
352
+ client = DDEXClient(max_retries=3, retry_delay=1.0)
353
+ ```
354
+
355
+ ## Supported Versions
356
+
357
+ - **ERN 4.3** (Recommended)
358
+ - **ERN 4.2**
359
+ - **ERN 3.8.2**
360
+
361
+ ## Supported Profiles
362
+
363
+ - AudioAlbum
364
+ - AudioSingle
365
+ - Video
366
+ - Mixed
367
+ - Classical
368
+ - Ringtone
369
+ - DJ
370
+ - ReleaseByRelease (ERN 3.8.2 only)
371
+
372
+ ## Requirements
373
+
374
+ - Python 3.7+
375
+ - requests 2.28+
376
+
377
+ ## Development
378
+
379
+ ```bash
380
+ # Clone repository
381
+ git clone https://github.com/daddykev/ddex-workbench.git
382
+ cd ddex-workbench/packages/python-sdk
383
+
384
+ # Install development dependencies
385
+ pip install -e ".[dev]"
386
+
387
+ # Run tests
388
+ pytest
389
+
390
+ # Run tests with coverage
391
+ pytest --cov=ddex_workbench
392
+
393
+ # Run linting
394
+ flake8 ddex_workbench
395
+ black --check ddex_workbench
396
+ mypy ddex_workbench
397
+
398
+ # Format code
399
+ black ddex_workbench
400
+ isort ddex_workbench
401
+
402
+ # Run all checks with tox
403
+ tox
404
+ ```
405
+
406
+ ## Testing
407
+
408
+ ```bash
409
+ # Run all tests
410
+ pytest
411
+
412
+ # Run specific test file
413
+ pytest tests/test_client.py
414
+
415
+ # Run with coverage
416
+ pytest --cov=ddex_workbench --cov-report=html
417
+
418
+ # Run integration tests
419
+ pytest -m integration
420
+
421
+ # Run tests in parallel
422
+ pytest -n auto
423
+ ```
424
+
425
+ ## Documentation
426
+
427
+ Full documentation available at [https://ddex-workbench.org/docs](https://ddex-workbench.org/docs)
428
+
429
+ ## Contributing
430
+
431
+ We welcome contributions! Please see our [Contributing Guide](https://github.com/daddykev/ddex-workbench/blob/main/CONTRIBUTING.md) for details.
432
+
433
+ ## Support
434
+
435
+ - 📚 [Documentation](https://ddex-workbench.org/docs)
436
+ - 💬 [GitHub Issues](https://github.com/daddykev/ddex-workbench/issues)
437
+ - 📧 [Email Support](mailto:support@ddex-workbench.org)
438
+ - 🌐 [Website](https://ddex-workbench.org)
439
+
440
+ ## License
441
+
442
+ MIT License - see [LICENSE](LICENSE) for details.
443
+
444
+ ## Related Projects
445
+
446
+ - [DDEX Workbench](https://ddex-workbench.org) - Web application
447
+ - [@ddex-workbench/sdk](https://www.npmjs.com/package/@ddex-workbench/sdk) - JavaScript/TypeScript SDK
448
+ - [DDEX Knowledge Base](https://kb.ddex.net) - Official DDEX documentation
449
+
450
+ ## Changelog
451
+
452
+ See [CHANGELOG.md](CHANGELOG.md) for version history.
453
+
454
+ ---
455
+
456
+ Built with ❤️ for the music industry by the DDEX Workbench team.