KeepDelta: A Python Library for Human-Readable Data Differencing

KeepDelta is a lightweight Python library designed to efficiently track and manage changes (deltas) between Python built-in types. It is applicable to various scenarios that require dynamic data management, especially when incremental numerical changes are present, such as simulations and sensing. While many alternative tools operate at the binary level, KeepDelta emphasizes human-readable delta encoding, facilitating debugging and analysis for Python developers and researchers across multiple domains.

What is Delta Encoding?

In many computational scenarios, efficiently managing evolving data is crucial. Traditional methods, that rely on full-state encoding — which means storing and/or transmitting complete snapshots at each step — can be inefficient due to the large size of the snapshots. Delta encoding addresses this challenge by capturing and applying only the changes (deltas) between successive states of data structures, resulting in significantly smaller and more manageable data.

Features

    • Generates compact and human-readable differences between two Python variables.
    • Applies delta to a variable to reconstruct the updated version.
    • Supports common Python built-in data types.
    • Handles deeply nested and mixed data structures efficiently.
    • Requires no external dependencies.

Installation

Install the package using pip:

pip install keepdelta

Usage

There are two core methods corresponding to the creation and application of delta encodings:

1. create(old, new):

The create function compares the old and new variables to generate delta that captures the differences between two data structures. It produces a compact data structure containing only these differences, and its high human readability greatly aids debugging during development.

Example:

>>> import keepdelta as kd

>>> # Initial data
>>> old = {
...     "name": "Alice",
...     "age": 20,
...     "is_student": True
... }

>>> # Updated data
>>> new = {
...     "name": "Alice",
...     "age": 25,
...     "is_student": False
... }

>>> # Create delta
>>> delta = kd.create(old, new)
>>> print(delta)
{
    "age": 5,
    "is_student": False
}

2. apply(old, delta):

The apply function takes the old variable and the delta, then applies the delta to recreate the updated, new variable.

Example:

>>> import keepdelta as kd

>>> # Initial data
>>> old = {
...     "name": "Alice",
...     "age": 20,
...     "is_student": True
... }

>>> # Delta
>>> delta = {
...     "age": 5,
...     "is_student": False
... }

>>> # Apply delta
>>> new = kd.apply(old, delta)
>>> print(new)
{
    "name": "Alice",
    "age": 25,
    "is_student": False
}

For more usage examples, refer to the examples folder in the project repository, or "Supported Data Types & Behaviors” section on the GitHub repository, for a detailed look at how each structure is handled.

Supported Python Versions

KeepDelta has been tested and verified to work with Python versions 3.7 to 3.13. While it is expected to work with older versions, they have not been tested and are not officially supported.

Citing KeepDelta

If you use KeepDelta in your work, please cite our paper.

You can either:

    - Click the “Cite this repository” button at the top of the GitHub page and copy the generated APA or BibTeX.

Or,

    - Copy one of the entries below:

BibTeX:

@article{Noorghasemi_KeepDelta_A_Python_2025,
author = {Noorghasemi, Aslan and McComb, Christopher},
doi = {10.21105/joss.08075},
journal = {Journal of Open Source Software},
month = jun,
number = {110},
pages = {8075},
title = {{KeepDelta: A Python Library for Human-Readable Data Differencing}},
url = {https://joss.theoj.org/papers/10.21105/joss.08075},
volume = {10},
year = {2025}
}

APA:

Noorghasemi, A., & McComb, C. (2025). KeepDelta: A Python Library for Human-Readable Data Differencing. Journal of Open Source Software, 10(110), 8075. https://doi.org/10.21105/joss.08075

Contributing

Contributions are welcome on GitHub! Feel free to:
    • Report issues.
    • Submit feature requests.
    • Create pull requests.

License

Distributed under the MIT License. See LICENSE.txt for more information.