Repository files navigation

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.

1. You need a simple NoSQL data store with an interface as simple as a Pythondict, and want to start storing and retrieving data within a few minutes.
2. You want to create an application without bothering much about configuration and setup for storing data.
3. Your database is not very huge i.e. not greater than a few megabytes of data.

1. You want to perform advanced queries on your data.
2. Your database is larger than a few megabytes of data.
3. You want a database software that supports advanced capabilities like indexing, partitioning etc.

1. Multi-processing support: Same database file can be used across multiple processes concurrently.
2. Mult-threading support: Same database file (with separatePupDB instance per thread) can be used concurrently.
3. REST-based HTTP Interface: Apart from using it as apython package, you can also use PupDB via aflask-based HTTP interface. This way you can use PupDB with programming languages other than Python.

PupDB can be installed usingpip:

pip install pupdb

PupDB can be instantiated as follows:

frompupdb.coreimportPupDB# Specify database file path as an argument to the PupDB constructor. That's it.db=PupDB('db.json')

1. set(key, value): Stores thevalue mapped tokey in the database file.

db.set('test_key','test_value')

2. get(key): Returns thevalue mapped tokey in the database file. ReturnsNone ifkey is not found.

db.get('test_key')

3. remove(key): Removes thekey from the database file. Raises aKeyError ifkey 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')

4. keys(): Returns the keys present in the database file. Return type islist in Python 2 andDictionary view object (similar todict.keys()) in Python 3.

# Python 2printdb.keys()# This will print ['key1', ...]# Python 3print(list(db.keys()))# This will print ['key1', ...]

5. values(): Returns the values of all keys present in the database file. Return type islist for Python 2 andDictionary view object (similar todict.values()) in Python 3.

# Python 2printdb.values()# This will print ['value1', ...]# Python 3print(list(db.values()))# This will print ['value1', ...]

6. items(): Returns the values of all keys present in the database file. Return type islist for Python 2 andDictionary view object (similar todict.items()) in Python 3.

# Python 2printdb.items()# This will print [('key1', 'value1'), ...]# Python 3print(list(db.items()))# This will print [('key1', 'value1'), ...]

7. dumps(): Returns ajson dump of the entire database file sorted by key.

db.dumps()# This will print the database json string.

8. 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'sgunicorn-basedflask server:

frompupdb.serverimportstart_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 athttp://localhost:4000.

1. /get?key=<key-goes-here> (Method:GET): This API endpoint is an interface to PupDB'sget() method. e.g.:

curl -XGET http://localhost:4000/get?key=test

The abovecurl request will fetch the result for keytest.

2. /set (Method:POST): This API endpoint is an interface to PupDB'sset() method. e.g.:

curl -XPOST http://localhost:4000/set -H'Content-Type: application/json' -d'{"key": "test", "value": "1234"}'

The abovecurl request will set the value1234 to keytest in the database.

3. /remove/<key-goes-here> (Method:DELETE): This API endpoint is an interface to PupDB'sremove() method. e.g.:

curl -XDELETE http://localhost:4000/remove/test

The abovecurl request will remove the keytest in the database. It returns a404 Not Found if the key does not exist in the database.

4. /keys (Method:GET): This API endpoint is an interface to PupDB'skeys() method. e.g.:

curl -XGET http://localhost:4000/keys

The abovecurl request will return a payload containing thelist of keys in the database.

5. /values (Method:GET): This API endpoint is an interface to PupDB'svalues() method. e.g.:

curl -XGET http://localhost:4000/values

The abovecurl request will return a payload containing thelist of values of all keys in the database.

6. /items (Method:GET): This API endpoint is an interface to PupDB'sitems() method. e.g.:

curl -XGET http://localhost:4000/items

The abovecurl request will return a payload containing thelist of[key, value] pairs in the database.

7. /dumps (Method:GET): This API endpoint is an interface to PupDB'sdumps() method. e.g.:

curl -XGET http://localhost:4000/dumps

The abovecurl request will return a payload containing the string dump of the entire database.

7. /truncate-db (Method:POST): This API endpoint is an interface to PupDB'struncate_db() method. e.g.:

curl -XPOST http://localhost:4000/truncate-db

The abovecurl request will truncate i.e. remove all key-value pairs from the database.

We useSemVer for versioning. For the versions available,see thetags on this repository.

This project is licensed under the MIT License - see theLICENSE.txt file for more details.