A simple file-based key-value database written in Python
PupDB is an ernest attempt to create a simple file-based key-value database written in Python.
The 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.
dict
, and want to start storing and retrieving data within a few minutes.PupDB
instance per thread) can be used concurrently.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.PupDB can be installed using pip
:
pip install pupdb
PupDB can be instantiated as follows:
from pupdb.core import PupDB
# Specify database file path as an argument to the PupDB constructor. That's it.
db = PupDB('db.json')
set(key, value)
: Stores the value
mapped to key
in the database file.db.set('test_key', 'test_value')
get(key)
: Returns the value
mapped to key
in the database file. Returns None
if key
is not found.db.get('test_key')
remove(key)
: Removes the key
from the database file. Raises a KeyError
if key
is not found in the database file.# Remove the key `test_key` from the db.
db.remove('test_key')
# Try doing the same again and it'll raise a `KeyError`,
# as the key has already been deleted from the db in the above step.
db.remove('test_key')
keys()
: Returns the keys present in the database file. Return type is list
in Python 2 and Dictionary view object (similar to dict.keys()
) in Python 3.# Python 2
print db.keys() # This will print ['key1', ...]
# Python 3
print(list(db.keys())) # This will print ['key1', ...]
values()
: Returns the values of all keys present in the database file. Return type is list
for Python 2 and Dictionary view object (similar to dict.values()
) in Python 3.# Python 2
print db.values() # This will print ['value1', ...]
# Python 3
print(list(db.values())) # This will print ['value1', ...]
items()
: Returns the values of all keys present in the database file. Return type is list
for Python 2 and Dictionary view object (similar to dict.items()
) in Python 3.# Python 2
print db.items() # This will print [('key1', 'value1'), ...]
# Python 3
print(list(db.items())) # This will print [('key1', 'value1'), ...]
dumps()
: Returns a json
dump of the entire database file sorted by key.db.dumps() # This will print the database json string.
truncate_db()
: Removes all data from the database file i.e. truncates the database file.db.truncate_db()
print(db) # Will print an empty database dict '{}', as the database has been truncated.
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.
To start PupDB's gunicorn
-based flask
server:
from pupdb.server import start_http_server
# Start the gunicorn server (with 4 worker threads).
start_http_server()
The server will listen to local port 4000. The server will be available at http://localhost:4000
.
/get?key=<key-goes-here>
(Method: GET
): This API endpoint is an interface to PupDB's get()
method. e.g.:curl -XGET http://localhost:4000/get?key=test
The above curl
request will fetch the result for key test
.
/set
(Method: POST
): This API endpoint is an interface to PupDB's set()
method. e.g.:curl -XPOST http://localhost:4000/set -H 'Content-Type: application/json' -d '{"key": "test", "value": "1234"}'
The above curl
request will set the value 1234
to key test
in the database.
/remove/<key-goes-here>
(Method: DELETE
): This API endpoint is an interface to PupDB's remove()
method. e.g.:curl -XDELETE http://localhost:4000/remove/test
The 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.
/keys
(Method: GET
): This API endpoint is an interface to PupDB's keys()
method. e.g.:curl -XGET http://localhost:4000/keys
The above curl
request will return a payload containing the list
of keys in the database.
/values
(Method: GET
): This API endpoint is an interface to PupDB's values()
method. e.g.:curl -XGET http://localhost:4000/values
The above curl
request will return a payload containing the list
of values of all keys in the database.
/items
(Method: GET
): This API endpoint is an interface to PupDB's items()
method. e.g.:curl -XGET http://localhost:4000/items
The above curl
request will return a payload containing the list
of [key, value]
pairs in the database.
/dumps
(Method: GET
): This API endpoint is an interface to PupDB's dumps()
method. e.g.:curl -XGET http://localhost:4000/dumps
The above curl
request will return a payload containing the string dump of the entire database.
/truncate-db
(Method: POST
): This API endpoint is an interface to PupDB's truncate_db()
method. e.g.:curl -XPOST http://localhost:4000/truncate-db
The above curl
request will truncate i.e. remove all key-value pairs from the database.
We use SemVer for versioning. For the versions available, see the tags on this repository.
This project is licensed under the MIT License - see the LICENSE.txt file for more details.