clockwork 0.6.0__tar.gz → 0.7.0__tar.gz

clockwork-0.7.0/.gitignore

@@ -0,0 +1,162 @@
+# https://github.com/github/gitignore/blob/main/Python.gitignore
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/#use-with-ide
+.pdm.toml
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/

clockwork-0.7.0/.python-version

@@ -0,0 +1 @@
+3.13

clockwork-0.7.0/PKG-INFO

@@ -0,0 +1,36 @@
+Metadata-Version: 2.5
+Name: clockwork
+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
+Author-email: Zachary Einck <zacharyeinck@gmail.com>
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: holidays>=0.94
+Requires-Dist: numpy>=2.4.4
+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
+
+<div>
+
+[![Package version](https://img.shields.io/pypi/v/clockwork?color=%2334D058&label=pypi)](https://pypi.org/project/clockwork/)
+[![License](https://img.shields.io/github/license/zteinck/clockwork)](https://github.com/zteinck/clockwork/blob/master/LICENSE)
+
+</div>
+
+
+`clockwork` is a Python package that provides a multitude of time-related functionalities, facilitating tasks such as scheduling, logging, date manipulation, and more.
+
+
+## Installation
+```sh
+pip install clockwork
+```

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

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

{clockwork-0.6.0 → 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()