bala0406/Simple-Store

A File-based key-value Data Store.

Simple Store

A File based key-value Data Store

Table of Contents

1. About The Project
   • Built With
   • Features
2. Getting Started
   • Installation
3. Usage
4. Acknowledgements

About The Project

A File based key-value data store that can be used in your project to store data in key value pairs in json file in your local machine. The Simple Store is very light weight and can be used in small or medium scale projects. If you don't want the data to be stored permanently, you can set the Time to live property which is a great feature. The data gets destroyed automatically after the expiration of the time to live property. The read and write operations are thread-safe, so you don't need to worry about concurrent access to the store. If you're on an UNIX machine you can also able to hide your data store file. The size of the value that can be stored for a single key is capped at 16KB for faster read and write. The file size is also capped at 1GB to have smaller size footprint on the local disk. So plan accordingly.

Built With

• Python 🚀

Features

• File stored as json 🎉
• Time to Live ⌛
• Thread safe 💪
• File hiding 🔐 (works only on UNIX based Operating Systems)
• Runs on all major Operating Systems 💻 (mac, linux, windows)

Getting Started

To get a local copy up and running follow these simple steps.

Installation

1. Clone the repo

   git clone https://github.com/bala0406/Simple-Store.git

2. Install required packages in requirements.txt

   pip3 install -r requirements.txt

Usage

1. Copy the simple_store package folder into your project.

2. Import the SimpleStore class into your python file and get an instance of the store.

   from simple_store.simple_store import SimpleStore 
   
   # if you need only one instance, you can prefer using the getInstance() static method in the class
   db = SimpleStore.getInstance()
   
   # if you need more than one instance, you can go with normal object creation for the class
   db = SimpleStore()

3. You can optionally set custom directory, file name and hidden property to the data store file. It's completely fine to skip this step and the data store file will be created in your current project directory with a default file name SimpleStore with file hiding defaulted to False.

   # isHidden property is defaulted to false
   db.setPath(path="your path goes here", fileName="enter your fileName here")
   
   # create file with default path 
   db.setPath(fileName="enter your fileName here") 
   
   # create file with default file name
   db.setPath(path="your path goes here")
   
   # hide file
   # NOTE: the file hiding only works on UNIX machines and isHidden parameter will be ignored on windows.
   db.setPath(path="your path goes here", fileName="enter your fileName here", isHidden=True) 

4. Create data in store.

    # the key is a string and value is a dict object that will be converted to json
    dummyDict = {} # your dict
    db.create(key="enter your key here", value=dummyDict)
   
    # the default time to live value is 0 which means None.
    # create data with time to live property
    db.create(key="enter your key here", value=dummyDict,timeToLiveInSeconds=10)

5. Read data from store.

    # it takes key as the parameter and returns the dict object converted from json object
    result = db.read(key="enter your key here")
    print(result)

6. Delete data in store.

    # it takes key as the parameter 
    db.delete(key="enter your key here")

   NOTE : The value will be mostly operated on dict object for wider compatibility within python and will be converted to json on storing the value to the data store. The operation is vice versa for reading.

Acknowledgements

• filelock 🔒