{
    "info": {
        "author": "J\u00fcrgen Knauth",
        "author_email": "pubsrc@binary-overflow.de",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 4 - Beta",
            "License :: OSI Approved :: Apache Software License",
            "Programming Language :: Python :: 3"
        ],
        "description": "jk_keyvaluestore\n==========\n\nIntroduction\n------------\n\nThis python module implements a simple key-value data base based on JSON data stored in a directory.\n\nInformation about this module can be found here:\n\n* [github.org](https://github.com/jkpubsrc/....)\n* [pypi.python.org](https://pypi.python.org/pypi/jk_keyvaluestore)\n\n### Goals\n\nThis module provides a simple key-value-based data store. The current implementation does not aim for highes performance but for ease of use, even in interprocess domain. This means that ...\n\n* You can instantiate a data store class right away and use it to read and write key-value data. The only thing you need to provide is a writable data directory.\n* A data store can be read-write or read-only.\n* A key can be associated with arbitrary amounts of JSON data.\n* Other data store instances (sharing the same directory) can perform writes as well. These will be visible to the other data store instances.\n\n### Limitations\n\nThe current implementation is pretty straight forward. Every change causes a write of a JSON file that contains that data. This way a) persistency is ensured and b) other instances of a data store will receive the new data. Therefore the concurrency model is very simple: THe most recent write wins.\n\nThough this concept has drawbacks:\n\n* Managing thousands of key-value-pairs will be inefficient as for every key-value-pair a single file is required to hold that data.\n* High frequent changes of data will be inefficient as well.\n* As time stamps are used to synchronize one or more data store instances if you use multiple processes residing on multiple hosts you need to ensure that the system time will not be much different accross all nodes.\n\nThis key-value store is ment for use cases where you desire to keep things simple in your software as the amount of data you need to manage is quite limited.\n\n### Use cases\n\nUse cases for this implementation is:\n\n* Write out state information of an application and monitor it\n* Implement simple interprocess communication\n* Modify configuration data of an application while the application is running\n\n### Benefits of this approach\n\nNevertheless this approach has a variety of benefits:\n\n* Portability: If you (would) require the cooperation of programs written in different languages this can be achieved very easily. Porting this python implementation to other programming languages would be very simple.\n\nHow to use this module\n----------------------\n\n### Import this module\n\nPlease include this module into your application using the following code:\n\n```python\nfrom jk_keyvaluestore import DirBasedKeyValueStore\n```\n\nImporting this way is recommended as currently `DirBasedKeyValueStore` is the only class. (This might change in the future.)\n\nUsing a single instance of the data store\n-----------------------------------------\n\n### Create an instance\n\nTo set up a data store instance is easy:\n\n```python\nds = DirBasedKeyValueStore(dirPath=\"my/data/directory\", identifier=1)\n```\n\nFor clarification all arguments have been named in this example (in their order of declaration).\n\n* `dirPath` must refer to an existing directory that will hold the data. If multiple instances are created they must refer to the same directory.\n* If this is not a read only instance `identifier` must be either a valid string or a valid integer value. If it is a string the identifier is matched against `r[a-zA-Z0-9_+-\\.]+`. If it is an integer the value must be greater or equal to zero. If you specify `None` (which is the default) the data store will be read only.\n\n### Write data\n\nWriting data is very simple. Example:\n\n```python\nds.put(\"someKey\", [ \"some\", \"value\" ])\n```\n\nor:\n\n```python\nds[\"someKey\"] = [ \"some\", \"value\" ]\n```\n\nThe keys must be strings of arbitrary size. Values can be anything that is storable in JSON.\n\n### Read data\n\nReading data is very simple. Example:\n\n```python\nvalue = ds.get(\"someKey\")\n```\n\nor:\n\n```python\nvalue = ds[\"someKey\"]\n```\n\nThis operation will return `None` by default if the key does not exist. (No exception will be raised.)\n\n### Check if a key exists\n\nPerforming a check for existance of a key in the data store is easy. Example:\n\n```python\nbKeyValuePairExists = ds.contains(\"someKey\")\n```\n\nPlease note that the data store will maintain a list of all deleted entries to be able to still synchronize such information with other instances. The data returned by `contains()` will **not** reflect deleted entries. Example:\n\n```python\nds.put(\"someKey\", \"someValue\")\nds.delete(\"someKey\")\nassert ds.contains(\"someKey\") == False\n```\n\n### Delete a single key value pair\n\nDeleting data is very simple. Example:\n\n```python\nds.remove(\"someKey\")\n```\n\nor:\n\n```python\ndel ds[\"someKey\"]\n```\n\nThis operation is indempotent. No exception will be raised if the key has already been deleted.\n\nPlease note that in ordert to maintain synchronization capabilities with other data stores information about this delete will be kept internally in the data store.\n\n### Delete all key value pairs\n\nRemoving all data from a data store is simple. Example:\n\n```python\nds.clear()\n```\n\nThis operation is indempotent. No exception will be raised if the data store is already empty.\n\nPlease note that in order to maintain synchronization capabilities with other data stores information about this delete will be kept internally in the data store.\n\n### Get a list of all keys\n\nIt is possible to get a list of all keys currently in use in the data store. Example:\n\n```python\nallKeys = ds.keys()\n```\n\nThe methhod `keys()` will return a list of keys.\n\nPlease note that the data store will maintain a list of all deleted entries. The data returned by `keys()` will **not** contain deleted entries.\n\nUsing a multipe instances of the data store\n-------------------------------------------\n\n### Instantiation\n\nUsing multiple instances is easy. Example:\n\n```python\n# In program A\ndsA = DirBasedKeyValueStore(dirPath=\"my/data/directory\", identifier=1)\n```\n\n```python\n# In program B\ndsB = DirBasedKeyValueStore(dirPath=\"my/data/directory\", identifier=2)\n```\n\nPlease note that both instances must be distinguishable. Therefore you need to provide unique identifiers for each instance matching the regular expression `r[a-zA-Z0-9_+-\\.]+`. (If you specify an identifier of `None` you will create a read only instance.)\n\nAfter this you can use `get()`, `put()`, `remove()` and other methods.\n\n### Synchronization\n\nIf intermediate changes occurred in other instances of a data store these changes are not synchronized automatically to other data store. Synchronization is entirely up to you: As synchronization is not cheap you as the developer has to decide when a synchronization should be performed.\n\nDuring synchronization the directory of files storing the key-value pairs is scanned for new entries. If new entries are found they will get loaded. The information contained in these files will then be incorporated into the current data store instance. As this is directly dependend on the number of files written since the last time synchronization has been performed, this might be a bit costly. Therefore it is up to you as a developer to decide when exactly these synchronizations should occur.\n\nPerformance\n-----------\n\nAs files are read and written in order to manage all data the time required for file operations is the limiting factor. Here are some performance values based on experience in Python on Linux with a regular SATA-SSD:\n\n| Operation\t\t\t\t\t| Performance\t|\n| ------------------------- | ------------- |\n| get\t\t\t\t\t\t| Limited by python interpreter performance only.\t|\n| put\t\t\t\t\t\t| ~15ms\t\t\t\t\t\t\t\t\t\t\t\t|\n| synchronize single change\t| ~10ms\t\t\t\t\t\t\t\t\t\t\t\t|\n\nAs during instantiation `synchronize()` is called to read all existing data, instantiation performance is very similar to synchronization performance.\n\n(Possible) Future Development\n-----------------------------\n\nThe current implementation is based on synchroneous I/O operations. Future implementation options therefore would be:\n\n* provide an implementation based on asynchroneous I/O\n* provide an implementation for C, Java, C#, maybe even JavaScript\n* maybe provide an implementation accessing data via SFTP\n* explore even better ways of implementing such a data store:\n\t* using named pipes to communicate to a single process\n\nOther things to do:\n\n* test the current implementation on an NFS share\n\nIf you would be interested in improving or porting the current implementation you're welcome. Feel free to contact me.\n\nContact Information\n-------------------\n\nThis is Open Source code. That not only gives you the possibility of freely using this code it also\nallows you to contribute. Feel free to contact the author(s) of this software listed below, either\nfor comments, collaboration requests, suggestions for improvement or reporting bugs:\n\n* J\u00fcrgen Knauth: jknauth@uni-goettingen.de, pubsrc@binary-overflow.de\n\nLicense\n-------\n\nThis software is provided under the following license:\n\n* Apache Software License 2.0",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "https://github.com/jkpubsrc/python-module-jk-keyvaluestore/tarball/0.2019.9.17.1",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/jkpubsrc/python-module-jk-keyvaluestore",
        "keywords": "kvp,json",
        "license": "Apache 2.0",
        "maintainer": "",
        "maintainer_email": "",
        "name": "jk-keyvaluestore",
        "package_url": "https://pypi.org/project/jk-keyvaluestore/",
        "platform": "",
        "project_url": "https://pypi.org/project/jk-keyvaluestore/",
        "project_urls": {
            "Download": "https://github.com/jkpubsrc/python-module-jk-keyvaluestore/tarball/0.2019.9.17.1",
            "Homepage": "https://github.com/jkpubsrc/python-module-jk-keyvaluestore"
        },
        "release_url": "https://pypi.org/project/jk-keyvaluestore/0.2019.9.17.1/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "This python module implements a simple key-value data base based on JSON data stored in a directory.",
        "version": "0.2019.9.17.1"
    },
    "last_serial": 5840634,
    "releases": {
        "0.2019.9.17": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "696b634f7c80c80ac6dcb4f934f892ba",
                    "sha256": "80cd807db028f200316fd138ec26b22d0f5c80503235049559ea6f72b50e9a1a"
                },
                "downloads": -1,
                "filename": "jk_keyvaluestore-0.2019.9.17.tar.gz",
                "has_sig": false,
                "md5_digest": "696b634f7c80c80ac6dcb4f934f892ba",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 10847,
                "upload_time": "2019-09-17T09:28:46",
                "url": "https://files.pythonhosted.org/packages/4d/19/ae3a73aaf159e02e74a24638b083efb9b3e83b80d547dac2f33bedae4460/jk_keyvaluestore-0.2019.9.17.tar.gz"
            }
        ],
        "0.2019.9.17.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "7f05a1d5924b210b2f1defcca16564e4",
                    "sha256": "2eecd8f5a7c938a712f8d6426967a886f19fd1af92decbf36e8f36b71c6dbb48"
                },
                "downloads": -1,
                "filename": "jk_keyvaluestore-0.2019.9.17.1.tar.gz",
                "has_sig": false,
                "md5_digest": "7f05a1d5924b210b2f1defcca16564e4",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 10861,
                "upload_time": "2019-09-17T09:33:02",
                "url": "https://files.pythonhosted.org/packages/5f/2f/cc0b8acd017cc414b8e2c3cc6c48fe317e18d29f8db94316acf70cce4580/jk_keyvaluestore-0.2019.9.17.1.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "7f05a1d5924b210b2f1defcca16564e4",
                "sha256": "2eecd8f5a7c938a712f8d6426967a886f19fd1af92decbf36e8f36b71c6dbb48"
            },
            "downloads": -1,
            "filename": "jk_keyvaluestore-0.2019.9.17.1.tar.gz",
            "has_sig": false,
            "md5_digest": "7f05a1d5924b210b2f1defcca16564e4",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 10861,
            "upload_time": "2019-09-17T09:33:02",
            "url": "https://files.pythonhosted.org/packages/5f/2f/cc0b8acd017cc414b8e2c3cc6c48fe317e18d29f8db94316acf70cce4580/jk_keyvaluestore-0.2019.9.17.1.tar.gz"
        }
    ]
}