What is it?
PupDB is an ernest attempt to create a simple file-based key-value database written in Python.
Why PupDB?
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.
PupDB is the best choice when:
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.
You want to create an application without bothering much about configuration and setup for storing data.
Your database is not very huge i.e. not greater than a few megabytes of data.
When not to use PupDB:
You want to perform advanced queries on your data.
Your database is larger than a few megabytes of data.
You want a database software that supports advanced capabilities like indexing, partitioning etc.
Salient Features
Multi-processing support: Same database file can be used across multiple processes concurrently.
Mult-threading support: Same database file (with separate PupDB instance per thread) can be used concurrently.
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.
Installation
PupDB can be installed using pip:
pip install pupdb
Basic API Documentation and Usage
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 PupDB HTTP/REST Interface
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.
HTTP API Endpoints
/get?key= (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/ (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.
Versioning
We use SemVer for versioning. For the versions available, see the tags on this repository.
License
This project is licensed under the MIT License - see the LICENSE.txt file for more details.