===================
Python RevisionDict
===================
.. image:: https://img.shields.io/pypi/v/revisiondict.svg
:target: https://pypi.python.org/pypi/revisiondict
.. image:: https://img.shields.io/travis/semiversus/python-revisiondict.svg
:target: https://travis-ci.org/semiversus/python-revisiondict
.. image:: https://codecov.io/gh/semiversus/python-revisiondict/branch/master/graph/badge.svg
:target: https://codecov.io/gh/semiversus/python-revisiondict
.. image:: https://img.shields.io/github/license/semiversus/python-revisiondict.svg
:target: https://en.wikipedia.org/wiki/MIT_License
RevisionDict works like an ordinary dictionary with additional revision keeping of changes. It remembers the order when
keys were *updated* (in contrast to the ``OrderedDict`` which is remembering the order when keys are *inserted*).
It is revision tracking the overall dictionary, but does not store each earlier value for each key in the dictionary.
It's basically answering the following questions:
* What is the actual revision number?
* What changed since revsion number *N*?
* In which revision has value of key *K* changed the last time?
Use `RevisionDict` to build caching systems, interface multiple clients to a common database,
publish/subscribe systems,...
Additional functionality compared to ``dict()``:
* ``.revision`` - returning the actual revision as integer (starting with 0)
* ``.base_revision`` - revision before oldest item changed (or 0 on empty dict)
* ``.key_to_revision(key)`` - return the revision when the given key was changed
* ``.checkout(start=0)`` - return a dict with changes since ``start``
Install
-------
.. code-block:: bash
pip install revisiondict
Example
-------
.. code::python
>>> from revisiondict import RevisionDict
>>> d = RevisionDict()
>>> d.revision # get revision (is 0 at init)
0
>>> d.base_revision # get revision before oldest change
0
Adding new items:
.. code::python
>>> d['a']=0; d['b']=1; d['c']=2 # make three updates
>>> d.revision # showing 3 changes
3
>>> d.base_revision # get revision before oldest change
0
Inspecting content of RevisionDict:
.. code::python
>>> d.checkout()=={'a': 0, 'b': 1, 'c': 2} # get a dictionary with all changes
True
>>> d.checkout(2) # get all changes starting with rev. 2
{'c': 2}
>>> d.checkout(3) # all changes starting with actual revision
{}
>>> d.key_to_revision('b') # revision where 'b' was changed last time
2
>>> d
RevisionDict([_Item(key='a', value=0, revision=1), _Item(key='b', value=1, revision=2), _Item(key='c', value=2, revision=3)])
Update items:
.. code::python
>>> d['a']=3 # update value of 'a' (was 0 before)
>>> d.revision
4
>>> d.base_revision
1
>>> d.key_to_revision('a')
4
>>> d.checkout(3) # get all changes starting with rev. 3
{'a': 3}
>>> tuple(d.keys()) # iterate over keys (ordered by time of update)
('b', 'c', 'a')
`UniqueRevisionDict`
--------------------
`UniqueRevisionDict` is a subclass of `RevisionDict` which does not create a new revision, when an element is
updated with the same value.
.. code::python
>>> from revisiondict import UniqueRevisionDict
>>> d = UniqueRevisionDict(a=0)
>>> d.revision
1
>>> d['a']=0 # value is equal to the previous one
>>> d.revision
1
>>> d['a']=False # value is still equal as 0 == False
>>> d.revision
1
>>> d['a']=100 # a new value is set, so revision is increased
>>> d.revision
2
Raw data
{
"_id": null,
"home_page": "https://github.com/semiversus/python-revisiondict",
"name": "revisiondict",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "dict revision versioning",
"author": "G\u00fcnther Jena",
"author_email": "guenther@jena.at",
"download_url": "https://files.pythonhosted.org/packages/d6/e0/7d7dc3bbebf6314a4eedd098c2d9a567c3c822abe7fbb855d2adb54af8ff/revisiondict-1.1.0.tar.gz",
"platform": null,
"description": "===================\nPython RevisionDict\n===================\n\n.. image:: https://img.shields.io/pypi/v/revisiondict.svg\n :target: https://pypi.python.org/pypi/revisiondict\n\n.. image:: https://img.shields.io/travis/semiversus/python-revisiondict.svg\n :target: https://travis-ci.org/semiversus/python-revisiondict\n\n.. image:: https://codecov.io/gh/semiversus/python-revisiondict/branch/master/graph/badge.svg\n :target: https://codecov.io/gh/semiversus/python-revisiondict\n\n.. image:: https://img.shields.io/github/license/semiversus/python-revisiondict.svg\n :target: https://en.wikipedia.org/wiki/MIT_License\n\nRevisionDict works like an ordinary dictionary with additional revision keeping of changes. It remembers the order when\nkeys were *updated* (in contrast to the ``OrderedDict`` which is remembering the order when keys are *inserted*).\n\nIt is revision tracking the overall dictionary, but does not store each earlier value for each key in the dictionary.\nIt's basically answering the following questions:\n\n* What is the actual revision number?\n* What changed since revsion number *N*?\n* In which revision has value of key *K* changed the last time?\n\nUse `RevisionDict` to build caching systems, interface multiple clients to a common database,\npublish/subscribe systems,...\n\nAdditional functionality compared to ``dict()``:\n\n* ``.revision`` - returning the actual revision as integer (starting with 0)\n* ``.base_revision`` - revision before oldest item changed (or 0 on empty dict)\n* ``.key_to_revision(key)`` - return the revision when the given key was changed\n* ``.checkout(start=0)`` - return a dict with changes since ``start``\n\nInstall\n-------\n\n.. code-block:: bash\n\n pip install revisiondict\n\nExample\n-------\n\n.. code::python\n\n>>> from revisiondict import RevisionDict\n>>> d = RevisionDict()\n>>> d.revision # get revision (is 0 at init)\n0\n>>> d.base_revision # get revision before oldest change\n0\n\nAdding new items:\n\n.. code::python\n\n>>> d['a']=0; d['b']=1; d['c']=2 # make three updates\n>>> d.revision # showing 3 changes\n3\n>>> d.base_revision # get revision before oldest change\n0\n\nInspecting content of RevisionDict:\n\n.. code::python\n\n>>> d.checkout()=={'a': 0, 'b': 1, 'c': 2} # get a dictionary with all changes\nTrue\n>>> d.checkout(2) # get all changes starting with rev. 2\n{'c': 2}\n>>> d.checkout(3) # all changes starting with actual revision\n{}\n>>> d.key_to_revision('b') # revision where 'b' was changed last time\n2\n>>> d\nRevisionDict([_Item(key='a', value=0, revision=1), _Item(key='b', value=1, revision=2), _Item(key='c', value=2, revision=3)])\n\nUpdate items:\n\n.. code::python\n\n>>> d['a']=3 # update value of 'a' (was 0 before)\n>>> d.revision\n4\n>>> d.base_revision\n1\n>>> d.key_to_revision('a')\n4\n>>> d.checkout(3) # get all changes starting with rev. 3\n{'a': 3}\n>>> tuple(d.keys()) # iterate over keys (ordered by time of update)\n('b', 'c', 'a')\n\n\n`UniqueRevisionDict`\n--------------------\n\n`UniqueRevisionDict` is a subclass of `RevisionDict` which does not create a new revision, when an element is\nupdated with the same value.\n\n.. code::python\n\n>>> from revisiondict import UniqueRevisionDict\n>>> d = UniqueRevisionDict(a=0)\n>>> d.revision\n1\n\n>>> d['a']=0 # value is equal to the previous one\n>>> d.revision\n1\n\n>>> d['a']=False # value is still equal as 0 == False\n>>> d.revision\n1\n\n>>> d['a']=100 # a new value is set, so revision is increased\n>>> d.revision\n2\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "RevisionDict works like an ordinary dictionary with additional revision keeping of changes.",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/semiversus/python-revisiondict"
},
"split_keywords": [
"dict",
"revision",
"versioning"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3f0033df6cacee770588a9a0a5766e7d9869fa32ad1018ed953bdff56c38701f",
"md5": "2a8863377201071568494c5b84045396",
"sha256": "4ca256d19813f13ff1293550f53c28d2bb28c750d882580a5f696afb8efa3104"
},
"downloads": -1,
"filename": "revisiondict-1.1.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "2a8863377201071568494c5b84045396",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 6622,
"upload_time": "2024-02-03T18:12:59",
"upload_time_iso_8601": "2024-02-03T18:12:59.461794Z",
"url": "https://files.pythonhosted.org/packages/3f/00/33df6cacee770588a9a0a5766e7d9869fa32ad1018ed953bdff56c38701f/revisiondict-1.1.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "d6e07d7dc3bbebf6314a4eedd098c2d9a567c3c822abe7fbb855d2adb54af8ff",
"md5": "f70009596f55c7188e45bef122ecc892",
"sha256": "7f5165bf7559e850f46d57c0afaf742df15f80aab9ac2a1770160cb4c36860f9"
},
"downloads": -1,
"filename": "revisiondict-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "f70009596f55c7188e45bef122ecc892",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12570,
"upload_time": "2024-02-03T18:13:01",
"upload_time_iso_8601": "2024-02-03T18:13:01.083474Z",
"url": "https://files.pythonhosted.org/packages/d6/e0/7d7dc3bbebf6314a4eedd098c2d9a567c3c822abe7fbb855d2adb54af8ff/revisiondict-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-02-03 18:13:01",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "semiversus",
"github_project": "python-revisiondict",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "revisiondict"
}
JSON
