updated readme and formatting

README.md

@@ -6,6 +6,41 @@ As the name implies, this is merely a simple key-value store for Python.
 
 Not counting comments and tests, it is less than 100 lines of code.
 
-It doesn't do anything crazy. It just takes json serializable data and writes it to disk.
+It doesn't do anything crazy. It just takes json serializable data and stores it to disk.
 
-You can control where and when to read/write, and that's it.
+You can control when and where to read/write, and that's it.
+
+No bloat, only 3 public methods.
+
+## Usage
+
+### Install: 
+
+`python3 setup.py install`
+
+### Create the KV instance:
+
+~~~
+# If the file already exists, it will load the json data from it
+kv = deadsimplekv.DeadSimpleKV('/path/to/file')
+~~~
+
+You can specify how often to refresh and flush to file by passing `flush_seconds` and `refresh_seconds` respectively.
+
+### Get and set values:
+
+~~~
+# Automatically reads/writes to disk every time unless no file was specified.
+# Set flush_seconds or refresh_seconds to None to disable automatic read/write.
+# Set them to >0 values to automatically read/write if time has elapsed. 
+kv.put('my_key', True)
+kv.get('my_key') # returns True.
+~~~
+
+### Delete a key/value pair:
+
+~~~
+kv.delete('my_key')
+~~~
+
+***Warning:*** **Be sure to manually flush when destroying the kv instance (such as by exiting your program) to avoid losing data, as flushes only happen when .put has been called.**

deadsimplekv/__init__.py

@@ -18,6 +18,9 @@
 import json, time, math, os
 
 def _is_serializable(data):
+    '''
+        Test if something is able to be in JSON format
+    '''
     try:
         json.dumps(data)
         return True
@@ -47,6 +50,9 @@ class DeadSimpleKV:
             pass
     
     def get(self, key):
+        '''
+            Accepts key, which must be json serializable
+        '''
         self._do_auto_refresh()
         try:
             return self._data[key]
@@ -54,8 +60,9 @@ class DeadSimpleKV:
             return None
         
     def put(self, key, value):
-        '''Value setter. Will automatically flush if auto_flush is True and file_path is not None
+        '''
-        Will return value error if either key or value are not JSON serializable
+            Value setter. Will automatically flush if auto_flush is True and file_path is not None
+            Will return value error if either key or value are not JSON serializable
         '''
         self._data[key] = value # Set the key
 
@@ -68,12 +75,16 @@ class DeadSimpleKV:
         return (key, value)
     
     def delete(self, key):
-        '''Deletes value. Will automatically flush if auto_flush is True and file_path is not None'''
+        '''
+            Deletes value. Will automatically flush if auto_flush is True and file_path is not None
+        '''
         del self._data[key]
         self._do_auto_flush()
 
     def refresh(self):
-        '''Refresh data and then mark time read. Can be manually called'''
+        '''
+            Refresh data and then mark time read. Can be manually called
+        '''
         try:
             self._data = json.loads(DeadSimpleKV._read_in(self.file_path))
         except FileNotFoundError:
@@ -81,7 +92,9 @@ class DeadSimpleKV:
         self._last_refresh = DeadSimpleKV._get_epoch()
 
     def flush(self):
-        '''Write out then mark time flushed. Can be manually called'''
+        '''
+            Write out then mark time flushed. Can be manually called
+        '''
         DeadSimpleKV._write_out(self.file_path, json.dumps(self._data))
         self._last_flush = DeadSimpleKV._get_epoch()
     
@@ -92,8 +105,8 @@ class DeadSimpleKV:
                 self.flush()
     
     def _do_auto_refresh(self):
+        # Automatically flush if it is enabled and time to do so
         if self.refresh_seconds is not None and self.file_path is not None:
-            # refresh if automatic and time to do so
             if DeadSimpleKV._get_epoch() - self._last_refresh >= self.refresh_seconds:
                 self.refresh()