More Readme improvements.

1 files changed, 20 insertions, 7 deletions

diff --git a/README.txt b/README.txt
index 3f90dc9..4eb2384 100644
--- a/README.txt
+++ b/README.txt
@@ -10,7 +10,7 @@ Introduction
 
 Pylru implements a true LRU cache along with several support classes. The cache is efficient and written in pure Python. It works with Python 2.6+ including the new 3.x series. Basic operations (lookup, insert, delete) all run in a constant amount of time.
 
-You can install pylru or you can just copy the source file pylru.py and use it in your own project.
+You can install pylru or you can just copy the source file pylru.py and use it in your own project. The rest of this file explains what the pylru module provides and how to use it. If you want to know more examine pylru.py. The code is straightforward and well commented.
 
 Usage
 =====
@@ -36,6 +36,8 @@ An lrucache object has a dictionary like interface and can be used in the same w
                         # Lookup and insert both move the key/value to the most
                         # recently used position. Delete (obviously) removes a
                         # key/value from whatever position it was in.
+                        #
+                        # WARNING - keys can't be None
                         
     key in cache        # Test for membership. Does not affect the cache order.
     
@@ -49,6 +51,7 @@ An lrucache object has a dictionary like interface and can be used in the same w
                         # cache.
                         #
                         # These calls have no effect on the cache order.
+                        # lrucache is scan resistant when these calls are used.
                         # The iterators iterate over their respective elements
                         # in the order of most recently used to least recently
                         # used.
@@ -91,9 +94,9 @@ Lrucache takes an optional callback function as a second argument. Since the cac
 WriteThroughCacheManager
 ========================
 
-Often a cache is used to speed up access to some other high latency object. For example, imagine you have a backend storage object that reads/writes from/to a remote server. Let us call this object *store*. If store has a dictionary interface a cache manager class can be used to compose the store object and an lrucache. The manager object exposes a dictionary interface. The programmer can then interact with the manager object as if it were the store. The manager object takes care of communicating with the store and cacheing key/value pair in the lrucache object.
+Often a cache is used to speed up access to some other high latency object. For example, imagine you have a backend storage object that reads/writes from/to a remote server. Let us call this object *store*. If store has a dictionary interface a cache manager class can be used to compose the store object and an lrucache. The manager object exposes a dictionary interface. The programmer can then interact with the manager object as if it were the store. The manager object takes care of communicating with the store and caching key/value pairs in the lrucache object.
 
-Two different semantics are supported, write-through (WriteThroughCacheManager class) and write-back (WriteBackCacheManager class). With write-through, lookups from the store are cached for future lookups, but insertion and deletions are updated in the cache and written through to the store immediately. Write-back works the same way, but insertion are updated only in the cache. These "dirty" key/value pair will only be update to the underlying store when they are ejected from the cache or when a sync is performed. The WriteBackCacheManager class is discussed more below. 
+Two different semantics are supported, write-through (WriteThroughCacheManager class) and write-back (WriteBackCacheManager class). With write-through, lookups from the store are cached for future lookups. Insertions and deletions are updated in the cache and written through to the store immediately. Write-back works the same way, but insertions are updated only in the cache. These "dirty" key/value pair will only be updated to the underlying store when they are ejected from the cache or when a sync is performed. The WriteBackCacheManager class is discussed more below. 
 
 The WriteThroughCacheManager class takes as arguments the store object you want to compose and the cache size. It then creates an LRU cache and automatically manages it::
 
@@ -104,12 +107,14 @@ The WriteThroughCacheManager class takes as arguments the store object you want
     cached = pylru.lruwrap(store, size)
                         # This is a factory function that does the same thing.
 
-    # Now the object *cached* can be used just like *store*, except cacheing is
+    # Now the object *cached* can be used just like store, except caching is
     # automatically handled.
     
     value = cached[key] # Lookup a value given its key.
     cached[key] = value # Insert a key/value pair.
     del cached[key]     # Delete a value given its key.
+                        #
+                        # WARNING - keys can't be None
     
     key in cache        # Test for membership. Does not affect the cache order.
 
@@ -144,6 +149,14 @@ Similar to the WriteThroughCacheManager class except write-back semantics are us
     cached = WriteBackCacheManager(store, size)
     cached = pylru.lruwrap(store, size, True)
                         # This is a factory function that does the same thing.
+                        
+    value = cached[key] # Lookup a value given its key.
+    cached[key] = value # Insert a key/value pair.
+    del cached[key]     # Delete a value given its key.
+                        #
+                        # WARNING - keys can't be None
+    
+    key in cache        # Test for membership. Does not affect the cache order.
 
                         
     cached.keys()       # Return an iterator over the keys in the cache/store
@@ -151,7 +164,7 @@ Similar to the WriteThroughCacheManager class except write-back semantics are us
     cached.items()      # Return an iterator over the (key, value) pairs in the
                         # cache/store.
                         #
-                        # The iterators iterate over a consistant view of the
+                        # The iterators iterate over a consistent view of the
                         # respective elements. That is, except for the order,
                         # the elements are the same as those returned if you
                         # first called sync() then called
@@ -176,7 +189,7 @@ Similar to the WriteThroughCacheManager class except write-back semantics are us
 
     cached.clear()      # Remove all items from the store and cache.
     
-    cached.sync()       # Make the store and cache consistant. Write all
+    cached.sync()       # Make the store and cache consistent. Write all
                         # cached changes to the store that have not been
                         # yet.
                         
@@ -187,7 +200,7 @@ To help the programmer ensure that the final sync() is called, WriteBackCacheMan
 
     with pylru.lruwrap(store, size, True) as cached:
         # Use cached just like you would store. sync() is called automatically
-        # called for you when leaving the with statement block.
+        # for you when leaving the with statement block.
 
 
 lrudecorator