{"id":31592598,"url":"https://github.com/ably/vcdiff-python","last_synced_at":"2026-01-20T17:02:46.594Z","repository":{"id":310842577,"uuid":"1023245276","full_name":"ably/vcdiff-python","owner":"ably","description":null,"archived":false,"fork":false,"pushed_at":"2025-09-19T17:11:42.000Z","size":66,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-14T12:24:06.031Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ably.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-20T20:39:08.000Z","updated_at":"2025-09-19T17:11:45.000Z","dependencies_parsed_at":"2025-08-20T16:00:32.311Z","dependency_job_id":"eabff6dc-935d-4bfa-8e19-fa75a80d930d","html_url":"https://github.com/ably/vcdiff-python","commit_stats":null,"previous_names":["ably/vcdiff-py","ably/vcdiff-python"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ably/vcdiff-python","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ably%2Fvcdiff-python","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ably%2Fvcdiff-python/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ably%2Fvcdiff-python/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ably%2Fvcdiff-python/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ably","download_url":"https://codeload.github.com/ably/vcdiff-python/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ably%2Fvcdiff-python/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28607624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T16:10:39.856Z","status":"ssl_error","status_checked_at":"2026-01-20T16:10:39.493Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-06T03:11:30.244Z","updated_at":"2026-01-20T17:02:46.577Z","avatar_url":"https://github.com/ably.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# VCDIFF Python Decoder\n\nA Python implementation of a VCDIFF (RFC 3284) decoder library and command-line tool for efficient binary differencing and compression.\n\n## Overview\n\nThe library provides a VCDIFF decoder that can decode delta files created according to RFC 3284 - The VCDIFF Generic Differencing and Compression Data Format. VCDIFF is a format for expressing one data stream as a variant of another data stream, commonly used for binary differencing, compression, and patch applications.\n\n## Features\n\n- **Python Library**: RFC 3284 compliant VCDIFF decoding with clean, Pythonic API\n- **Command-Line Tool**: Apply deltas and inspect VCDIFF file structure\n- **Comprehensive Validation**: Support for all VCDIFF instruction types (ADD, COPY, RUN)\n- **Address Caching**: Efficient decoding with proper address cache implementation\n- **Checksum Validation**: Full Adler-32 checksum validation support\n- **Robust Error Handling**: Detailed error messages for debugging malformed files\n- **Extensive Testing**: 85 test cases with reference implementation validation\n- **Type Safety**: Full type hints for better development experience\n\n## Limitations\n\n- **Application Headers**: This implementation does not handle application header information\n- **Secondary Compression**: This decoder does not support secondary compression (e.g., gzip, bzip2)\n- **Compatibility**: Works with VCDIFF deltas created using `xdelta3 -e -S -A` (no secondary compression, no application header)\n\n## Checksum Support\n\n- **VCD_ADLER32**: This implementation detects and parses the VCD_ADLER32 extension (bit 0x04 in window indicator)\n- **Non-standard Extension**: The Adler-32 checksum is not part of RFC 3284 but is supported by some implementations\n- **Validation**: Full Adler-32 checksum validation is implemented and performed during decoding\n- **Display**: Checksums are displayed in the CLI output as `Adler32: 0x########`\n\n## Installation\n\n```bash\npip install vcdiff-decoder\n```\n\n### Development Installation\n\n```bash\npoetry install\n```\n\n### Cloning with Test Suite\n\nThis repository includes the VCDIFF test suite as a git submodule. To clone the repository with all test cases:\n\n```bash\ngit clone --recursive https://github.com/ably/vcdiff-python.git\n```\n\nIf you've already cloned the repository without the submodule, initialize it:\n\n```bash\ngit submodule update --init --recursive\n```\n\nTo update the test suite submodule to the latest version:\n\n```bash\ngit submodule update --remote\n```\n\n## Quick Start\n\n### Library Usage\n\n```python\nimport vcdiff_decoder\n\n# Read the source file\nwith open(\"original.txt\", \"rb\") as f:\n    source = f.read()\n\n# Read the VCDIFF delta file\nwith open(\"changes.vcdiff\", \"rb\") as f:\n    delta_data = f.read()\n\n# Apply the delta to reconstruct the target\ntry:\n    result = vcdiff_decoder.decode(source, delta_data)\n    print(f\"Decoded result: {result}\")\nexcept vcdiff_decoder.VCDIFFError as e:\n    print(f\"Decoding failed: {e}\")\n```\n\n## API Reference\n\n### Core Functions\n\n#### `vcdiff.decode(source: bytes, delta: bytes) -\u003e bytes`\n\nDecodes a VCDIFF delta file using the provided source data and returns the reconstructed target data.\n\n**Parameters:**\n- `source`: The original source data (may be empty for deltas that don't reference source)\n- `delta`: The VCDIFF delta file data\n\n**Returns:**\n- Decoded target data as bytes\n\n**Raises:**\n- `VCDIFFError`: If decoding fails (malformed delta, checksum validation failure, etc.)\n\n#### `vcdiff.Decoder(source: bytes)`\n\nCreates a new decoder instance with the specified source data. Useful for decoding multiple deltas against the same source.\n\n**Parameters:**\n- `source`: The source data for decoding operations\n\n**Returns:**\n- A `Decoder` instance that can be used to decode multiple deltas\n\n#### `decoder.decode(delta: bytes) -\u003e bytes`\n\nDecodes a single VCDIFF delta using the decoder's source data.\n\n### Error Handling\n\nThe decoder provides detailed error messages for various failure conditions:\n- Invalid VCDIFF format or magic bytes\n- Malformed varint encoding\n- Out-of-bounds memory access attempts\n- Checksum validation failures\n- Truncated or corrupted delta files\n\n**Exception Hierarchy:**\n- `VCDIFFError`: Base exception for all VCDIFF-related errors\n- `InvalidMagicError`: Invalid VCDIFF magic bytes\n- `InvalidVersionError`: Unsupported VCDIFF version\n- `InvalidFormatError`: Malformed delta structure\n- `CorruptedDataError`: Data corruption detected\n- `InvalidChecksumError`: Checksum validation failure\n\n## Testing\n\n### Prerequisites\n\nFor comprehensive testing, this project uses xdelta3 as a reference implementation to verify the correctness of the decoder.\n\n#### Installing xdelta3\n\n##### macOS (Homebrew)\n```bash\nbrew install xdelta\n```\n\n##### Linux (Ubuntu/Debian)\n```bash\nsudo apt-get install xdelta3\n```\n\n### Running Tests\n\nTo run the Python unit tests:\n\n```bash\npoetry run pytest\n```\n\nTo run tests with coverage:\n\n```bash\npoetry run pytest --cov=vcdiff tests/\n```\n\nTo run the comprehensive test suite against the VCDIFF test cases (requires submodule):\n\n```bash\npoetry run pytest tests/test_vcdiff.py -v\n```\n\nThe test suite includes:\n- **20 general positive tests**: Valid VCDIFF files that should decode successfully\n- **33 targeted negative tests**: Invalid VCDIFF files that should be rejected with appropriate errors\n- **32 targeted positive tests**: Specific feature validation tests\n- **Total**: 85 test cases with 100% pass rate\n\n### Test Results\n- **General Positive Tests**: 20/20 passed ✅\n- **Targeted Negative Tests**: 33/33 passed ✅\n- **Targeted Positive Tests**: 32/32 passed ✅\n\n## Contributing\n\nContributions are welcomed. Please follow these guidelines:\n\n### Getting Started\n\n1. Fork the repository\n2. Clone your fork with submodules: `git clone --recursive \u003cyour-fork-url\u003e`\n3. Create a feature branch: `git checkout -b feature/your-feature-name`\n4. Make your changes\n5. Test your changes thoroughly\n6. Submit a pull request\n\n### Development Guidelines\n\n- **Code Style**: Follow PEP 8 formatting (`black .` for automatic formatting)\n- **Type Hints**: All new code should include proper type annotations\n- **Testing**: All new features must include tests\n- **Documentation**: Update documentation for any API changes\n- **Commits**: Use clear, descriptive commit messages\n\n### Before Submitting\n\nEnsure your contribution passes all checks:\n\n```bash\n# Run all tests\npytest\n\n# Format code\nblack .\n\n# Lint code\nflake8 vcdiff/\n\n# Type checking\nmypy vcdiff/\n```\n\n### Reporting Issues\n\nWhen reporting bugs, please include:\n- Python version\n- Operating system\n- Minimal reproduction case\n- Expected vs actual behavior\n- Sample VCDIFF files (if applicable)\n\n### Feature Requests\n\nFor new features, please:\n- Check existing issues first\n- Describe the use case\n- Provide RFC 3284 references if applicable\n- Consider backwards compatibility\n\n## Requirements\n\n- **Python**: 3.8 or higher\n- **Development Dependencies**:\n  - `pytest\u003e=7.0.0`\n  - `pytest-cov\u003e=4.0.0`\n  - `black\u003e=22.0.0`\n  - `flake8\u003e=5.0.0`\n  - `mypy\u003e=1.0.0`\n\n## License\n\nThis project is licensed under the Apache License 2.0. See the LICENSE file for details.\n\n## References\n\n- [RFC 3284: The VCDIFF Generic Differencing and Compression Data Format](https://tools.ietf.org/html/rfc3284)\n- [xdelta3: VCDIFF binary diff tool](https://github.com/jmacd/xdelta)\n- [Go VCDIFF Implementation](https://github.com/ably/vcdiff-go) - Algorithmically compatible sibling project","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fably%2Fvcdiff-python","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fably%2Fvcdiff-python","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fably%2Fvcdiff-python/lists"}