Various little changes. Naming. Durations as arguments.

[python_utils.git] / persistent.py

diff --git a/persistent.py b/persistent.py
index 4c18c23f43be7b60fb2198158b7647bf12c8e1b2..0ba931521a8841968068a6c7d97eb78edd86f78c 100644 (file)
--- a/persistent.py
+++ b/persistent.py
@@ -31,7 +31,7 @@ class Persistent(ABC):
 def reuse_if_mtime_is_today() -> Callable[[datetime.datetime], bool]:
     """
     A helper that returns a lambda appropriate for use in the
-    persistent_autoload_singleton decorator's may_reuse_persisted
+    persistent_autoloaded_singleton decorator's may_reuse_persisted
     parameter that allows persisted state to be reused as long as it
     was persisted on the same day as the load.
 
@@ -44,12 +44,12 @@ 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]:
     """
     A helper that returns a lambda appropriate for use in the
-    persistent_autoload_singleton decorator's may_reuse_persisted
+    persistent_autoloaded_singleton decorator's may_reuse_persisted
     parameter that allows persisted state to be reused as long as it
     was persisted within the past limit_seconds.
 
@@ -58,6 +58,11 @@ def reuse_if_mtime_less_than_limit(
     return lambda dt: (now - dt).total_seconds() <= limit_seconds
 
 
+def dont_reuse_persisted_state_force_refresh(
+) -> Callable[[datetime.datetime], bool]:
+    return lambda dt: False
+
+
 class PersistAtShutdown(enum.Enum):
     """
     An enum to describe the conditions under which state is persisted
@@ -69,7 +74,7 @@ class PersistAtShutdown(enum.Enum):
     ALWAYS = 2,
 
 
-class persistent_autoload_singleton(Persistent):
+class persistent_autoloaded_singleton(Persistent):
     """This class is meant to be used as a decorator around a class that:
 
         1. Is a singleton; one global instance per python program.
@@ -80,10 +85,10 @@ class persistent_autoload_singleton(Persistent):
 
     Here's and example usage pattern:
 
-        @persistent_autoload_singleton(
+        @persistent_autoloaded_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 +106,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__(