# © Copyright 2021-2022, Scott Gasch
-"""A :class:Persistent is just a class with a load and save method. This
-module defines the :class:Persistent base and a decorator that can be used to
+"""A :class:`Persistent` is just a class with a load and save method. This
+module defines the :class:`Persistent` base and a decorator that can be used to
create a persistent singleton that autoloads and autosaves."""
import atexit
def was_file_written_today(filename: str) -> bool:
- """Convenience wrapper around was_file_written_within_n_seconds.
+ """Convenience wrapper around :meth:`was_file_written_within_n_seconds`.
Args:
filename: filename to check
"""
An enum to describe the conditions under which state is persisted
to disk. This is passed as an argument to the decorator below and
- is used to indicate when to call :meth:save on a :class:Persistent
+ is used to indicate when to call :meth:`save` on a :class:`Persistent`
subclass.
- * NEVER: never call :meth:save
- * IF_NOT_LOADED: call :meth:save as long as we did not successfully
- :meth:load its state.
- * ALWAYS: always call :meth:save
+ * NEVER: never call :meth:`save`
+ * IF_NOT_LOADED: call :meth:`save` as long as we did not successfully
+ :meth:`load` its state.
+ * ALWAYS: always call :meth:`save`
"""
NEVER = (0,)
class persistent_autoloaded_singleton(object):
- """A decorator that can be applied to a :class:Persistent subclass
- (i.e. a class with :meth:save and :meth:load methods. The
+ """A decorator that can be applied to a :class:`Persistent` subclass
+ (i.e. a class with :meth:`save` and :meth:`load` methods. The
decorator will intercept attempts to instantiate the class via
- it's c'tor and, instead, invoke the class' :meth:load to give it a
+ it's c'tor and, instead, invoke the class' :meth:`load` to give it a
chance to read state from somewhere persistent (disk, db,
whatever). Subsequent calls to construt instances of the wrapped
class will return a single, global instance (i.e. the wrapped
class is a singleton).
- If :meth:load fails (returns None), the c'tor is invoked with the
+ If :meth:`load` fails (returns None), the c'tor is invoked with the
original args as a fallback.
Based upon the value of the optional argument
:code:`persist_at_shutdown` argument, (NEVER, IF_NOT_LOADED,
- ALWAYS), the :meth:save method of the class will be invoked just
+ ALWAYS), the :meth:`save` method of the class will be invoked just
before program shutdown to give the class a chance to save its
state somewhere.
.. note::
- The implementations of :meth:save and :meth:load and where the
- class persists its state are details left to the :class:Persistent
+ The implementations of :meth:`save` and :meth:`load` and where the
+ class persists its state are details left to the :class:`Persistent`
implementation. Essentially this decorator just handles the
plumbing of calling your save/load and appropriate times and
creates a transparent global singleton whose state can be