encommon 0.10.0__py3-none-any.whl → 0.11.1__py3-none-any.whl

encommon/times/timers.py

@@ -7,82 +7,98 @@ is permitted, for more information consult the project license file.
 
 
 
+from copy import deepcopy
 from sqlite3 import Connection
 from sqlite3 import connect as SQLite
 from typing import Optional
+from typing import TYPE_CHECKING
 
-from .common import NUMERIC
 from .common import PARSABLE
+from .timer import Timer
 from .times import Times
 
+if TYPE_CHECKING:
+    from .params import TimerParams
+    from .params import TimersParams
+
 
 
 CACHE_TABLE = (
     """
     create table if not exists
      {0} (
+      "group" text not null,
       "unique" text not null,
       "update" text not null,
-     primary key ("unique"));
+     primary key (
+      "group", "unique"));
     """)  # noqa: LIT003
 
 
 
-_TIMERS = dict[str, float]
-_CACHED = dict[str, Times]
+TIMERS = dict[str, Timer]
 
 
 
 class Timers:
     """
-    Track timers on unique key and determine when to proceed.
+    Track timers on unique key determining when to proceed.
 
     .. warning::
        This class will use an in-memory database for cache,
        unless a cache file is explicity defined.
 
     .. testsetup::
+       >>> from .params import TimerParams
+       >>> from .params import TimersParams
        >>> from time import sleep
 
     Example
     -------
-    >>> timers = Timers({'one': 1})
+    >>> source = {'one': TimerParams(timer=1)}
+    >>> params = TimersParams(timers=source)
+    >>> timers = Timers(params)
     >>> timers.ready('one')
     False
     >>> sleep(1)
     >>> timers.ready('one')
     True
 
-    :param timers: Seconds that are used for each of timers.
-    :param file: Optional path to SQLite database for
-        cache. This will allow for use between executions.
-    :param table: Optional override default table name.
+    :param params: Parameters for instantiating the instance.
+    :param file: Optional path to file for SQLite database,
+        allowing for state retention between the executions.
+    :param table: Optional override for default table name.
+    :param group: Optional override for default group name.
     """
 
-    __config: _TIMERS
+    __params: 'TimersParams'
+
     __sqlite: Connection
     __file: str
     __table: str
-    __cache: _CACHED
+    __group: str
+
+    __timers: TIMERS
 
 
     def __init__(
         self,
-        timers: Optional[dict[str, NUMERIC]] = None,
+        params: Optional['TimersParams'] = None,
+        *,
         file: str = ':memory:',
         table: str = 'timers',
+        group: str = 'default',
     ) -> None:
         """
         Initialize instance for class using provided parameters.
         """
 
+        from .params import TimersParams
 
-        timers = dict(timers or {})
+        if params is None:
+            params = TimersParams()
 
-        items = timers.items()
-
-        for key, value in items:
-            timers[key] = float(value)
+        self.__params = deepcopy(params)
 
 
         sqlite = SQLite(file)
@@ -93,113 +109,71 @@ class Timers:
 
         sqlite.commit()
 
-
-        cached: _CACHED = {}
-
-        for timer in timers:
-            cached[timer] = Times()
-
-
-        self.__config = timers
         self.__sqlite = sqlite
         self.__file = file
         self.__table = table
-        self.__cache = cached
+        self.__group = group
+
 
+        self.__timers = {}
 
-        self.load_cache()
-        self.save_cache()
+        self.load_children()
 
 
-    def load_cache(
+    @property
+    def params(
         self,
-    ) -> None:
+    ) -> 'TimersParams':
         """
-        Load the timers cache from the database into attribute.
-        """
-
-        cached = self.__sqlite
-        table = self.__table
-        cachem = self.__cache
-
-        cursor = cached.execute(
-            f'select * from {table}'
-            ' order by "unique" asc')
+        Return the Pydantic model containing the configuration.
 
-        records = cursor.fetchall()
-
-        for record in records:
-
-            unique = record[0]
-            update = record[1]
-
-            times = Times(update)
+        :returns: Pydantic model containing the configuration.
+        """
 
-            cachem[unique] = times
+        return self.__params
 
 
-    def save_cache(
+    @property
+    def sqlite(
         self,
-    ) -> None:
-        """
-        Save the timers cache from the attribute into database.
+    ) -> Connection:
         """
+        Return the value for the attribute from class instance.
 
-        insert = tuple[str, str]
-        inserts: list[insert] = []
-
-
-        cached = self.__sqlite
-        table = self.__table
-        cachem = self.__cache
-
-
-        items = cachem.items()
-
-        for key, value in items:
-
-            append = (key, str(value))
-
-            inserts.append(append)
-
-
-        cached.executemany(
-            (f'replace into {table}'
-             ' ("unique", "update")'
-             ' values (?, ?)'),
-            tuple(sorted(inserts)))
+        :returns: Value for the attribute from class instance.
+        """
 
-        cached.commit()
+        return self.__sqlite
 
 
     @property
-    def timers(
+    def file(
         self,
-    ) -> _TIMERS:
+    ) -> str:
         """
         Return the value for the attribute from class instance.
 
         :returns: Value for the attribute from class instance.
         """
 
-        return dict(self.__config)
+        return self.__file
 
 
     @property
-    def sqlite(
+    def table(
         self,
-    ) -> Connection:
+    ) -> str:
         """
         Return the value for the attribute from class instance.
 
         :returns: Value for the attribute from class instance.
         """
 
-        return self.__sqlite
+        return self.__table
 
 
     @property
-    def file(
+    def group(
         self,
     ) -> str:
         """
@@ -208,33 +182,130 @@ class Timers:
         :returns: Value for the attribute from class instance.
         """
 
-        return self.__file
+        return self.__group
 
 
     @property
-    def table(
+    def children(
         self,
-    ) -> str:
+    ) -> dict[str, Timer]:
         """
         Return the value for the attribute from class instance.
 
         :returns: Value for the attribute from class instance.
         """
 
-        return self.__table
+        return dict(self.__timers)
 
 
-    @property
-    def cache(
+    def load_children(
         self,
-    ) -> _CACHED:
+    ) -> None:
+        """
+        Construct the children instances for the primary class.
         """
-        Return the value for the attribute from class instance.
 
-        :returns: Value for the attribute from class instance.
+        params = self.__params
+        timers = self.__timers
+
+        sqlite = self.__sqlite
+        table = self.__table
+        group = self.__group
+
+
+        config = params.timers
+
+
+        cursor = sqlite.execute(
+            f"""
+            select * from {table}
+            where "group"="{group}"
+            order by "unique" asc
+            """)  # noqa: LIT003
+
+        records = cursor.fetchall()
+
+        for record in records:
+
+            unique = record[1]
+            update = record[2]
+
+            if unique not in config:
+                continue
+
+            _config = config[unique]
+
+            _config.start = update
+
+
+        items = config.items()
+
+        for key, value in items:
+
+            if key in timers:
+
+                timer = timers[key]
+
+                timer.update(
+                    value.start)
+
+                continue
+
+            timer = Timer(
+                value.timer,
+                start=value.start)
+
+            timers[key] = timer
+
+
+        self.__timers = timers
+
+
+    def save_children(
+        self,
+    ) -> None:
+        """
+        Save the child caches from the attribute into database.
         """
 
-        return dict(self.__cache)
+        timers = self.__timers
+
+        sqlite = self.__sqlite
+        table = self.__table
+        group = self.__group
+
+
+        insert = tuple[
+            str,  # group
+            str,  # unique
+            str]  # update
+
+        inserts: list[insert] = []
+
+        items = timers.items()
+
+        for unique, timer in items:
+
+            append = (
+                group, unique,
+                Times('now').subsec)
+
+            inserts.append(append)
+
+
+        statement = (
+            f"""
+            replace into {table}
+            ("group", "unique",
+             "update")
+            values (?, ?, ?)
+            """)  # noqa: LIT003
+
+        sqlite.executemany(
+            statement,
+            tuple(sorted(inserts)))
+
+        sqlite.commit()
 
 
     def ready(
@@ -245,74 +316,90 @@ class Timers:
         """
         Determine whether or not the appropriate time has passed.
 
-        .. note::
-           For performance reasons, this method will not notice
-           changes within the database unless refreshed first.
-
-        :param unique: Which timer configuration from reference.
+        :param unique: Unique identifier for the related child.
         :param update: Determines whether or not time is updated.
+        :returns: Boolean indicating whether enough time passed.
         """
 
-        config = self.__config
-        caches = self.__cache
+        timers = self.__timers
 
-        if unique not in caches:
+        if unique not in timers:
             raise ValueError('unique')
 
-        cache = caches[unique]
-        timer = config[unique]
+        timer = timers[unique]
 
-        ready = cache.since >= timer
+        ready = timer.ready(update)
 
-        if ready and update:
-            self.update(unique)
+        if ready is True:
+            self.save_children()
 
         return ready
 
 
+    def create(
+        self,
+        unique: str,
+        params: 'TimerParams',
+    ) -> Timer:
+        """
+        Create a new timer using the provided input parameters.
+
+        :param unique: Unique identifier for the related child.
+        :param params: Parameters for instantiating the instance.
+        :returns: Newly constructed instance of related class.
+        """
+
+        timers = self.params.timers
+
+        if unique in timers:
+            raise ValueError('unique')
+
+        timers[unique] = params
+
+        self.load_children()
+
+        self.save_children()
+
+        return self.children[unique]
+
+
     def update(
         self,
         unique: str,
-        started: Optional[PARSABLE] = None,
+        value: Optional[PARSABLE] = None,
     ) -> None:
         """
-        Update the existing timer from mapping within the cache.
+        Update the timer from the provided parasable time value.
 
-        :param unique: Which timer configuration from reference.
-        :param started: Override the start time for timer value.
+        :param unique: Unique identifier for the related child.
+        :param value: Override the time updated for timer value.
         """
 
-        caches = self.__cache
+        timers = self.__timers
 
-        if unique not in caches:
+        if unique not in timers:
             raise ValueError('unique')
 
-        caches[unique] = Times(started)
+        timer = timers[unique]
 
-        self.save_cache()
+        self.save_children()
 
+        return timer.update(value)
 
-    def create(
+
+    def delete(
         self,
         unique: str,
-        minimum: int | float,
-        started: Optional[PARSABLE] = None,
     ) -> None:
         """
-        Update the existing timer from mapping within the cache.
+        Delete the timer from the internal dictionary reference.
 
-        :param unique: Which timer configuration from reference.
-        :param minimum: Determine minimum seconds that must pass.
-        :param started: Determine when time starts for the timer.
+        :param unique: Unique identifier for the related child.
         """
 
-        config = self.__config
-        caches = self.__cache
+        timers = self.__timers
 
-        if unique in config:
+        if unique not in timers:
             raise ValueError('unique')
 
-        config[unique] = float(minimum)
-        caches[unique] = Times(started)
-
-        self.save_cache()
+        del timers[unique]

encommon/times/times.py

@@ -16,10 +16,10 @@ from .common import PARSABLE
 from .common import STAMP_HUMAN
 from .common import STAMP_SIMPLE
 from .common import STAMP_SUBSEC
-from .common import findtz
-from .common import strftime
 from .parse import parse_time
 from .parse import since_time
+from .utils import findtz
+from .utils import strftime
 
 
 
@@ -348,9 +348,9 @@ class Times:
         self,
     ) -> float:
         """
-        Determine the time in seconds that occured since instance.
+        Determine the time in seconds occurring since instance.
 
-        :returns: Time in seconds that occured between the values.
+        :returns: Time in seconds occurring since the instance.
         """
 
         return since_time(self.__source)
@@ -361,9 +361,9 @@ class Times:
         self,
     ) -> float:
         """
-        Determine the time in seconds that occured since instance.
+        Determine the time in seconds occurring since instance.
 
-        :returns: Time in seconds that occured between the values.
+        :returns: Time in seconds occurring since the instance.
         """
 
         return since_time(self.__source)

encommon/times/utils.py

@@ -0,0 +1,148 @@
+"""
+Functions and routines associated with Enasis Network Common Library.
+
+This file is part of Enasis Network software eco-system. Distribution
+is permitted, for more information consult the project license file.
+"""
+
+
+
+from contextlib import suppress
+from datetime import datetime
+from datetime import timezone
+from datetime import tzinfo
+from typing import Any
+from typing import Optional
+
+from dateutil.tz import gettz
+
+
+
+def findtz(
+    tzname: Optional[str] = None,
+) -> tzinfo:
+    """
+    Return the located timezone object for the provided name.
+
+    Example
+    -------
+    >>> findtz('US/Central')
+    tzfile('/usr/share/zoneinfo/US/Central')
+
+    :param tzname: Name of the timezone associated to source.
+    :returns: Located timezone object for the provided name.
+    """
+
+    if tzname is None:
+        return timezone.utc
+
+    tzinfo = gettz(tzname)
+
+    if tzinfo is None:
+        raise ValueError('tzname')
+
+    return tzinfo
+
+
+
+def utcdatetime(
+    *args: Any,
+    **kwargs: Any,
+) -> datetime:
+    """
+    Return the instance of datetime within the UTC timezone.
+
+    .. warning::
+       If no arguments are provided, returns current time.
+
+    Example
+    -------
+    >>> utcdatetime(1970, 1, 1)
+    datetime.datetime(1970, 1, 1, 0...
+
+    :param args: Positional arguments passed for downstream.
+    :param kwargs: Keyword arguments passed for downstream.
+    :returns: Instance of datetime within the UTC timezone.
+    """
+
+    tzinfo = timezone.utc
+
+    if not args and not kwargs:
+        return datetime.now(tz=tzinfo)
+
+    if 'tzinfo' not in kwargs:
+        kwargs['tzinfo'] = tzinfo
+
+    return (
+        datetime(*args, **kwargs)
+        .astimezone(timezone.utc))
+
+
+
+def strptime(
+    source: str,
+    formats: str | list[str],
+) -> datetime:
+    """
+    Parse provided time value with various supported formats.
+
+    Example
+    -------
+    >>> strptime('2023', '%Y')
+    datetime.datetime(2023, 1, 1, 0...
+
+    :param source: Time in various forms that will be parsed.
+    :param formats: Various formats compatable with strptime.
+    :returns: Python datetime object containing related time.
+    """
+
+    tzinfo = timezone.utc
+
+    if isinstance(formats, str):
+        formats = [formats]
+
+
+    def _strptime(
+        format: str,
+    ) -> datetime:
+
+        return (
+            datetime
+            .strptime(source, format)
+            .astimezone(tzinfo))
+
+
+    for format in formats:
+
+        with suppress(ValueError):
+            return _strptime(format)
+
+
+    raise ValueError('invalid')
+
+
+
+def strftime(
+    source: datetime,
+    format: str,
+) -> str:
+    """
+    Return the timestamp string for datetime object provided.
+
+    .. note::
+       This function is extremely pedantic and cosmetic.
+
+    Example
+    -------
+    >>> dtime = datetime(2023, 1, 1)
+    >>> strftime(dtime, '%Y')
+    '2023'
+
+    :param source: Python datetime instance containing source.
+    :param format: Format for the timestamp string returned.
+    :returns: Timestamp string for datetime object provided.
+    """
+
+    return (
+        datetime
+        .strftime(source, format))