Islet
==================================
Introduction
------------
Islet is a pure python key-value file database. It allows for multiple serializers for both the keys and values. The API is designed to use all of the same python dictionary methods python programmers are used to in addition to the typical dbm methods.
Installation
------------
Install via pip::
pip install islet
Or conda::
conda install -c mullenkamp islet
I'll probably put it on conda-forge once I feel like it's up to an appropriate standard...
Serialization
-----------------------------
Both the keys and values stored in Islet must be bytes when written to disk. This is the default when "open" is called. Islet allows for various serializers to be used for taking input keys and values and converting them to bytes. The in-build serializers include pickle, str, json, and orjson (if orjson is installed). If you want to serialize to json, then it is highly recommended to use orjson as it is substantially faster than the standard json python module.
The user can also pass custom serializers to the key_serializer and value_serializer parameters. These must have "dumps" and "loads" static methods. This allows the user to chain a serializer and a compressor together if desired.
Usage
-----
The docstrings have a lot of info about the classes and methods. Files should be opened with the islet.open function. Read the docstrings of the open function for more details.
Write data
~~~~~~~~~~
.. code:: python
import islet
with islet.open('test.book', 'n', value_serializer='pickle', key_serializer='str') as db:
db['test_key'] = ['one', 2, 'three', 4]
Read data
~~~~~~~~~
.. code:: python
with islet.open('test.book', 'r') as db:
test_data = db['test_key']
Notice that you don't need to pass serializer parameters when reading. Islet stores this info on the initial file creation.
Recommendations
~~~~~~~~~~~~~~~
In most cases, the user should use python's context manager "with" when reading and writing data. This will ensure data is properly written and (optionally) locks are released on the file. If the context manager is not used, then the user must be sure to run the db.sync() at the end of a series of writes to ensure the data has been fully written to disk. And as with other dbm style APIs, the db.close() must be run to close the file and release locks. MultiThreading is safe for multiple readers and writers, but only multiple readers are safe with MultiProcessing.
Benchmarks
-----------
Coming soon...
Raw data
{
"_id": null,
"home_page": "https://github.com/mullenkamp/islet",
"name": "islet",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "shelve dbm",
"author": "Mike Kittridge",
"author_email": "mullenkamp1@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/04/44/965e84fe4960deb1f8a7ad43d383e5f9d1ae188db2498431c44af4393744/islet-0.0.2.tar.gz",
"platform": null,
"description": "Islet\n==================================\n\nIntroduction\n------------\nIslet is a pure python key-value file database. It allows for multiple serializers for both the keys and values. The API is designed to use all of the same python dictionary methods python programmers are used to in addition to the typical dbm methods.\n\n\nInstallation\n------------\nInstall via pip::\n\n pip install islet\n\nOr conda::\n\n conda install -c mullenkamp islet\n\n\nI'll probably put it on conda-forge once I feel like it's up to an appropriate standard...\n\n\nSerialization\n-----------------------------\nBoth the keys and values stored in Islet must be bytes when written to disk. This is the default when \"open\" is called. Islet allows for various serializers to be used for taking input keys and values and converting them to bytes. The in-build serializers include pickle, str, json, and orjson (if orjson is installed). If you want to serialize to json, then it is highly recommended to use orjson as it is substantially faster than the standard json python module.\nThe user can also pass custom serializers to the key_serializer and value_serializer parameters. These must have \"dumps\" and \"loads\" static methods. This allows the user to chain a serializer and a compressor together if desired.\n\nUsage\n-----\nThe docstrings have a lot of info about the classes and methods. Files should be opened with the islet.open function. Read the docstrings of the open function for more details.\n\nWrite data\n~~~~~~~~~~\n.. code:: python\n\n import islet\n\n with islet.open('test.book', 'n', value_serializer='pickle', key_serializer='str') as db:\n db['test_key'] = ['one', 2, 'three', 4]\n\n\nRead data\n~~~~~~~~~\n.. code:: python\n\n with islet.open('test.book', 'r') as db:\n test_data = db['test_key']\n\nNotice that you don't need to pass serializer parameters when reading. Islet stores this info on the initial file creation.\n\nRecommendations\n~~~~~~~~~~~~~~~\nIn most cases, the user should use python's context manager \"with\" when reading and writing data. This will ensure data is properly written and (optionally) locks are released on the file. If the context manager is not used, then the user must be sure to run the db.sync() at the end of a series of writes to ensure the data has been fully written to disk. And as with other dbm style APIs, the db.close() must be run to close the file and release locks. MultiThreading is safe for multiple readers and writers, but only multiple readers are safe with MultiProcessing.\n\n\nBenchmarks\n-----------\nComing soon...\n",
"bugtrack_url": null,
"license": "Apache",
"summary": "A python key-value file database",
"version": "0.0.2",
"split_keywords": [
"shelve",
"dbm"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "27e5d02020671e7ed527dbefc520f6eeece35ad4ec3fdea70b3e9eeacd4350a1",
"md5": "e06b7acef6ee83d5f6a6f25066502bd0",
"sha256": "b4c07134ca510139eff5ad13f532c052c0169322ecc5e8c5a96173df2f55424e"
},
"downloads": -1,
"filename": "islet-0.0.2-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "e06b7acef6ee83d5f6a6f25066502bd0",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 15442,
"upload_time": "2023-01-11T04:37:08",
"upload_time_iso_8601": "2023-01-11T04:37:08.573082Z",
"url": "https://files.pythonhosted.org/packages/27/e5/d02020671e7ed527dbefc520f6eeece35ad4ec3fdea70b3e9eeacd4350a1/islet-0.0.2-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0444965e84fe4960deb1f8a7ad43d383e5f9d1ae188db2498431c44af4393744",
"md5": "7e2c4ea6cfa199bc35641fe0346c9ac3",
"sha256": "9b3e957ccfc5774624c3917d8ff01ea5a840b8534f9170e8e1a4c90ea8681d2b"
},
"downloads": -1,
"filename": "islet-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "7e2c4ea6cfa199bc35641fe0346c9ac3",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 18074,
"upload_time": "2023-01-11T04:37:10",
"upload_time_iso_8601": "2023-01-11T04:37:10.318357Z",
"url": "https://files.pythonhosted.org/packages/04/44/965e84fe4960deb1f8a7ad43d383e5f9d1ae188db2498431c44af4393744/islet-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-11 04:37:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "mullenkamp",
"github_project": "islet",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "islet"
}
JSON
