X-Git-Url: https://wannabe.guru.org/gitweb/?a=blobdiff_plain;f=persistent.py;h=58014608f9a894fa40742249cd9c04933007d52e;hb=e46158e49121b8a955bb07b73f5bcf9928b79c90;hp=b42a5c0e3036a35d76dc0c8f32374d029e94fd53;hpb=f2901184ccb5415cf40b3ec61c128a6a59ab3aa7;p=python_utils.git diff --git a/persistent.py b/persistent.py index b42a5c0..5801460 100644 --- a/persistent.py +++ b/persistent.py @@ -2,8 +2,8 @@ # © Copyright 2021-2022, Scott Gasch -"""A Persistent is just a class with a load and save method. This -module defines the 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 @@ -22,30 +22,27 @@ logger = logging.getLogger(__name__) class Persistent(ABC): """ A base class of an object with a load/save method. Classes that are - decorated with @persistent_autoloaded_singleton should subclass this - and implement their save() and load() methods. - + decorated with :code:`@persistent_autoloaded_singleton` should subclass + this and implement their :meth:`save` and :meth:`load` methods. """ @abstractmethod def save(self) -> bool: """ Save this thing somewhere that you'll remember when someone calls - load() later on in a way that makes sense to your code. - + :meth:`load` later on in a way that makes sense to your code. """ pass @classmethod @abstractmethod def load(cls) -> Any: - """ - Load this thing from somewhere and give back an instance which - will become the global singleton and which will may (see - below) be save()d at program exit time. + """Load this thing from somewhere and give back an instance which + will become the global singleton and which may (see + below) be saved (via :meth:`save`) at program exit time. - Oh, in case this is handy, here's how to write a factory - method that doesn't call the c'tor in python: + Oh, in case this is handy, here's a reminder how to write a + factory method that doesn't call the c'tor in python:: @classmethod def load_from_somewhere(cls, somewhere): @@ -58,13 +55,18 @@ class Persistent(ABC): # Load the piece(s) of obj that you want to from somewhere. obj._state = load_from_somewhere(somewhere) return obj - """ pass def was_file_written_today(filename: str) -> bool: - """Returns True if filename was written today. + """Convenience wrapper around :meth:`was_file_written_within_n_seconds`. + + Args: + filename: filename to check + + Returns: + True if filename was written today. >>> import os >>> filename = f'/tmp/testing_persistent_py_{os.getpid()}' @@ -95,8 +97,15 @@ def was_file_written_within_n_seconds( filename: str, limit_seconds: int, ) -> bool: - """Returns True if filename was written within the pas limit_seconds - seconds. + """Helper for determining persisted state staleness. + + Args: + filename: the filename to check + limit_seconds: how fresh, in seconds, it must be + + Returns: + True if filename was written within the past limit_seconds + or False otherwise (or on error). >>> import os >>> filename = f'/tmp/testing_persistent_py_{os.getpid()}' @@ -126,8 +135,14 @@ def was_file_written_within_n_seconds( class PersistAtShutdown(enum.Enum): """ An enum to describe the conditions under which state is persisted - to disk. See details below. - + 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` + 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 = (0,) @@ -136,23 +151,31 @@ class PersistAtShutdown(enum.Enum): class persistent_autoloaded_singleton(object): - """A decorator that can be applied to a Persistent subclass (i.e. a - class with a save() and load() method. It will intercept attempts - to instantiate the class via it's c'tor and, instead, invoke the - class' load() method to give it a chance to read state from - somewhere persistent. - - If load() fails (returns None), the c'tor is invoked with 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 + 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 original args as a fallback. - Based upon the value of the optional argument persist_at_shutdown, - (NEVER, IF_NOT_LOADED, ALWAYS), the save() method of the class will - be invoked just before program shutdown to give the class a chance - to save its state somewhere. - - The implementations of save() and load() and where the class - persists its state are details left to the Persistent - implementation. + 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 + 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` + 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 + persisted between runs. """