clockwork 0.2.2__tar.gz → 0.3.1__tar.gz

{clockwork-0.2.2 → clockwork-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: clockwork
-Version: 0.2.2
+Version: 0.3.1
 Summary: Toolkit for time-related operations including scheduling, logging, date manipulation, and more.
 Home-page: https://github.com/zteinck/clockwork
 License: MIT
@@ -16,11 +16,9 @@ Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Dist: holidays
 Requires-Dist: numpy
-Requires-Dist: oddments
+Requires-Dist: oddments (>=0.3.0)
 Requires-Dist: pandas
-Requires-Dist: pathpilot
 Requires-Dist: schedule
-Requires-Dist: textwrap3
 Project-URL: Repository, https://github.com/zteinck/clockwork
 Description-Content-Type: text/markdown
 

clockwork-0.3.1/clockwork/__init__.py

@@ -0,0 +1,12 @@
+from .timestamp import Timestamp
+from .month_end import MonthEnd
+from .quarter_end import QuarterEnd
+from .decorators import action_timer
+
+from .utils import (
+    format_elapsed_seconds,
+    date_format_to_regex,
+    )
+
+__version__ = '0.3.1'
+__author__ = 'Zachary Einck <zacharyeinck@gmail.com>'

clockwork-0.3.1/clockwork/constants.py

@@ -0,0 +1 @@
+MONTHS_IN_YEAR = 12

clockwork-0.3.1/clockwork/decorators.py

@@ -0,0 +1,22 @@
+from functools import wraps
+from oddments import add_border
+import time
+
+from .utils import format_elapsed_seconds
+
+
+def action_timer(func):
+
+    @wraps(func)
+    def wrapper(*args, **kwargs):
+        start_time = time.time()
+        action = func.__name__
+        header = add_border(action, width=75, fixed_width=True)
+        print(header + '\n')
+        out = func(*args, **kwargs)
+        duration = format_elapsed_seconds(time.time() - start_time)
+        trailer = add_border(f'{action} complete in {duration}.')
+        print(trailer + '\n')
+        return out
+
+    return wrapper

clockwork-0.3.1/clockwork/month_end.py

@@ -0,0 +1,188 @@
+
+import datetime
+import oddments as odd
+
+from .timestamp import Timestamp
+from .constants import MONTHS_IN_YEAR
+
+
+class MonthEnd(Timestamp):
+    '''
+    Description
+    --------------------
+    Month end timestamp object.
+
+    Class Attributes
+    --------------------
+    _increment : int
+        Number of months to increment during offsets.
+
+    Instance Attributes
+    --------------------
+    ...
+    '''
+
+    #╭-------------------------------------------------------------------------╮
+    #| Class Attributes                                                        |
+    #╰-------------------------------------------------------------------------╯
+
+    _increment = 1
+
+
+    #╭-------------------------------------------------------------------------╮
+    #| Initialize Instance                                                     |
+    #╰-------------------------------------------------------------------------╯
+
+    def __init__(self, arg=None, **kwargs):
+        '''
+        Parameters
+        ------------
+        arg : None | any
+            A scalar value to be interpreted as a month end date. Must be None
+            if 'year' or 'month' are provided. Refer to '_to_datetime()' for
+            supported input formats.
+        year : int
+            The calendar year of the month end date.
+        month : int
+            The calendar month of the month end date (1 to 12).
+        offset : int
+            Number of months to shift from the base month end. Base month end
+            defaults to the most recently completed month end when no other
+            parameters are provided. Use positive values to move forward and
+            negative values to move backward in time.
+        kwargs : dict
+            Additional keyword arguments are forwarded to the Timestamp
+            constructor. Refer to its documentation for details.
+        '''
+        offset = self._try_int(kwargs.pop('offset', 0))
+        year, month = [kwargs.pop(k, None) for k in ['year','month']]
+        year_or_month = not (year is None and month is None)
+        has_arg = arg is not None
+
+        if has_arg:
+            if year_or_month:
+                raise ValueError(
+                    "Both 'year' and 'month' must be "
+                    "None when 'arg' is not None."
+                    )
+        else:
+            if year_or_month:
+                year, month = map(self._try_int, (year, month))
+                self._validate_month(month)
+            else:
+                now = datetime.datetime.now()
+                year = now.year
+                month = now.month - 1 # default to last month
+
+            year, month = self._offset(
+                year=year,
+                month=month,
+                offset=offset * self._increment
+                )
+
+            day = self.days_in_month(year, month)
+            arg = datetime.datetime(year, month, day)
+
+        super().__init__(arg, **kwargs)
+        self.validate_instance()
+
+        if has_arg and offset != 0:
+            self.offset(periods=offset, inplace=True)
+
+
+    #╭-------------------------------------------------------------------------╮
+    #| Properties                                                              |
+    #╰-------------------------------------------------------------------------╯
+
+    @property
+    def long_label(self):
+        return self.str('%Y-%m-%d')
+
+
+    @property
+    def compact_label(self):
+        return self.str('%Y-%m')
+
+
+    @property
+    def short_label(self):
+        return self.str('%b')
+
+
+    @property
+    def is_year_end(self):
+        return self.month == MONTHS_IN_YEAR
+
+
+    @property
+    def relative_offset(self):
+        '''
+        Description
+        ------------
+        Returns the number of periods the instance is offset relative to
+        the most recent period end. Periods are defined by the '_increment'
+        class attribute.
+
+        Returns
+        ------------
+        q : int
+            Number of offset periods.
+        '''
+        a, b = [
+            self._total_months(obj.year, obj.month)
+            for obj in (self, self.__class__(offset=0))
+            ]
+        q, r = divmod(a - b, self._increment)
+        if r == 0: return int(q)
+        raise ValueError(f"Unexpected remainder: {r}")
+
+
+    #╭-------------------------------------------------------------------------╮
+    #| Instance Methods                                                        |
+    #╰-------------------------------------------------------------------------╯
+
+    def offset(self, periods, inplace=False):
+        ''' offsets instance by desired number of periods '''
+        odd.validate_value(
+            value=periods,
+            attr='periods',
+            types=int
+            )
+
+        out = self.__class__(offset=self.relative_offset + periods)
+
+        if inplace:
+            self.dt = out.dt
+        else:
+            return out
+
+
+    def _offset(self, year, month, offset):
+        total_months = self._total_months(year, month + offset)
+        y, m = divmod(total_months, MONTHS_IN_YEAR)
+        return (y - 1, MONTHS_IN_YEAR) if m == 0 else (y, m)
+
+
+    def validate_instance(self):
+        ''' raises an error if the instance fails validation '''
+        error_msg = self._validate_instance()
+
+        if error_msg is not None:
+            raise ValueError(
+                f"Failed to initialize a {self.__class__.__name__} "
+                f"instance because the {error_msg}. "
+                )
+
+
+    def _validate_instance(self):
+        if not self.is_last_day_of_month:
+            return (
+                f"day ({self.day}) is not the last day "
+                f"({self.last_day_of_month}) of {self.month_name} {self.year}"
+                )
+
+        if not self.is_normalized:
+            return (
+                "date must have no time component. Use "
+                "'normalize=True' when creating the date"
+                )

clockwork-0.3.1/clockwork/quarter_end.py

@@ -0,0 +1,244 @@
+import oddments as odd
+import pandas as pd
+import datetime
+import re
+
+from .month_end import MonthEnd
+from .constants import MONTHS_IN_YEAR
+
+
+class QuarterEnd(MonthEnd):
+    '''
+    Description
+    --------------------
+    Quarter end timestamp object.
+
+    Class Attributes
+    --------------------
+    scheme : tuple
+        Quarter end months.
+
+    Instance Attributes
+    --------------------
+    ...
+    '''
+
+    #╭-------------------------------------------------------------------------╮
+    #| Class Attributes                                                        |
+    #╰-------------------------------------------------------------------------╯
+
+    _increment = 3
+    scheme = (3, 6, 9, 12)
+
+
+    #╭-------------------------------------------------------------------------╮
+    #| Initialize Instance                                                     |
+    #╰-------------------------------------------------------------------------╯
+
+    def __init__(self, arg=None, **kwargs):
+        '''
+        Parameters
+        ------------
+        arg : None | any
+            A scalar value to be interpreted as a quarter end date. Must be
+            None if 'year', 'month', or 'quarter' are provided. Refer to
+            '_to_datetime()' for supported input formats.
+        year : int
+            The calendar year of the quarter end date.
+        month : int
+            The calendar month of the quarter end date (1 to 12).
+        quarter : int
+            The quarter number (1 to 4). Cannot be used together with the
+            'month' argument.
+        offset : int
+            Number of quarters to shift from the base quarter end. Base
+            quarter end defaults to the most recently completed quarter end
+            when no other parameters are provided. Use positive values to move
+            forward and negative values to move backward in time.
+        kwargs : dict
+            Additional keyword arguments are forwarded to the Timestamp
+            constructor. Refer to its documentation for details.
+        '''
+        qtr = kwargs.pop('quarter', None)
+        parsed = self.parse_label(arg)
+
+        if parsed is not None:
+            for k in ['year','quarter']:
+                if kwargs.get(k) is not None:
+                    raise ValueError(
+                        f"'{k}' must be None when 'arg' "
+                        "is a quarter label: {arg!r}."
+                        )
+
+            kwargs['year'], qtr = parsed
+            arg = None
+
+        if qtr is not None:
+            if kwargs.get('month') is not None:
+                raise ValueError(
+                    "Cannot pass 'quarter' and 'month' "
+                    "arguments simultaneously."
+                    )
+            qtr = self._try_int(qtr)
+            kwargs['month'] = self.scheme[qtr - 1]
+
+        super().__init__(arg, **kwargs)
+
+
+    #╭-------------------------------------------------------------------------╮
+    #| Properties                                                              |
+    #╰-------------------------------------------------------------------------╯
+
+    @property
+    def long_label(self):
+        return f'{self.year}Q{self.qtr}'
+
+
+    @property
+    def compact_label(self):
+        return f'{self.qtr}Q' + self.str('%y')
+
+
+    @property
+    def short_label(self):
+        return f'Q{self.qtr}'
+
+
+    @property
+    def quarter(self):
+        ''' the quarter number (1 to 4) '''
+        return int(self.scheme.index(self.month) + 1)
+
+
+    @property
+    def qtr(self):
+        ''' quarter alias '''
+        return self.quarter
+
+
+    #╭-------------------------------------------------------------------------╮
+    #| Instance Methods                                                        |
+    #╰-------------------------------------------------------------------------╯
+
+    def _offset(self, year, month, offset):
+        year, month = self._backtrack_to_scheme(year, month)
+        return super()._offset(year, month, offset)
+
+
+    def _validate_instance(self):
+        if self.month not in self.scheme:
+            return f'month ({self.month}) is not in scheme: {self.scheme}'
+        return super()._validate_instance()
+
+
+    #╭-------------------------------------------------------------------------╮
+    #| Class Methods                                                           |
+    #╰-------------------------------------------------------------------------╯
+
+    @classmethod
+    def _backtrack_to_scheme(cls, year, month):
+        ''' Backtracks from the given year and month, moving one month at a
+            time, until a month that is part of the scheme is found. '''
+        while month not in cls.scheme:
+            year, month = cls._get_prior_month(year, month)
+        return year, month
+
+
+    @classmethod
+    def set_scheme(cls, value):
+        ''' safely sets 'scheme' class attribute '''
+
+        odd.validate_value(
+            value=value,
+            attr='scheme',
+            types=tuple
+            )
+
+        if len(value) != 4:
+            raise ValueError(
+                "'scheme' must contain 4 elements, "
+                f"got: {len(value):,}"
+                )
+
+        value = tuple(map(cls._try_int, value))
+        s = pd.Series(value)
+
+        if not (s.diff().dropna() == 3).all():
+            raise ValueError(
+                "'scheme' must be ascending in "
+                f"increments of 3. got: {value}."
+                )
+
+        if not s.between(
+            left=1,
+            right=MONTHS_IN_YEAR,
+            inclusive='both'
+            ).all():
+            raise ValueError(
+                "'scheme' values must be between 1 "
+                f"and {MONTHS_IN_YEAR}, got: {value}."
+                )
+
+        cls.scheme = value
+
+
+    @classmethod
+    def parse_label(cls, x):
+        '''
+        Description
+        ------------
+        Parses a quarter end label into its year and quarter components.
+        Supports input patterns like YYYYQ#, #QYY, and Q#. When the year
+        is not provided in the label, the current year is used by default.
+
+        Parameters
+        ------------
+        x : str
+            Quarter end label to parse.
+
+        Returns
+        ------------
+        Returns None if input is not a string or parsing failed.
+        Otherwise:
+
+        out : tuple
+            year : int
+                The four-digit year.
+            qtr : int
+                The quarter number (1 to 4).
+        '''
+
+        def extract_year_qtr(x):
+            if not isinstance(x, str): return
+            x = x.strip().upper()
+
+            # YYYYQ#
+            match = re.fullmatch(r'(\d{4})Q(\d)', x)
+            if match: return match.groups()
+
+            now = datetime.datetime.now()
+
+            # #QYY
+            match = re.fullmatch(r'(\d)Q(\d{2})', x)
+            if match:
+                qtr, yy = match.groups()
+                return f'{now.year // 100}{yy}', qtr
+
+            # Q#
+            match = re.fullmatch(r'Q(\d)', x)
+            if match:
+                qtr = match.group(1)
+                return str(now.year), qtr
+
+
+        parsed = extract_year_qtr(x)
+        if parsed is None: return
+        year, qtr = map(cls._try_int, parsed)
+
+        if not (1 <= qtr <= 4):
+            raise ValueError(
+                "Quarter must be between "
+                f"1 and 4, got: {qtr}"
+                )
+
+        return year, qtr

{clockwork-0.2.2 → clockwork-0.3.1}/clockwork/taskmaster/_task.py

@@ -3,7 +3,7 @@ import os
 from contextlib import redirect_stdout
 from schedule import CancelJob
 
-from ..core import Date
+from ..timestamp import Timestamp
 from ..utils import elapsed_time
 from .utils import PrerequisiteError, ContinueFailedJob
 
@@ -33,7 +33,7 @@ class Task(object):
         name of job
     at : str
         at time string
-    expiry : Date
+    expiry : Timestamp
         If not None, job will be set inactive and stop running after this
         datetime
     func : func
@@ -164,12 +164,12 @@ class Task(object):
             if logger: logger.info(f"{self.name} status update: '{self.status}'")
             self.update_table(active=0 if set_inactive else 1)
 
-        if self.expiry and self.expiry < Date():
+        if self.expiry and self.expiry < Timestamp():
             update_status('cancelled on expiration', set_inactive=True)
             if self.verbose:
                 print('Killing', end=' ')
                 print(self.name, end='')
-                print(f' @ {Date()} ->', end=' ')
+                print(f' @ {Timestamp()} ->', end=' ')
                 print('Job Cancelled')
 
         # cancel job if it was cancelled on cascasde or
@@ -186,12 +186,12 @@ class Task(object):
                 if self.verbose:
                     print('Running', end=' ')
                     print(self.name, end='')
-                    print(f' @ {Date()} ->', end=' ')
+                    print(f' @ {Timestamp()} ->', end=' ')
 
-                if self.restrict_to_business_hours and not Date().is_business_hours:
+                if self.restrict_to_business_hours and not Timestamp().is_business_hours:
                     raise PrerequisiteError('cannot execute outside of business hours')
 
-                if self.restrict_to_business_days and not Date().is_business_day:
+                if self.restrict_to_business_days and not Timestamp().is_business_day:
                     raise PrerequisiteError('cannot execute during the weekend')
 
                 if self.disable_print:

{clockwork-0.2.2 → clockwork-0.3.1}/clockwork/taskmaster/logger.py

@@ -1,6 +1,5 @@
 import logging
 import datetime
-from pathpilot import Folder
 
 
 #╭-------------------------------------------------------------------------╮
@@ -55,12 +54,10 @@ class Logger(object):
         # create custom formatter
         # https://docs.python.org/3/library/logging.html#logrecord-attributes
         formatter = CustomLogFormatter(fmt='%(asctime)s %(levelname)s %(message)s')
-        #formatter = CustomLogFormatter(fmt='%(asctime)s %(name)s %(levelname)s %(message)s')
+        # formatter = CustomLogFormatter(fmt='%(asctime)s %(name)s %(levelname)s %(message)s')
 
         # create file handler which logs even debug messages
-        self.file = Folder().parent\
-            .join('Data', 'Logger', read_only=False)\
-            .join(f'{name}.log').path
+        self.file = self.folder.join(f'{name}.log', read_only=False).path
         if clear: self.clear()
         fh = logging.FileHandler(self.file)
         fh.setLevel(logging.DEBUG)

{clockwork-0.2.2 → clockwork-0.3.1}/clockwork/taskmaster/taskmaster.py

@@ -1,10 +1,9 @@
 import datetime
 import time
 import uuid
-from oddments import to_iter
-from pathpilot import Folder
+import oddments as odd
 
-from ..core import Date
+from ..timestamp import Timestamp
 from ._scheduler import TaskScheduler
 from ._task import Task
 
@@ -146,9 +145,9 @@ class TaskMaster(object):
             constituent time.
         interval : int
             schedule.Scheduler.every interval argument
-        start : Date
+        start : Timestamp
             If not None, job will be not be added until this datetime
-        expiry : Date
+        expiry : Timestamp
             If not None, job will be set inactive and stop running after this
             datetime
         kwargs : keyword arguments
@@ -160,15 +159,14 @@ class TaskMaster(object):
         '''
 
         if not hasattr(cls, 'db'):
-            cls.db = Folder().parent.join('Data', 'SQLite', read_only=False)\
-                                    .join('taskmaster.sqlite')
-            cls.db.connect()
-            cls.db.enable_foreign_keys()
+            raise NotImplementedError
+            # cls.db.connect()
+            # cls.db.enable_foreign_keys()
 
         if not hasattr(cls, 'scheduler'):
             cls.scheduler = TaskScheduler()
 
-        now = Date()
+        now = Timestamp()
         if (start and start > now) or (expiry and expiry < now): return
         expiry_str = expiry.dt.strftime('%Y-%m-%d %I:%M:%S.{} %p')\
                      .format('%03d' % (expiry.dt.microsecond / 1000))\
@@ -183,7 +181,7 @@ class TaskMaster(object):
             else:
                 raise Exception("'every' argument cannot be None")
 
-        for at in to_iter(at):
+        for at in odd.to_iter(at):
             job = getattr(cls.scheduler.every(interval), every)
             if at is not None:
                 try: