# TSIH - A dict with a HISTory
`tsih.Dict` is a type of `UserDict` that allows versioning, backed up by a `sqlite3` database.
* Transparent operation
* Only changes (deltas) are stored.
* Forward-filling of values. A value is reused in future versions, unless it changes.
* Auto-versioning option (off by default), to produce a new version every time a value change happens.
* Ability to store related entries as separate dictionaries. Each `tsih.Dict` has a `dict_name` that is used in the database to identify the dictionary.
* Tuple-based indexing. Get and set values by `dict_name`, `version` and `key`.
## Usage and examples
`tsih.Dict` objects can be used just like regular dictionaries:
```python
>>> from tsih import Dict
>>> a = Dict()
>>> a['test'] = True
>>> a
{'test': True}
>>> a.get('missing', 5)
5
>>> a['missing']
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
KeyError: 'missing'
```
But at any point, new versions can be produced:
```python
>>> a.version
0
>>> a['start'] = 'now'
>>> a
{'test': True, 'start': 'now'}
>>> a.version = 1
>>> a['start'] = 'one version ago'
>>> a
{'test': True, 'start': 'one version ago'}
```
Previous values can be accessed using tuple keys, i.e., (version, key):
```python
>>> a[(0, 'start')]
'now'
>>> a[(1, 'start')]
'one version ago'
```
Each version only "records" changes, but later versions (even if they don't exist yet) inherit unchanged values from the previous ones:
```python
>>> a[(5, 'start')]
'one version ago'
>>> a.version = 5
>>> # Until the value is changed
>>> a['start'] = '4 versions ago'
>>> a[(5, 'start')]
'4 versions ago'
```
You can access *every* state of the Dict using `None` in place of the version and/or the key.
In that case, we will get an iterator, which we can turn into a list explicitly or with the `.value` method.
For example, here we get all the changes to the `start` key:
```python
>>> a[(None, 'start')].value() #
[(0.0, 'now'), (1.0, 'one version ago'), (5.0, '4 versions ago')]
```
Similarly, to get the keys and values at a specific version:
```python
>>> list(a[(0, None)])
[('start', 'now'), ('test', True)]
```
Or, we can combine both to get the keys and values at every version:
```python
>>> a[(None, None)].value()
[(0.0, 'start', 'now'), (1.0, 'start', 'one version ago'), (5.0, 'start', '4 versions ago'), (0.0, 'test', True), (1.0, 'test', True), (5.0, 'test', True)]
```
## Use cases
Tsih was originally part of the [Soil](https://github.com/gsi-upm/soil) Agent-Based Social Simulation framework, where both the environment and the agents need to keep track of state (i.e., attribute) changes.
Raw data
{
"_id": null,
"home_page": "https://github.com/balkian/tsih",
"name": "tsih",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "history,sql,records",
"author": "J. Fernando Sanchez",
"author_email": "jf.sanchez@upm.es",
"download_url": "https://files.pythonhosted.org/packages/07/f0/8f16d1432f6a43e1a3609e778d99620cea0da90ea13d800c59a59c71737d/tsih-0.1.9.tar.gz",
"platform": null,
"description": "# TSIH - A dict with a HISTory\n\n`tsih.Dict` is a type of `UserDict` that allows versioning, backed up by a `sqlite3` database.\n\n* Transparent operation\n* Only changes (deltas) are stored.\n* Forward-filling of values. A value is reused in future versions, unless it changes.\n* Auto-versioning option (off by default), to produce a new version every time a value change happens.\n* Ability to store related entries as separate dictionaries. Each `tsih.Dict` has a `dict_name` that is used in the database to identify the dictionary.\n* Tuple-based indexing. Get and set values by `dict_name`, `version` and `key`.\n\n## Usage and examples\n\n`tsih.Dict` objects can be used just like regular dictionaries:\n\n```python\n>>> from tsih import Dict\n>>> a = Dict()\n>>> a['test'] = True\n>>> a\n{'test': True}\n>>> a.get('missing', 5)\n5\n>>> a['missing']\nTraceback (most recent call last):\n File \"<stdin>\", line 1, in <module>\nKeyError: 'missing'\n```\n\nBut at any point, new versions can be produced:\n\n```python\n>>> a.version\n0\n>>> a['start'] = 'now'\n>>> a\n{'test': True, 'start': 'now'}\n>>> a.version = 1\n>>> a['start'] = 'one version ago'\n>>> a\n{'test': True, 'start': 'one version ago'}\n```\n\nPrevious values can be accessed using tuple keys, i.e., (version, key):\n\n```python\n>>> a[(0, 'start')]\n'now'\n>>> a[(1, 'start')]\n'one version ago'\n```\n\nEach version only \"records\" changes, but later versions (even if they don't exist yet) inherit unchanged values from the previous ones:\n\n```python\n>>> a[(5, 'start')] \n'one version ago'\n>>> a.version = 5\n>>> # Until the value is changed\n>>> a['start'] = '4 versions ago' \n>>> a[(5, 'start')]\n'4 versions ago'\n```\n\nYou can access *every* state of the Dict using `None` in place of the version and/or the key.\nIn that case, we will get an iterator, which we can turn into a list explicitly or with the `.value` method.\n\nFor example, here we get all the changes to the `start` key:\n\n```python\n>>> a[(None, 'start')].value() # \n[(0.0, 'now'), (1.0, 'one version ago'), (5.0, '4 versions ago')]\n```\n\nSimilarly, to get the keys and values at a specific version:\n\n```python\n>>> list(a[(0, None)])\n[('start', 'now'), ('test', True)]\n```\n\nOr, we can combine both to get the keys and values at every version:\n\n```python\n>>> a[(None, None)].value()\n[(0.0, 'start', 'now'), (1.0, 'start', 'one version ago'), (5.0, 'start', '4 versions ago'), (0.0, 'test', True), (1.0, 'test', True), (5.0, 'test', True)]\n```\n\n## Use cases\n\nTsih was originally part of the [Soil](https://github.com/gsi-upm/soil) Agent-Based Social Simulation framework, where both the environment and the agents need to keep track of state (i.e., attribute) changes.\n\n\n",
"bugtrack_url": null,
"license": "",
"summary": "A lightweight library to store an object's history into a SQL database",
"version": "0.1.9",
"split_keywords": [
"history",
"sql",
"records"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "5a061f601e360c3eb05e02ebbb01d292556512f05aa86ef6cbb3dff66db5db98",
"md5": "2ac33a1ad25b7faa1ca1cc7b2deaa6ec",
"sha256": "e1c4a743c9247493fe0c5d201d078e0a4b1cdce029a691a28accf4877571f9a4"
},
"downloads": -1,
"filename": "tsih-0.1.9-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2ac33a1ad25b7faa1ca1cc7b2deaa6ec",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": null,
"size": 14316,
"upload_time": "2023-03-23T13:18:21",
"upload_time_iso_8601": "2023-03-23T13:18:21.163974Z",
"url": "https://files.pythonhosted.org/packages/5a/06/1f601e360c3eb05e02ebbb01d292556512f05aa86ef6cbb3dff66db5db98/tsih-0.1.9-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "07f08f16d1432f6a43e1a3609e778d99620cea0da90ea13d800c59a59c71737d",
"md5": "a54b8f9d77a0d2d9bcd12cdd3e7d50b1",
"sha256": "b40481b22d7983957d3c8859a245ab7f64236080dcd9bd8ef255147780657e8b"
},
"downloads": -1,
"filename": "tsih-0.1.9.tar.gz",
"has_sig": false,
"md5_digest": "a54b8f9d77a0d2d9bcd12cdd3e7d50b1",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 12014,
"upload_time": "2023-03-23T13:18:23",
"upload_time_iso_8601": "2023-03-23T13:18:23.300995Z",
"url": "https://files.pythonhosted.org/packages/07/f0/8f16d1432f6a43e1a3609e778d99620cea0da90ea13d800c59a59c71737d/tsih-0.1.9.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-03-23 13:18:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "balkian",
"github_project": "tsih",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "tsih"
}
JSON
