Skip to main content

A simple file-based key-value database written in Python.

Project description

PupDB Logo

Build Status codecov PyPI version fury.io Supported Python Versions

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:

  1. 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.
  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.

When not to use PupDB:

  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.

Salient Features

  1. Multi-processing support: Same database file can be used across multiple processes concurrently.
  2. Mult-threading support: Same database file (with separate PupDB instance per thread) can be used concurrently.
  3. 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')
  1. set(key, value): Stores the value mapped to key in the database file.
db.set('test_key', 'test_value')
  1. get(key): Returns the value mapped to key in the database file. Returns None if key is not found.
db.get('test_key')
  1. 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')
  1. 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', ...]
  1. 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', ...]
  1. 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'), ...]
  1. dumps(): Returns a json dump of the entire database file sorted by key.
db.dumps() # This will print the database json string.
  1. 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

  1. /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.

  1. /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.

  1. /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.

  1. /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.

  1. /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.

  1. /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.

  1. /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.

  1. /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.

Project details


Release history Release notifications

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for pupdb, version 0.1.4
Filename, size File type Python version Upload date Hashes
Filename, size pupdb-0.1.4.tar.gz (6.7 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page