{"id":16920456,"url":"https://github.com/ostafen/viperdb","last_synced_at":"2025-03-22T11:30:50.206Z","repository":{"id":57477472,"uuid":"458318617","full_name":"ostafen/viperdb","owner":"ostafen","description":"A tiny log-structured key-value database written in pure Python.","archived":false,"fork":false,"pushed_at":"2022-02-15T09:25:36.000Z","size":26,"stargazers_count":20,"open_issues_count":0,"forks_count":3,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-10T09:35:47.545Z","etag":null,"topics":["database","key-value-database","key-value-store","log-structured","python3","tiny"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ostafen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-02-11T19:40:23.000Z","updated_at":"2023-06-27T00:22:34.000Z","dependencies_parsed_at":"2022-08-30T17:11:26.709Z","dependency_job_id":null,"html_url":"https://github.com/ostafen/viperdb","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ostafen%2Fviperdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ostafen%2Fviperdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ostafen%2Fviperdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ostafen%2Fviperdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ostafen","download_url":"https://codeload.github.com/ostafen/viperdb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244207715,"owners_count":20416104,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["database","key-value-database","key-value-store","log-structured","python3","tiny"],"created_at":"2024-10-13T19:48:24.766Z","updated_at":"2025-03-22T11:30:49.769Z","avatar_url":"https://github.com/ostafen.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ViperDB :snake:\n\n[![codecov](https://codecov.io/gh/ostafen/viperdb/branch/main/graph/badge.svg?token=CXZTXRQ9YS)](https://codecov.io/gh/ostafen/viperdb)\n\nViperDB is a lightweight embedded key-value store written in pure Python. \nIt has been designed for being extremely simple while efficient.\n\n### Features\n\n- **tiny**: the main db file consists of just ~300 lines of code.\n- **highly coverage**: thanks to the small codebase, every single line of code is tested.\n- **log-structured**: ViperDB takes design concepts by log-structured databases such as [Bitcask](https://docs.riak.com/riak/kv/2.2.3/setup/planning/backend/bitcask/index.html).\n- **written in pure Python**: no external dependency needed.\n\n### Installation\n\n```bash\nfoo@bar:~$ pip3 install viperdb\n```\n\n### Python version\nViperDB has been tested with Python 3.8.\n\n### Database layout\n\nViperDB simply consists of two files: a **key log file** and a **value log file**.\nThe first is used to maintain information about values (e.g. offset, size, etc...) which are actually stored in the value log.\nThis layout allows to speed-up db initialization, which consists in loading the pointers to the entire key-space from the key-file to a dictionary. \nFor simplicity, the key file is treated as a text file, with each line containing a json-encoded entry.\nThe value file is viewed as a raw sequence of bytes. Before being written to the value file, each value is encoded according to the following scheme:\nbuiltin types (except for the **bytes** type) are json-encoded, while user-defined classes are pickled.\n\nTo keep logic simple, no automatic compaction is performed in the background: unused space must be reclaimed explicitly through the **reclaim** function.\n\n### API usage\n```python\nfrom viperdb import ViperDB\n\ndb = ViperDB('./db')\n# db can be used as a simple dictionary\ndb['hello'] = 'ViperDB!'\nassert db['hello'] == 'ViperDB'\n\ndel db['hello']\nassert 'hello' not in db\n\ndb.reclaim() # call this method periodically to free unused space.\ndb.close() # flush any pending write and close the database.\n```\n\n### Contribute\n\nViperDB is a very recent project. However, it is actively maintained to ensure high quality.\nIf you find any bug, or have some suggestion, feel free to contribute by opening a new issue or making a pull request.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fostafen%2Fviperdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fostafen%2Fviperdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fostafen%2Fviperdb/lists"}