<h1 align="center">
<a href="https://github.com/ayaanhossain/ShareDB/">
<img src="https://raw.githubusercontent.com/ayaanhossain/ShareDB/master/logo/logo.svg?sanitize=true" alt="ShareDB" width="260" class="center"/>
</a>
</h1>
<p align="center">
<a href="https://github.com/ayaanhossain/ShareDB/actions">
<img src="https://github.com/ayaanhossain/ShareDB/workflows/build/badge.svg"
alt="CI-badge">
</a>
<a href="https://codecov.io/gh/ayaanhossain/ShareDB">
<img src="https://codecov.io/gh/ayaanhossain/ShareDB/branch/master/graph/badge.svg?token=syTKRG9H8O"
alt="codecov-badge">
</a>
<a href="https://pypi.org/project/ShareDB/">
<img src="https://img.shields.io/pypi/v/ShareDB"
alt="version-badge">
</a>
<a href="https://pypi.org/project/ShareDB/">
<img src="https://img.shields.io/pypi/pyversions/ShareDB"
alt="python-badge">
</a>
<a href="https://img.shields.io/badge/os-Linux-9cf">
<img src="https://img.shields.io/badge/os-Linux-9cf"
alt="os-badge">
</a>
<a href="./LICENSE">
<img src="https://img.shields.io/pypi/l/ShareDB"
alt="license-badge">
</a>
</p>
<p align="center">
<a href="#sharedb-in-action">ShareDB in Action</a> •
<a href="#installation">Installation</a> •
<a href="#license">License</a> •
<a href="#contributing">Contributing</a> •
<a href="#acknowledgements">Acknowledgements</a> •
<a href="https://github.com/ayaanhossain/ShareDB/blob/master/docs/API.md">API</a>
</p>
`ShareDB` is a lightweight, **persistent key-value store** with a **dictionary-like interface** built on top of [LMDB](https://symas.com/lmdb/). It is intended to replace a python dictionary when
1. the key-value information needs to **persist locally** for later reuse,
2. the data needs to be **shared across multiple processes** with minimal overhead, and
3. the **keys** and **values** can be (de)serialized via **msgpack** or **pickle**.
A `ShareDB` instance may be opened simultaneously in children, for reading in parallel, as long as a single process writes to the instance. **Parallel writes made across processes are not safe**; they are not guaranteed to be written, and may corrupt instance. `ShareDB` is primarily developed and tested using **Linux** and is compatible with both **Python 2.7 and Python 3.6 and above**.
### `ShareDB` in Action
```python
>>> from ShareDB import ShareDB # Easy import
>>> print(ShareDB.__version__) # Check version
1.1.4
>>> myDB = ShareDB(path='./test.ShareDB') # Store ShareDB locally
>>> myDB['Name'] = ['Ayaan Hossain'] # Insert information
>>> myDB.get(key='Name') # Retrieve values
['Ayaan Hossain']
>>> # Accelerated batch insertion/update via a single transaction
>>> len(myDB.multiset(kv_iter=zip(range(0, 10), range(10, 20))).sync())
11
>>> 7 in myDB # Membership queries work
True
>>> myDB['non-existent key'] # KeyError on invalid get as expected
Traceback (most recent call last):
...
KeyError: "key=non-existent key of <class 'str'> is absent"
>>> myDB.pop(7) # Pop a key just like a dictionary
17
>>> list(myDB.multipopitem(num_items=5)) # Or, pop as many items as you need
[(0, 10), (1, 11), (2, 12), (3, 13), (4, 14)]
>>> myDB.remove(5).remove(6).length() # Chain removal of several keys
2
>>> myDB.clear().length() # Or, clear entire ShareDB
0
>>> myDB.drop() # Close/delete when you're done
True
```
`ShareDB` methods either return data/result up on appropriate query, or a `self` is returned to facilitate method chaining. Terminal methods `.close()` and `.drop()` return a boolean indicating success.
Please see the `/examples/` directory for full examples of `ShareDB` usage. Please see the [API.md](./docs/API.md) file for API details.
### Installation
One-shot **installation/upgrade** of `ShareDB` from **PyPI**.
```bash
$ pip install --upgrade ShareDB
```
Alternatively, **clone** `ShareDB` from **GitHub**,
```bash
$ git clone https://github.com/ayaanhossain/ShareDB
```
navigate into repo, and install via `pip`.
```bash
$ cd ShareDB
$ pip install .
```
You can **test** `ShareDB` with **pytest** inside the `/tests/` directory.
```bash
$ cd tests
$ pytest
```
**Uninstallation** of `ShareDB` is easy with `pip`.
```bash
$ pip uninstall ShareDB
```
### License
`ShareDB` (c) 2019-2024 Ayaan Hossain.
`ShareDB` is an **open-source software** under [MIT](https://opensource.org/licenses/MIT) License.
See [LICENSE](./LICENSE) file for more details.
### Contributing
Please **discuss** any issues/bugs you're facing, or any changes/features you have in mind by **opening an issue**, following the [Contributor Covenant](https://www.contributor-covenant.org/version/2/0/code_of_conduct). See [COC.md](./docs/COC.md) file for details. Please provide detailed **information**, and code **snippets** to facilitate debugging.
To contribute to `ShareDB`, please **clone** this repository, **commit** your code on a **separate new branch**, and **submit** a **pull request**. Please annotate and describe all **new** and **modified code** with detailed **comments** and **new unit tests** as applicable. Please ensure that modified builds **pass existing unit tests** before sending pull-requests. For versioning, we use [SemVer](https://semver.org/).
### Acknowledgements
`ShareDB` is maintained by:
- Ayaan Hossain | [github.com/ayaanhossain](https://github.com/ayaanhossain) | [@bioalgorithmist](https://twitter.com/bioalgorithmist)
`ShareDB` was originally written to meet data analysis needs in [Prof. Howard Salis](https://twitter.com/hsalis)' Lab at [Penn State University](https://salislab.net/).
### API
`ShareDB` API details can be found in the [API.md](./docs/API.md) file.
Raw data
{
"_id": null,
"home_page": "https://github.com/ayaanhossain/ShareDB",
"name": "ShareDB",
"maintainer": null,
"docs_url": null,
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,<4,>=2.7",
"maintainer_email": null,
"keywords": "lmdb embedded key value store parallel data share read multiprocessing db",
"author": "Ayaan Hossain",
"author_email": "auh57@psu.edu",
"download_url": "https://files.pythonhosted.org/packages/31/97/9d216646af712196761f5cdfc34220885809478a8f91b199aad9c549c69b/sharedb-1.1.4.tar.gz",
"platform": null,
"description": "\ufeff<h1 align=\"center\">\n <a href=\"https://github.com/ayaanhossain/ShareDB/\">\n <img src=\"https://raw.githubusercontent.com/ayaanhossain/ShareDB/master/logo/logo.svg?sanitize=true\" alt=\"ShareDB\" width=\"260\" class=\"center\"/>\n </a>\n</h1>\n\n<p align=\"center\">\n\t<a href=\"https://github.com/ayaanhossain/ShareDB/actions\">\n\t <img src=\"https://github.com/ayaanhossain/ShareDB/workflows/build/badge.svg\"\n\t alt=\"CI-badge\">\n </a>\n\t<a href=\"https://codecov.io/gh/ayaanhossain/ShareDB\">\n\t\t<img src=\"https://codecov.io/gh/ayaanhossain/ShareDB/branch/master/graph/badge.svg?token=syTKRG9H8O\"\n\t\t alt=\"codecov-badge\">\n </a>\n\t<a href=\"https://pypi.org/project/ShareDB/\">\n\t\t<img src=\"https://img.shields.io/pypi/v/ShareDB\"\n\t\t alt=\"version-badge\">\n\t</a>\n\t<a href=\"https://pypi.org/project/ShareDB/\">\n\t <img src=\"https://img.shields.io/pypi/pyversions/ShareDB\"\n\t alt=\"python-badge\">\n </a>\n <a href=\"https://img.shields.io/badge/os-Linux-9cf\">\n\t <img src=\"https://img.shields.io/badge/os-Linux-9cf\"\n\t alt=\"os-badge\">\n </a>\n\t<a href=\"./LICENSE\">\n\t <img src=\"https://img.shields.io/pypi/l/ShareDB\"\n\t alt=\"license-badge\">\n </a>\n</p>\n\n<p align=\"center\">\n <a href=\"#sharedb-in-action\">ShareDB in Action</a> \u2022\n <a href=\"#installation\">Installation</a> \u2022\n <a href=\"#license\">License</a> \u2022\n <a href=\"#contributing\">Contributing</a> \u2022\n <a href=\"#acknowledgements\">Acknowledgements</a> \u2022\n <a href=\"https://github.com/ayaanhossain/ShareDB/blob/master/docs/API.md\">API</a>\n</p>\n\n`ShareDB` is a lightweight, **persistent key-value store** with a **dictionary-like interface** built on top of [LMDB](https://symas.com/lmdb/). It is intended to replace a python dictionary when\n\n 1. the key-value information needs to **persist locally** for later reuse,\n 2. the data needs to be **shared across multiple processes** with minimal overhead, and\n 3. the **keys** and **values** can be (de)serialized via **msgpack** or **pickle**.\n\nA `ShareDB` instance may be opened simultaneously in children, for reading in parallel, as long as a single process writes to the instance. **Parallel writes made across processes are not safe**; they are not guaranteed to be written, and may corrupt instance. `ShareDB` is primarily developed and tested using **Linux** and is compatible with both **Python 2.7 and Python 3.6 and above**.\n\n### `ShareDB` in Action\n```python\n>>> from ShareDB import ShareDB # Easy import\n>>> print(ShareDB.__version__) # Check version\n1.1.4\n>>> myDB = ShareDB(path='./test.ShareDB') # Store ShareDB locally\n>>> myDB['Name'] = ['Ayaan Hossain'] # Insert information\n>>> myDB.get(key='Name') # Retrieve values\n['Ayaan Hossain']\n>>> # Accelerated batch insertion/update via a single transaction\n>>> len(myDB.multiset(kv_iter=zip(range(0, 10), range(10, 20))).sync())\n11\n>>> 7 in myDB # Membership queries work\nTrue\n>>> myDB['non-existent key'] # KeyError on invalid get as expected\nTraceback (most recent call last):\n...\nKeyError: \"key=non-existent key of <class 'str'> is absent\"\n>>> myDB.pop(7) # Pop a key just like a dictionary\n17\n>>> list(myDB.multipopitem(num_items=5)) # Or, pop as many items as you need\n[(0, 10), (1, 11), (2, 12), (3, 13), (4, 14)]\n>>> myDB.remove(5).remove(6).length() # Chain removal of several keys\n2\n>>> myDB.clear().length() # Or, clear entire ShareDB\n0\n>>> myDB.drop() # Close/delete when you're done\nTrue\n```\n`ShareDB` methods either return data/result up on appropriate query, or a `self` is returned to facilitate method chaining. Terminal methods `.close()` and `.drop()` return a boolean indicating success.\n\nPlease see the `/examples/` directory for full examples of `ShareDB` usage. Please see the [API.md](./docs/API.md) file for API details.\n\n### Installation\nOne-shot **installation/upgrade** of `ShareDB` from **PyPI**.\n```bash\n$ pip install --upgrade ShareDB\n```\nAlternatively, **clone** `ShareDB` from **GitHub**,\n```bash\n$ git clone https://github.com/ayaanhossain/ShareDB\n```\nnavigate into repo, and install via `pip`.\n```bash\n$ cd ShareDB\n$ pip install .\n```\nYou can **test** `ShareDB` with **pytest** inside the `/tests/` directory.\n```bash\n$ cd tests\n$ pytest\n```\n**Uninstallation** of `ShareDB` is easy with `pip`.\n```bash\n$ pip uninstall ShareDB\n```\n\n### License\n`ShareDB` (c) 2019-2024 Ayaan Hossain.\n\n`ShareDB` is an **open-source software** under [MIT](https://opensource.org/licenses/MIT) License.\n\nSee [LICENSE](./LICENSE) file for more details.\n\n### Contributing\nPlease **discuss** any issues/bugs you're facing, or any changes/features you have in mind by **opening an issue**, following the [Contributor Covenant](https://www.contributor-covenant.org/version/2/0/code_of_conduct). See [COC.md](./docs/COC.md) file for details. Please provide detailed **information**, and code **snippets** to facilitate debugging.\n\nTo contribute to `ShareDB`, please **clone** this repository, **commit** your code on a **separate new branch**, and **submit** a **pull request**. Please annotate and describe all **new** and **modified code** with detailed **comments** and **new unit tests** as applicable. Please ensure that modified builds **pass existing unit tests** before sending pull-requests. For versioning, we use [SemVer](https://semver.org/).\n\n### Acknowledgements\n`ShareDB` is maintained by:\n\n - Ayaan Hossain | [github.com/ayaanhossain](https://github.com/ayaanhossain) | [@bioalgorithmist](https://twitter.com/bioalgorithmist)\n\n`ShareDB` was originally written to meet data analysis needs in [Prof. Howard Salis](https://twitter.com/hsalis)' Lab at [Penn State University](https://salislab.net/).\n\n### API\n`ShareDB` API details can be found in the [API.md](./docs/API.md) file.\n",
"bugtrack_url": null,
"license": null,
"summary": "An on-disk pythonic embedded key-value store for compressed data storage and distributed data analysis.",
"version": "1.1.4",
"project_urls": {
"Bug Reports": "https://github.com/ayaanhossain/ShareDB/issues",
"Homepage": "https://github.com/ayaanhossain/ShareDB",
"Source": "https://github.com/ayaanhossain/ShareDB/"
},
"split_keywords": [
"lmdb",
"embedded",
"key",
"value",
"store",
"parallel",
"data",
"share",
"read",
"multiprocessing",
"db"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e7e97321af0d25afab09fcc82f7908fdf8f0df104b3882d9a699b7eb477e9f70",
"md5": "eabe6a2b1301d18fc3d6d362f69dddf7",
"sha256": "1ffdaa0c9cf1aa43590a9f91ad0fb1deb1ba86293a95bbe3b5c14ad603f6e0d7"
},
"downloads": -1,
"filename": "ShareDB-1.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "eabe6a2b1301d18fc3d6d362f69dddf7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,<4,>=2.7",
"size": 13891,
"upload_time": "2024-11-04T22:11:46",
"upload_time_iso_8601": "2024-11-04T22:11:46.409948Z",
"url": "https://files.pythonhosted.org/packages/e7/e9/7321af0d25afab09fcc82f7908fdf8f0df104b3882d9a699b7eb477e9f70/ShareDB-1.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "31979d216646af712196761f5cdfc34220885809478a8f91b199aad9c549c69b",
"md5": "5b440b5b661b9a241affeb0e881c601a",
"sha256": "e300dfdf1dafa9802b675d9216171cafdc94682fe7b9b2be85199792c84709c7"
},
"downloads": -1,
"filename": "sharedb-1.1.4.tar.gz",
"has_sig": false,
"md5_digest": "5b440b5b661b9a241affeb0e881c601a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "!=3.0.*,!=3.1.*,!=3.2.*,!=3.3.*,!=3.4.*,!=3.5.*,<4,>=2.7",
"size": 19205,
"upload_time": "2024-11-04T22:11:47",
"upload_time_iso_8601": "2024-11-04T22:11:47.566593Z",
"url": "https://files.pythonhosted.org/packages/31/97/9d216646af712196761f5cdfc34220885809478a8f91b199aad9c549c69b/sharedb-1.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-04 22:11:47",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "ayaanhossain",
"github_project": "ShareDB",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "lmdb",
"specs": [
[
">=",
"0.98"
]
]
},
{
"name": "msgpack",
"specs": [
[
">=",
"0.6.2"
]
]
},
{
"name": "configparser",
"specs": [
[
">=",
"4.0.2"
]
]
},
{
"name": "pytest-cov",
"specs": [
[
">=",
"2.8.1"
]
]
}
],
"lcname": "sharedb"
}
JSON
