{"id":13504358,"url":"https://github.com/tuxmonk/pupdb","last_synced_at":"2025-03-29T21:30:32.100Z","repository":{"id":62578289,"uuid":"223895357","full_name":"tuxmonk/pupdb","owner":"tuxmonk","description":"A simple file-based key-value database written in Python","archived":false,"fork":false,"pushed_at":"2023-05-01T21:03:30.000Z","size":67,"stargazers_count":87,"open_issues_count":7,"forks_count":6,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-03-19T17:43:34.633Z","etag":null,"topics":["cross-language","database","file-based","key-value-store","process-safe","python","rest-api"],"latest_commit_sha":null,"homepage":null,"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/tuxmonk.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2019-11-25T08:13:16.000Z","updated_at":"2025-02-08T06:33:37.000Z","dependencies_parsed_at":"2022-11-03T19:29:33.748Z","dependency_job_id":"2ab430e5-41f8-46a1-ba79-55f294584e51","html_url":"https://github.com/tuxmonk/pupdb","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/tuxmonk%2Fpupdb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuxmonk%2Fpupdb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuxmonk%2Fpupdb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tuxmonk%2Fpupdb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tuxmonk","download_url":"https://codeload.github.com/tuxmonk/pupdb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246249110,"owners_count":20747164,"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":["cross-language","database","file-based","key-value-store","process-safe","python","rest-api"],"created_at":"2024-08-01T00:00:35.226Z","updated_at":"2025-03-29T21:30:31.839Z","avatar_url":"https://github.com/tuxmonk.png","language":"Python","funding_links":[],"categories":["Databases"],"sub_categories":["Key-Value Databases"],"readme":"\u003cimg src=\"https://raw.githubusercontent.com/tuxmonk/pupdb/master/logo.png\" alt=\"PupDB Logo\" width=\"400\"/\u003e\n\n[![Build Status](https://travis-ci.org/tuxmonk/pupdb.svg?branch=master)](https://travis-ci.org/tuxmonk/pupdb) [![codecov](https://codecov.io/gh/tuxmonk/pupdb/branch/master/graph/badge.svg)](https://codecov.io/gh/tuxmonk/pupdb) [![PyPI version fury.io](https://badge.fury.io/py/pupdb.svg)](https://pypi.python.org/pypi/pupdb/) [![Supported Python Versions](https://img.shields.io/pypi/pyversions/pupdb.svg)](https://pypi.python.org/pypi/pupdb/)\n\n## What is it?\n\nPupDB is an ernest attempt to create a simple file-based key-value database written in Python.\n\n## Why PupDB?\n\nThe objective behind the creation of PupDB is to create a database system which performs simple persistence operations well and data can be accessed with a minimalist, easy-to-use API with least configuration.\n\n### PupDB is the best choice when:\n\n1. You need a simple NoSQL data store with an interface as simple as a Python `dict`, and want to start storing and retrieving data within a few minutes.\n2. You want to create an application without bothering much about configuration and setup for storing data.\n3. Your database is not very huge i.e. not greater than a few megabytes of data.\n\n### When not to use PupDB:\n\n1. You want to perform advanced queries on your data.\n2. Your database is larger than a few megabytes of data.\n3. You want a database software that supports advanced capabilities like indexing, partitioning etc.\n\n## Salient Features\n\n1. **Multi-processing support**: Same database file can be used across multiple processes concurrently.\n2. **Mult-threading support**: Same database file (with separate `PupDB` instance per thread) can be used concurrently.\n3. **REST-based HTTP Interface**: Apart from using it as a `python` package, you can also use PupDB via a `flask`-based HTTP interface. This way you can use PupDB with programming languages other than Python.\n\n## Installation\n\nPupDB can be installed using `pip`:\n\n```bash\npip install pupdb\n```\n\n## Basic API Documentation and Usage\n\nPupDB can be instantiated as follows:\n```python\nfrom pupdb.core import PupDB\n\n# Specify database file path as an argument to the PupDB constructor. That's it.\ndb = PupDB('db.json')\n```\n\n1. `set(key, value)`: Stores the `value` mapped to `key` in the database file.\n```python\ndb.set('test_key', 'test_value')\n```\n2. `get(key)`: Returns the `value` mapped to `key` in the database file. Returns `None` if `key` is not found.\n```python\ndb.get('test_key')\n```\n3. `remove(key)`: Removes the `key` from the database file. Raises a `KeyError` if `key` is not found in the database file.\n```python\n# Remove the key `test_key` from the db.\ndb.remove('test_key')\n\n# Try doing the same again and it'll raise a `KeyError`,\n# as the key has already been deleted from the db in the above step.\ndb.remove('test_key')\n```\n4. `keys()`: Returns the keys present in the database file. Return type is `list` in Python 2 and [Dictionary view object](https://docs.python.org/3.8/library/stdtypes.html?highlight=keys#dict-views) (similar to [`dict.keys()`](https://docs.python.org/3.8/library/stdtypes.html?highlight=keys#dict.keys)) in Python 3.\n```python\n# Python 2\nprint db.keys() # This will print ['key1', ...]\n\n# Python 3\nprint(list(db.keys())) # This will print ['key1', ...]\n```\n5. `values()`: Returns the values of all keys present in the database file. Return type is `list` for Python 2 and [Dictionary view object](https://docs.python.org/3.8/library/stdtypes.html?highlight=keys#dict-views) (similar to [`dict.values()`](https://docs.python.org/3.8/library/stdtypes.html?highlight=keys#dict.values)) in Python 3.\n```python\n# Python 2\nprint db.values() # This will print ['value1', ...]\n\n# Python 3\nprint(list(db.values())) # This will print ['value1', ...]\n```\n6. `items()`: Returns the values of all keys present in the database file. Return type is `list` for Python 2 and [Dictionary view object](https://docs.python.org/3.8/library/stdtypes.html?highlight=keys#dict-views) (similar to [`dict.items()`](https://docs.python.org/3.8/library/stdtypes.html?highlight=keys#dict.items)) in Python 3.\n```python\n# Python 2\nprint db.items() # This will print [('key1', 'value1'), ...]\n\n# Python 3\nprint(list(db.items())) # This will print [('key1', 'value1'), ...]\n```\n7. `dumps()`: Returns a `json` dump of the entire database file sorted by key.\n```python\ndb.dumps() # This will print the database json string.\n```\n8. `truncate_db()`: Removes all data from the database file i.e. truncates the database file.\n```python\ndb.truncate_db()\nprint(db) # Will print an empty database dict '{}', as the database has been truncated.\n```\n\n## Using the PupDB HTTP/REST Interface\n\n**Using the HTTP/REST Interface, all PupDB-related operations can be performed without using PupDB as a Python package. As a result, PupDB can be used in any programming language that can make HTTP requests.**\n\nTo start PupDB's `gunicorn`-based `flask` server:\n\n```python\nfrom pupdb.server import start_http_server\n\n# Start the gunicorn server (with 4 worker threads).\nstart_http_server()\n```\n\nThe server will listen to local port 4000. The server will be available at `http://localhost:4000`.\n\n### HTTP API Endpoints\n\n1. `/get?key=\u003ckey-goes-here\u003e` (Method: `GET`): This API endpoint is an interface to PupDB's `get()` method. e.g.:\n\n```bash\ncurl -XGET http://localhost:4000/get?key=test\n```\n\nThe above `curl` request will fetch the result for key `test`.\n\n2. `/set` (Method: `POST`): This API endpoint is an interface to PupDB's `set()` method. e.g.:\n\n```bash\ncurl -XPOST http://localhost:4000/set -H 'Content-Type: application/json' -d '{\"key\": \"test\", \"value\": \"1234\"}'\n```\n\nThe above `curl` request will set the value `1234` to key `test` in the database.\n\n3. `/remove/\u003ckey-goes-here\u003e` (Method: `DELETE`): This API endpoint is an interface to PupDB's `remove()` method. e.g.:\n\n```bash\ncurl -XDELETE http://localhost:4000/remove/test\n```\n\nThe above `curl` request will remove the key `test` in the database. It returns a `404 Not Found` if the key does not exist in the database.\n\n4. `/keys` (Method: `GET`): This API endpoint is an interface to PupDB's `keys()` method. e.g.:\n\n```bash\ncurl -XGET http://localhost:4000/keys\n```\n\nThe above `curl` request will return a payload containing the `list` of keys in the database.\n\n5. `/values` (Method: `GET`): This API endpoint is an interface to PupDB's `values()` method. e.g.:\n\n```bash\ncurl -XGET http://localhost:4000/values\n```\n\nThe above `curl` request will return a payload containing the `list` of values of all keys in the database.\n\n6. `/items` (Method: `GET`): This API endpoint is an interface to PupDB's `items()` method. e.g.:\n\n```bash\ncurl -XGET http://localhost:4000/items\n```\n\nThe above `curl` request will return a payload containing the `list` of `[key, value]` pairs in the database.\n\n7. `/dumps` (Method: `GET`): This API endpoint is an interface to PupDB's `dumps()` method. e.g.:\n\n```bash\ncurl -XGET http://localhost:4000/dumps\n```\n\nThe above `curl` request will return a payload containing the string dump of the entire database.\n\n7. `/truncate-db` (Method: `POST`): This API endpoint is an interface to PupDB's `truncate_db()` method. e.g.:\n\n```bash\ncurl -XPOST http://localhost:4000/truncate-db\n```\n\nThe above `curl` request will truncate i.e. remove all key-value pairs from the database.\n\n## Versioning\n\nWe use [SemVer](http://semver.org/) for versioning. For the versions available,\nsee the\n[tags on this repository](https://github.com/tuxmonk/pupdb/tags).\n\n## License\n\nThis project is licensed under the MIT License - see the\n[LICENSE.txt](https://github.com/tuxmonk/pupdb/blob/master/LICENSE.txt) file for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuxmonk%2Fpupdb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftuxmonk%2Fpupdb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftuxmonk%2Fpupdb/lists"}