clockwork 0.2.1__tar.gz → 0.3.0__tar.gz

{clockwork-0.2.1 → clockwork-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: clockwork
-Version: 0.2.1
+Version: 0.3.0
 Summary: Toolkit for time-related operations including scheduling, logging, date manipulation, and more.
 Home-page: https://github.com/zteinck/clockwork
 License: MIT
@@ -15,12 +15,10 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Requires-Dist: holidays
-Requires-Dist: iterlab
 Requires-Dist: numpy
+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.0/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.0'
+__author__ = 'Zachary Einck <zacharyeinck@gmail.com>'

clockwork-0.3.0/clockwork/constants.py

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

clockwork-0.3.0/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.0/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.0/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.3.0/clockwork/taskmaster/_scheduler.py

@@ -0,0 +1,27 @@
+import datetime
+from schedule import Scheduler, CancelJob
+
+from .utils import ContinueFailedJob
+
+
+class TaskScheduler(Scheduler):
+
+    #╭-------------------------------------------------------------------------╮
+    #| Initialize Instance                                                     |
+    #╰-------------------------------------------------------------------------╯
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+
+    #╭-------------------------------------------------------------------------╮
+    #| Instance Methods                                                        |
+    #╰-------------------------------------------------------------------------╯
+
+    def _run_job(self, job):
+        ret = job.run()
+        if ret is CancelJob:
+            self.cancel_job(job)
+        elif ret is ContinueFailedJob:
+            job.last_run = datetime.datetime.now()
+            job._schedule_next_run()

{clockwork-0.2.1 → clockwork-0.3.0}/clockwork/taskmaster/_task.py

@@ -3,12 +3,11 @@ 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
 
 
-
 class Task(object):
     '''
     Description
@@ -34,8 +33,9 @@ class Task(object):
         name of job
     at : str
         at time string
-    expiry : Date
-        If not None, job will be set inactive and stop running after this datetime
+    expiry : Timestamp
+        If not None, job will be set inactive and stop running after this
+        datetime
     func : func
         function to run
     args : tuple
@@ -164,15 +164,16 @@ 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 if it was set inactive after being scheduled
+        # cancel job if it was cancelled on cascasde or
+        # if it was set inactive after being scheduled
         if self.status == self.cascade_status or \
            not self.master.is_active(self.name, self.at):
             return CancelJob
@@ -185,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.1 → clockwork-0.3.0}/clockwork/taskmaster/file_monitor.py

@@ -1,15 +1,14 @@
 from .utils import PrerequisiteError
 
 
-
 class FileMonitor(object):
     '''
     Description
     --------------------
     Monitors a folder for new files and passes latest and 2nd latest file
-    names to user-defined function. Class is intended to be used in conjunction
-    with TaskMaster as a func argument which allows for file monitoring at regular
-    intervals.
+    names to user-defined function. Class is intended to be used in
+    conjunction with TaskMaster as a func argument which allows for file
+    monitoring at regular intervals.
 
     Class Attributes
     --------------------
@@ -18,8 +17,8 @@ class FileMonitor(object):
     Instance Attributes
     --------------------
     func : func
-        Custom function that takes the latest and second-latest file names in a
-        folder as the first and second arguments, respectively.
+        Custom function that takes the latest and second-latest file names
+        in a folder as the first and second arguments, respectively.
     folder : Folder object
         folder to monitor for new files.
     filter_kwargs : dict

{clockwork-0.2.1 → clockwork-0.3.0}/clockwork/taskmaster/logger.py

@@ -1,6 +1,5 @@
 import logging
 import datetime
-from pathpilot import Folder
 
 
 #╭-------------------------------------------------------------------------╮
@@ -21,7 +20,6 @@ class CustomLogFormatter(logging.Formatter):
                    .format('%03d' % record.msecs)
 
 
-
 class Logger(object):
 
     #╭-------------------------------------------------------------------------╮
@@ -56,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)