clockwork 0.6.1__tar.gz → 0.7.0__tar.gz

{clockwork-0.6.1 → clockwork-0.7.0}/.python-version

@@ -1 +1 @@
-3.13
+3.13

{clockwork-0.6.1 → clockwork-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: clockwork
-Version: 0.6.1
+Version: 0.7.0
 Summary: Toolkit for time-related operations including scheduling, logging, date manipulation, and more.
 Project-URL: repository, https://github.com/zteinck/clockwork
 Project-URL: homepage, https://github.com/zteinck/clockwork
@@ -10,9 +10,10 @@ License-File: LICENSE
 Requires-Python: >=3.13
 Requires-Dist: holidays>=0.94
 Requires-Dist: numpy>=2.4.4
-Requires-Dist: oddments>=0.9.1
+Requires-Dist: oddments>=0.10.0
 Requires-Dist: pandas>=3.0.2
 Requires-Dist: polars>=1.39.3
+Requires-Dist: python-dateutil>=2.9.0.post0
 Requires-Dist: schedule>=1.2.2
 Description-Content-Type: text/markdown
 

{clockwork-0.6.1 → clockwork-0.7.0}/clockwork/__init__.py

@@ -8,5 +8,5 @@ from .utils import (
     temporal_format_to_regex,
     )
 
-__version__ = '0.6.1'
+__version__ = '0.7.0'
 __author__ = 'Zachary Einck <zacharyeinck@gmail.com>'

{clockwork-0.6.1 → clockwork-0.7.0}/clockwork/decorators.py

@@ -1,7 +1,7 @@
 from functools import wraps
 from time import perf_counter
 
-from oddments import validate_value
+from oddments import Validator
 
 from .utils import format_duration
 
@@ -25,7 +25,7 @@ def print_duration(indents=1, in_place=True):
 
     Returns
     ------------
-    out : any
+    result : any
         The decorated method's return value.
     '''
 
@@ -95,19 +95,18 @@ def print_duration(indents=1, in_place=True):
 
 
             # validate decorator arguments
-            validate_value(
-                value=indents,
-                name='indents',
+            (
+            Validator(
                 types=int,
                 min_value=0,
-                min_inclusive=True
+                min_inclusive=True,
                 )
-
-            validate_value(
-                value=in_place,
-                name='in_place',
-                types=bool,
+            .validate(
+                indents=indents
                 )
+            )
+
+            Validator(types=bool).validate(in_place=in_place)
 
             if self.verbose:
                 words = [
@@ -119,13 +118,13 @@ def print_duration(indents=1, in_place=True):
                 print_status()
                 start_time = perf_counter()
 
-            out = func(self, *args, **kwargs)
+            result = func(self, *args, **kwargs)
 
             if self.verbose:
                 duration = perf_counter() - start_time
                 print_status(duration)
 
-            return out
+            return result
 
         return wrapper
 

clockwork-0.7.0/clockwork/month_end.py

@@ -0,0 +1,243 @@
+import datetime
+
+from oddments import Validator, UNSET
+
+from .timestamp import Timestamp
+from .constants import MONTHS_IN_YEAR
+
+
+class MonthEnd(Timestamp):
+    '''
+    Description
+    --------------------
+    Month end date.
+
+    Class Attributes
+    --------------------
+    _increment : int
+        Number of months to increment during offsets.
+
+    Instance Attributes
+    --------------------
+    None
+    '''
+
+    #╭-------------------------------------------------------------------------╮
+    #| Class Attributes                                                        |
+    #╰-------------------------------------------------------------------------╯
+
+    repr_format = '%Y-%m-%d'
+    _increment = 1
+
+
+    #╭-------------------------------------------------------------------------╮
+    #| Initialize Instance                                                     |
+    #╰-------------------------------------------------------------------------╯
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+
+    #╭-------------------------------------------------------------------------╮
+    #| Properties                                                              |
+    #╰-------------------------------------------------------------------------╯
+
+    @property
+    def long_label(self):
+        return self.to_string('%Y-%m-%d')
+
+
+    @property
+    def compact_label(self):
+        return self.to_string('%Y-%m')
+
+
+    @property
+    def short_label(self):
+        return self.to_string('%b')
+
+
+    @property
+    def is_year_end(self):
+        return self.month == MONTHS_IN_YEAR
+
+
+    @property
+    def relative_offset(self):
+        return self._compute_relative_offset()
+
+
+    #╭-------------------------------------------------------------------------╮
+    #| Instance Methods                                                        |
+    #╰-------------------------------------------------------------------------╯
+
+    def offset(self, periods):
+        ''' offsets instance by desired number of periods '''
+        Validator(types=int).validate(periods=periods)
+        offset = self.relative_offset + periods
+        result = self._spawn(offset=offset, target_tz=self.tz)
+        return result
+
+
+    def _offset(self, year, month, offset):
+        total_months = self._total_months(
+            years=year,
+            months=(month + offset),
+            )
+
+        y, m = divmod(total_months, MONTHS_IN_YEAR)
+
+        if m == 0:
+            return y - 1, MONTHS_IN_YEAR
+
+        return y, m
+
+
+    def _compute_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(
+                years=obj.year,
+                months=obj.month,
+                )
+            for obj in (
+                self,
+                self._spawn(
+                    offset=0,
+                    target_tz=self.tz,
+                    )
+                )
+            )
+
+        q, r = divmod(a - b, self._increment)
+
+        if r != 0:
+            raise AssertionError(
+                f'Unexpected remainder: {r}'
+                )
+
+        return int(q)
+
+
+    def _validate(self):
+        ''' raises an error if the instance fails validation '''
+        msg = self._find_error()
+
+        if msg is not None:
+            raise ValueError(
+                f'{self.__class__.__name__} instance is invalid because {msg}'
+                )
+
+
+    def _find_error(self):
+        if not self.is_last_day_of_month:
+            return (
+                f'{self.day} is not the last day ({self.last_day_of_month}) '
+                f'of {self.month_name} {self.year}'
+                )
+
+        if not self.is_normalized:
+            return (
+                'the time component must be normalized (i.e. all zoroes), '
+                f'got: {self.time}'
+                )
+
+
+    def _init_dt(
+        self,
+        source,
+        target_tz,
+        offset,
+        year=None,
+        month=None,
+        **kwargs
+        ):
+        '''
+        Parameters
+        ------------
+        source : None | any
+            A value representing a month end date. Must be None if 'year' or
+            'month' arguments are provided.
+        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 in
+            time and negative values to move backward in time.
+        kwargs : dict
+            Additional keyword arguments are forwarded to the Timestamp
+            constructor.
+        '''
+
+        has_source = source is not None
+        has_year_or_month = year is not None or month is not None
+
+        if has_source:
+            if has_year_or_month:
+                raise ValueError(
+                    "Both 'year' and 'month' must be None when 'source' is "
+                    "not None."
+                    )
+
+            self._dt = self._resolve_dt(
+                source=source,
+                target_tz=target_tz,
+                offset=offset,
+                **kwargs
+                )
+
+            if offset != 0:
+                self._dt = self.offset(periods=offset).to_datetime()
+
+        else:
+            _target_tz = None if target_tz is UNSET else target_tz
+
+            if has_year_or_month:
+                year, month = (
+                    self._ensure_int(value=v, name=k)
+                    for k, v in {
+                        'year': year,
+                        'month': month,
+                        }.items()
+                    )
+                self._validate_month(month)
+
+            else:
+                now = datetime.datetime.now(tz=_target_tz)
+
+                year, month = self._get_prior_month(
+                    year=now.year,
+                    month=now.month,
+                    )
+
+            year, month = self._offset(
+                year=year,
+                month=month,
+                offset=(offset * self._increment),
+                )
+
+            day = self.days_in_month(year, month)
+
+            self._dt = datetime.datetime(
+                year=year,
+                month=month,
+                day=day,
+                tzinfo=_target_tz,
+                )
+
+        self._dt = self._normalize(self._dt)
+        self._validate()

clockwork-0.7.0/clockwork/quarter_end.py

@@ -0,0 +1,314 @@
+import datetime
+import re
+
+from oddments import Validator, UNSET
+import polars as pl
+
+from .month_end import MonthEnd
+from .constants import MONTHS_IN_YEAR
+
+
+class QuarterEnd(MonthEnd):
+    '''
+    Description
+    --------------------
+    Quarter end date.
+
+    Class Attributes
+    --------------------
+    _scheme : tuple
+        Quarter end months.
+
+    Instance Attributes
+    --------------------
+    None
+    '''
+
+    #╭-------------------------------------------------------------------------╮
+    #| Class Attributes                                                        |
+    #╰-------------------------------------------------------------------------╯
+
+    _increment = 3
+    _scheme = (3, 6, 9, 12)
+
+
+    #╭-------------------------------------------------------------------------╮
+    #| Initialize Instance                                                     |
+    #╰-------------------------------------------------------------------------╯
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+
+
+    #╭-------------------------------------------------------------------------╮
+    #| Properties                                                              |
+    #╰-------------------------------------------------------------------------╯
+
+    @property
+    def scheme(self):
+        return self._scheme
+
+
+    @property
+    def long_label(self):
+        return f'{self.year}Q{self.quarter}'
+
+
+    @property
+    def compact_label(self):
+        return f'{self.quarter}Q' + self.to_string('%y')
+
+
+    @property
+    def short_label(self):
+        return f'Q{self.quarter}'
+
+
+    @property
+    def quarter(self):
+        ''' the quarter number (1 to 4) '''
+        return int(self.scheme.index(self.month) + 1)
+
+
+    #╭-------------------------------------------------------------------------╮
+    #| Instance Methods                                                        |
+    #╰-------------------------------------------------------------------------╯
+
+    def _init_dt(
+        self,
+        source,
+        target_tz,
+        year=None,
+        month=None,
+        quarter=None,
+        **kwargs
+        ):
+        '''
+        Parameters
+        ------------
+        source : None | any
+            A value representing a quarter end date. Must be None if 'year',
+            'month', or 'quarter' are provided.
+        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 in time and negative values to move backward in time.
+        kwargs : dict
+            Additional keyword arguments forwarded to the Timestamp
+            constructor.
+        '''
+
+        parsed_label = self._parse_label(source, target_tz)
+
+        if parsed_label is not None:
+            for k, v in {
+                'year': year,
+                'month': month,
+                'quarter': quarter,
+                }.items():
+                if v is not None:
+                    raise ValueError(
+                        f"{k!r} must be None when 'source' is a quarter end "
+                        f"label: {source!r}."
+                        )
+
+            year, quarter = parsed_label
+            source = None
+
+        has_quarter = quarter is not None
+
+        if month is not None:
+            if has_quarter:
+                raise ValueError(
+                    "Cannot pass 'quarter' and 'month' arguments "
+                    "simultaneously."
+                    )
+
+            month = self._ensure_int(month)
+
+            # validate month
+            (
+            Validator(
+                types=int,
+                whitelist=self.scheme,
+                )
+            .validate(
+                month=month
+                )
+            )
+
+        if has_quarter:
+            quarter = self._ensure_int(
+                value=quarter,
+                name='quarter',
+                )
+            month = self.scheme[quarter - 1]
+
+        super()._init_dt(
+            source=source,
+            target_tz=target_tz,
+            year=year,
+            month=month,
+            **kwargs
+            )
+
+
+    def _offset(self, year, month, offset):
+        year, month = self._backtrack_to_scheme(
+            year=year,
+            month=month,
+            )
+
+        result = super()._offset(
+            year=year,
+            month=month,
+            offset=offset,
+            )
+
+        return result
+
+
+    def _find_error(self):
+        if self.month not in self.scheme:
+            return f'the month ({self.month}) is not in scheme: {self.scheme}'
+        return super()._find_error()
+
+
+    #╭-------------------------------------------------------------------------╮
+    #| Class Methods                                                           |
+    #╰-------------------------------------------------------------------------╯
+
+    @classmethod
+    def set_scheme(cls, value):
+        ''' safely sets 'scheme' class attribute '''
+
+        name = 'scheme'
+
+        Validator(types=tuple).validate(value, name)
+
+        if len(value) != 4:
+            raise ValueError(
+                f"'scheme' must contain 4 elements, got: {len(value):,}"
+                )
+
+        value = tuple(map(cls._ensure_int, value))
+        s = pl.Series(name=name, values=value)
+
+        valid_increments = (
+            s.diff(null_behavior='drop') == 3
+            ).all()
+
+        if not valid_increments:
+            raise ValueError(
+                "'scheme' must be ascending in increments of 3, got: "
+                f"{value!r}"
+                )
+
+        valid_months = s.is_between(
+            lower_bound=1,
+            upper_bound=MONTHS_IN_YEAR,
+            closed='both'
+            ).all()
+
+        if not valid_months:
+            raise ValueError(
+                f"'scheme' values must be between 1 and {MONTHS_IN_YEAR}, "
+                f"got: {value!r}."
+                )
+
+        cls._scheme = value
+
+
+    @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=year,
+                month=month,
+                )
+
+        return year, month
+
+
+    @classmethod
+    def _parse_label(cls, source, target_tz):
+        '''
+        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
+        ------------
+        source : str
+            Quarter end label to parse.
+        target_tz : str | datetime.timezone
+            Refer to '_resolve_dt()' documentation.
+
+        Returns
+        ------------
+        Returns None if input is not a string or parsing failed.
+        Otherwise:
+
+        result : tuple
+            year : int
+                The four-digit year.
+            quarter : int
+                The quarter number (1 to 4).
+        '''
+
+        def extract_year_and_quarter(value):
+            if not isinstance(value, str):
+                return None
+
+            value = value.strip().upper()
+
+            # 'YYYYQ#' | 'YYYY Q#'
+            match = re.fullmatch(r'(\d{4})\s?Q(\d)', value)
+
+            if match:
+                return match.groups()
+
+            tz = None if target_tz is UNSET else target_tz
+            now = datetime.datetime.now(tz=tz)
+
+            # '#QYY'
+            match = re.fullmatch(r'(\d)Q(\d{2})', value)
+
+            if match:
+                quarter, year = match.groups()
+                return f'{now.year // 100}{year}', quarter
+
+            # 'Q#'
+            match = re.fullmatch(r'Q(\d)', value)
+
+            if match:
+                quarter = match.group(1)
+                return f'{now.year}', quarter
+
+
+        parsed = extract_year_and_quarter(source)
+
+        if parsed is None:
+            return None
+
+        year, quarter = (cls._ensure_int(x) for x in parsed)
+
+        if not (1 <= quarter <= 4):
+            raise ValueError(
+                f"Quarter must be between 1 and 4, got: {quarter}"
+                )
+
+        return year, quarter

{clockwork-0.6.1 → clockwork-0.7.0}/clockwork/taskmaster/_task.py

@@ -13,7 +13,7 @@ from .utils import (
     )
 
 
-class Task(object):
+class Task:
     '''
     Description
     --------------------
@@ -211,9 +211,9 @@ class Task(object):
 
                 if self.disable_print:
                     with redirect_stdout(open(os.devnull, 'w')):
-                        out = self.func(*self.args, **self.kwargs)
+                        result = self.func(*self.args, **self.kwargs)
                 else:
-                    out = self.func(*self.args, **self.kwargs)
+                    result = self.func(*self.args, **self.kwargs)
 
                 if self.verbose:
                     elapsed = format_duration(time.time() - start)
@@ -230,7 +230,7 @@ class Task(object):
                 if self.cancel_on_completion:
                     update_status('cancelled on completion', set_inactive=True)
 
-                return CancelJob if self.cancel_on_completion else out
+                return CancelJob if self.cancel_on_completion else result
 
             except Exception as e:
 

{clockwork-0.6.1 → clockwork-0.7.0}/clockwork/taskmaster/file_monitor.py

@@ -1,7 +1,7 @@
 from .utils import PrerequisiteError
 
 
-class FileMonitor(object):
+class FileMonitor:
     '''
     Description
     --------------------