+ """This class is meant to be used as a decorator around a class that:
+
+ 1. Is a singleton; one global instance per python program.
+ 2. Has a complex state that is initialized fully by __init__()
+ 3. Would benefit from caching said state on disk and reloading
+ it on future invokations rather than recomputing and
+ reinitializing.
+
+ Here's and example usage pattern:
+
+ @persistent_autoload_singleton(
+ filename = "my_cache_file.bin",
+ may_reuse_persisted = reuse_if_mtime_less_than_limit(60),
+ persist_at_shutdown = False
+ )
+ class MyComplexObject(object):
+ def __init__(self, ...):
+ # do a bunch of work to fully initialize this instance
+
+ def another_method(self, ...):
+ # use the state stored in this instance to do some work
+
+ What does this do, exactly?
+
+ 1. Anytime you attempt to instantiate MyComplexObject you will
+ get the same instance. This class is now a singleton.
+ 2. The first time you attempt to instantiate MyComplexObject
+ the wrapper scaffolding will check "my_cache_file.bin". If
+ 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.
+ 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.
+ 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.
+
+ """
+ def __init__(
+ self,
+ filename: str,
+ *,
+ may_reuse_persisted: Optional[Callable[[datetime.datetime], bool]] = None,
+ persist_at_shutdown: PersistAtShutdown = PersistAtShutdown.NEVER):