docs: add PR description and update CHANGELOG for #355

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
KaifAhmad1
2026-03-07 02:07:44 +05:30
co-authored by Claude Sonnet 4.6
parent 8c4e5e5968
commit 34df1964b9
2 changed files with 83 additions and 0 deletions
+6
View File
@@ -7,6 +7,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
- **TTL Export Alias Fix** (PR #355 by @ZohaibHassan16):
- Added `_format_aliases` map in `RDFExporter` so `format="ttl"`, `"nt"`, `"xml"`, `"rdf"`, and `"json-ld"` resolve to their canonical counterparts without breaking existing callers
- Alias resolution applied at the top of `export_to_rdf()` before format validation — zero public API changes
- Added working TTL export cell to `cookbook/introduction/15_Export.ipynb` (Step 3: RDF Export)
- Added `tests/export/test_rdf_exporter.py` with 8 tests covering all aliases, canonical formats, error handling, and file export
- **Incremental/Delta Processing Feature** (PR #349 by @ZohaibHassan16, reviewed and fixed by @KaifAhmad1):
- Native delta computation between graph snapshots using SPARQL queries
- Delta-aware pipeline execution with `delta_mode` configuration for processing only changed data
+77
View File
@@ -0,0 +1,77 @@
## Description
Fixes two gaps that made Turtle/TTL export inaccessible:
1. `format="ttl"` raised a `ValidationError` because `"ttl"` was not accepted as an alias for `"turtle"` in `RDFExporter`, even though it is the standard file extension.
2. `RDFExporter` was never introduced in `cookbook/introduction/15_Export.ipynb`, so users following the default learning path had no way to discover TTL export.
## Type of Change
- [x] Bug fix (non-breaking change which fixes an issue)
- [x] Documentation update
## Related Issues
Closes #355
## Changes Made
- `semantica/export/rdf_exporter.py`: Added `_format_aliases` dict in `RDFExporter.__init__()` mapping common shorthands to canonical format names (`ttl→turtle`, `nt→ntriples`, `xml→rdfxml`, `rdf→rdfxml`, `json-ld→jsonld`). Added one-line alias resolution at the top of `export_to_rdf()` before format validation — all existing callers using canonical names are unaffected.
- `cookbook/introduction/15_Export.ipynb`: Added a code cell in Step 3 (RDF Export) demonstrating `format="ttl"` and `validate_rdf()`.
- `tests/export/test_rdf_exporter.py`: New test file with 8 tests covering alias parity, canonical formats, unsupported format error, and file export with `format="ttl"`.
## Testing
- [x] Tested locally
- [x] Added tests for new functionality
- [x] Package builds successfully (`python -m build`)
### Test Commands
```bash
# Run new RDF exporter tests
pytest tests/export/test_rdf_exporter.py -v
# Verify the original bug is fixed
python -c "
from semantica.export import RDFExporter
exporter = RDFExporter()
rdf_data = {
'entities': [
{'id': 'e1', 'text': 'Apple Inc.', 'type': 'ORG', 'confidence': 0.95},
{'id': 'e2', 'text': 'Steve Jobs', 'type': 'PERSON', 'confidence': 0.97},
],
'relationships': [
{'source_id': 'e2', 'target_id': 'e1', 'type': 'founded_by', 'confidence': 0.91},
],
}
exporter.export(rdf_data, 'output.ttl', format='ttl')
print('format=ttl works correctly')
"
# Full test suite
pytest tests/
```
## Documentation
- [x] Updated relevant documentation
- [x] Added code examples if applicable
- [x] Updated cookbook if adding new examples
## Breaking Changes
**Breaking Changes**: No
All existing callers using canonical format names (`"turtle"`, `"rdfxml"`, `"jsonld"`, `"ntriples"`, `"n3"`) are completely unaffected. The alias map is purely additive.
## Checklist
- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] My changes generate no new warnings
- [x] Package builds successfully
## Additional Notes
The alias resolution uses `.lower()` on the input before lookup, so `"TTL"`, `"Ttl"`, etc. also work. No public API signatures were changed.