Updated docs.

diff --git a/persistent.py b/persistent.py
index 4c18c23f43be7b60fb2198158b7647bf12c8e1b2..ecf39c40be7e578f8d5d3b29835058074594416d 100644 (file)
--- a/persistent.py
+++ b/persistent.py
@@ -44,7 +44,7 @@ def reuse_if_mtime_is_today() -> Callable[[datetime.datetime], bool]:
     )
 
 
-def reuse_if_mtime_less_than_limit(
+def reuse_if_mtime_less_than_limit_sec(
         limit_seconds: int
 ) -> Callable[[datetime.datetime], bool]:
     """
@@ -82,8 +82,8 @@ class persistent_autoload_singleton(Persistent):
 
         @persistent_autoload_singleton(
             filename = "my_cache_file.bin",
-            may_reuse_persisted = reuse_if_mtime_less_than_limit(60),
-            persist_at_shutdown = False
+            may_reuse_persisted = reuse_if_mtime_less_than_limit_sec(60),
+            persist_at_shutdown = PersistAtShutdown.IF_NOT_INITIALIZED_FROM_DISK,
         )
         class MyComplexObject(object):
             def __init__(self, ...):
@@ -101,17 +101,20 @@ class persistent_autoload_singleton(Persistent):
            it exists and any may_reuse_persisted predicate indicates
            that reusing persisted state is allowed, we will skip the
            call to __init__ and return an unpickled instance read from
-           the disk file.
+           the disk file.  In the example above the predicate allows
+           reuse of saved state if it is <= 60s old.
         3. If the file doesn't exist or the predicate indicates that
-           the persisted state cannot be reused, MyComplexObject's
-           __init__ will be invoked and will be expected to fully
-           initialize the instance.
+           the persisted state cannot be reused (e.g. too stale),
+           MyComplexObject's __init__ will be invoked and will be
+           expected to fully initialize the instance.
         4. At program exit time, depending on the value of the
            persist_at_shutdown parameter, the state of MyComplexObject
            will be written to disk using the same filename so that
            future instances may potentially reuse saved state.  Note
            that the state that is persisted is the state at program
-           exit time.
+           exit time.  In the example above this parameter indicates
+           that we should persist state so long as we were not
+           initialized from cached state on disk.
 
     """
     def __init__(