From 5e1bced276766fec9d4c408790c99d4a26d267e0 Mon Sep 17 00:00:00 2001
From: Scott Gasch <scott@gasch.org>
Date: Wed, 22 Sep 2021 17:37:17 -0700
Subject: [PATCH] Various little changes.  Naming.  Durations as arguments.

---
 argparse_utils.py | 22 ++++++++++++++++++++++
 datetime_utils.py | 24 ++++++++++++++++++++++++
 persistent.py     | 13 +++++++++----
 3 files changed, 55 insertions(+), 4 deletions(-)

diff --git a/argparse_utils.py b/argparse_utils.py
index 0ee2be9..2d2297c 100644
--- a/argparse_utils.py
+++ b/argparse_utils.py
@@ -232,6 +232,28 @@ def valid_datetime(txt: str) -> datetime.datetime:
     raise argparse.ArgumentTypeError(msg)
 
 
+def valid_duration(txt: str) -> datetime.timedelta:
+    """If the string is a valid time duration, return a
+    datetime.timedelta representing the period of time.  Otherwise
+    maybe raise an ArgumentTypeError or potentially just treat the
+    time window as zero in length.
+
+    >>> valid_duration('3m')
+    datetime.timedelta(seconds=180)
+
+    >>> valid_duration('your mom')
+    datetime.timedelta(seconds=0)
+
+    """
+    from datetime_utils import parse_duration
+    try:
+        secs = parse_duration(txt)
+    except Exception as e:
+        raise argparse.ArgumentTypeError(e)
+    finally:
+        return datetime.timedelta(seconds=secs)
+
+
 if __name__ == '__main__':
     import doctest
     doctest.ELLIPSIS_MARKER = '-ANYTHING-'
diff --git a/datetime_utils.py b/datetime_utils.py
index db5b2b5..c100057 100644
--- a/datetime_utils.py
+++ b/datetime_utils.py
@@ -652,6 +652,18 @@ def describe_duration(seconds: int, *, include_seconds = False) -> str:
     return descr
 
 
+def describe_timedelta(delta: datetime.timedelta) -> str:
+    """
+    Describe a duration represented by a timedelta object.
+
+    >>> d = datetime.timedelta(1, 600)
+    >>> describe_timedelta(d)
+    '1 day, and 10 minutes'
+
+    """
+    return describe_duration(delta.total_seconds())
+
+
 def describe_duration_briefly(seconds: int, *, include_seconds=False) -> str:
     """
     Describe a duration briefly.
@@ -685,6 +697,18 @@ def describe_duration_briefly(seconds: int, *, include_seconds=False) -> str:
     return descr.strip()
 
 
+def describe_timedelta_briefly(delta: datetime.timedelta) -> str:
+    """
+    Describe a duration represented by a timedelta object.
+
+    >>> d = datetime.timedelta(1, 600)
+    >>> describe_timedelta_briefly(d)
+    '1d 10m'
+
+    """
+    return describe_duration_briefly(delta.total_seconds())
+
+
 if __name__ == '__main__':
     import doctest
     doctest.testmod()
diff --git a/persistent.py b/persistent.py
index ecf39c4..0ba9315 100644
--- 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.
 
@@ -49,7 +49,7 @@ def reuse_if_mtime_less_than_limit_sec(
 ) -> 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_sec(
     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,7 +85,7 @@ 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_sec(60),
             persist_at_shutdown = PersistAtShutdown.IF_NOT_INITIALIZED_FROM_DISK,
-- 
2.45.2