aws-croniter 0.1.0__tar.gz

aws_croniter-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Siddarth Patil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aws_croniter-0.1.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.1
+Name: aws-croniter
+Version: 0.1.0
+Summary: A Python utility for AWS cron expressions. Validate and parse AWS EventBridge cron expressions seamlessly.
+License: MIT
+Author: Siddarth Patil
+Author-email: siddarth3639@gmail.com
+Requires-Python: >=3.8,<4.0
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Dist: python-dateutil (>=2.8.1,<3.0.0)
+Description-Content-Type: text/markdown
+
+# AWS Croniter
+
+AWS Croniter is a Python library that provides utilities for working with AWS cron expressions. It allows you to easily parse, manipulate, and validate cron expressions used in AWS services like CloudWatch and EventBridge.
+
+## Features
+
+- Parse AWS cron expressions
+- Validate cron expressions
+- Generate next execution times
+- Convert cron expressions to human-readable format
+
+## Installation
+
+You can install AWS Croniter using pip:
+
+```sh
+pip install aws-croniter
+```
+
+## Usage
+
+Here is a basic example of how to use AWS Croniter:
+
+```python
+from aws_croniter import Croniter
+
+# Create a Croniter object with an AWS cron expression
+cron = Croniter('cron(0 12 * * ? *)')
+
+# Validate the cron expression
+if cron.is_valid():
+    print("The cron expression is valid.")
+
+# Get the next execution time
+next_time = cron.get_next()
+print(f"The next execution time is: {next_time}")
+
+# Convert to human-readable format
+human_readable = cron.to_human_readable()
+print(f"Human-readable format: {human_readable}")
+```
+
+## Contributing
+
+Contributions are welcome! Please read the [contributing guidelines](CONTRIBUTING.md) first.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Contact
+
+For any questions or suggestions, please open an issue or contact the maintainer at [email@example.com](mailto:email@example.com).
+

aws_croniter-0.1.0/README.md

@@ -0,0 +1,53 @@
+# AWS Croniter
+
+AWS Croniter is a Python library that provides utilities for working with AWS cron expressions. It allows you to easily parse, manipulate, and validate cron expressions used in AWS services like CloudWatch and EventBridge.
+
+## Features
+
+- Parse AWS cron expressions
+- Validate cron expressions
+- Generate next execution times
+- Convert cron expressions to human-readable format
+
+## Installation
+
+You can install AWS Croniter using pip:
+
+```sh
+pip install aws-croniter
+```
+
+## Usage
+
+Here is a basic example of how to use AWS Croniter:
+
+```python
+from aws_croniter import Croniter
+
+# Create a Croniter object with an AWS cron expression
+cron = Croniter('cron(0 12 * * ? *)')
+
+# Validate the cron expression
+if cron.is_valid():
+    print("The cron expression is valid.")
+
+# Get the next execution time
+next_time = cron.get_next()
+print(f"The next execution time is: {next_time}")
+
+# Convert to human-readable format
+human_readable = cron.to_human_readable()
+print(f"Human-readable format: {human_readable}")
+```
+
+## Contributing
+
+Contributions are welcome! Please read the [contributing guidelines](CONTRIBUTING.md) first.
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
+
+## Contact
+
+For any questions or suggestions, please open an issue or contact the maintainer at [email@example.com](mailto:email@example.com).

aws_croniter-0.1.0/pyproject.toml

@@ -0,0 +1,60 @@
+[tool.poetry]
+name = "aws-croniter"
+version = "0.1.0"
+description = "A Python utility for AWS cron expressions. Validate and parse AWS EventBridge cron expressions seamlessly."
+authors = ["Siddarth Patil <siddarth3639@gmail.com>"]
+license = "MIT"
+readme = "README.md"
+
+packages = [{ include = "aws_croniter", from = "src" }]
+
+[tool.poetry.dependencies]
+python = "^3.8"
+python-dateutil = "^2.8.1"
+
+[tool.poetry.group.test.dependencies]
+coverage = "^7.6"
+pytest = "^8.0.0"
+pytest-cov = "^5.0"
+tox = "^4.23.2"
+
+
+[tool.pytest.ini_options]
+markers = [
+    "package",
+]
+testpaths = "tests"
+addopts = "--durations=3 --cov --cov-report=html --cov-report=xml"
+
+[tool.coverage.run]
+source = ["aws_croniter"]
+
+[tool.coverage.report]
+fail_under = 80
+
+[tool.ruff]
+# Setting the maximum line length
+line-length = 120
+include = ["src"]
+
+[tool.ruff.lint]
+# Extending the rules to apply
+extend-select = [
+    "S", # flake8-bandit
+    "E501", # Line too long
+    "W292", # No newline at end of file
+    "W293", # Blank line contains whitespace
+]
+
+[tool.ruff.lint.isort]
+force-single-line = true
+
+[tool.ruff.lint.extend-per-file-ignores]
+"tests/*" = [
+    "S101", # asserts allowed in tests
+]
+
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

aws_croniter-0.1.0/src/aws_croniter/awscron.py

@@ -0,0 +1,264 @@
+import datetime
+import re
+
+from aws_croniter.exceptions import AWSCronExpressionDayOfMonthError
+from aws_croniter.exceptions import AWSCronExpressionDayOfWeekError
+from aws_croniter.exceptions import AWSCronExpressionError
+from aws_croniter.exceptions import AWSCronExpressionHourError
+from aws_croniter.exceptions import AWSCronExpressionMinuteError
+from aws_croniter.exceptions import AWSCronExpressionMonthError
+from aws_croniter.exceptions import AWSCronExpressionYearError
+from aws_croniter.occurrence import Occurrence
+from aws_croniter.utils import RegexUtils
+
+
+class AWSCron:
+    MONTH_REPLACES = [
+        ["JAN", "1"],
+        ["FEB", "2"],
+        ["MAR", "3"],
+        ["APR", "4"],
+        ["MAY", "5"],
+        ["JUN", "6"],
+        ["JUL", "7"],
+        ["AUG", "8"],
+        ["SEP", "9"],
+        ["OCT", "10"],
+        ["NOV", "11"],
+        ["DEC", "12"],
+    ]
+
+    DAY_WEEK_REPLACES = [
+        ["SUN", "1"],
+        ["MON", "2"],
+        ["TUE", "3"],
+        ["WED", "4"],
+        ["THU", "5"],
+        ["FRI", "6"],
+        ["SAT", "7"],
+    ]
+
+    def __init__(self, cron):
+        self.cron = cron
+        self.minutes = None
+        self.hours = None
+        self.days_of_month = None
+        self.months = None
+        self.days_of_week = None
+        self.years = None
+        self.rules = cron.split(" ")
+        self.__validate()
+
+    def __validate(self):
+        """
+        Validates these AWS EventBridge cron expressions, which are similar to, but not compatible with standard
+        unix cron expressions:
+        https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-create-rule-schedule.html#eb-cron-expressions
+
+        | Field        | Values          | Wildcards     |
+        | :----------: | :-------------: | :-----------: |
+        | Minute       | 0-59            | , - * /       |
+        | Hour         | 0-23            | , - * /       |
+        | Day-of-month | 1-31            | , - * ? / L W |
+        | Month        | 1-12 or JAN-DEC | , - * /       |
+        | Day-of-week  | 1-7 or SUN-SAT  | , - * ? L #   |
+        | Year         | 1970-2199       | , - * /       |
+        """
+        value_count = len(self.cron.split(" "))
+        if value_count != 6:
+            raise AWSCronExpressionError(
+                f"Incorrect number of values in '{self.cron}'. 6 required, {value_count} provided."
+            )
+
+        minute, hour, day_of_month, month, day_of_week, year = self.cron.split(" ")
+
+        if not ((day_of_month == "?" and day_of_week != "?") or (day_of_month != "?" and day_of_week == "?")):
+            raise AWSCronExpressionError(
+                f"Invalid combination of day-of-month '{day_of_month}' and day-of-week '{day_of_week}'."
+                "One must be a question mark (?)"
+            )
+
+        if not re.fullmatch(RegexUtils.minute_regex(), minute):
+            raise AWSCronExpressionMinuteError(f"Invalid minute value '{minute}'.")
+        if not re.fullmatch(RegexUtils.hour_regex(), hour):
+            raise AWSCronExpressionHourError(f"Invalid hour value '{hour}'.")
+        if not re.fullmatch(RegexUtils.day_of_month_regex(), day_of_month):
+            raise AWSCronExpressionDayOfMonthError(f"Invalid day-of-month value '{day_of_month}'.")
+        if not re.fullmatch(RegexUtils.month_regex(), month):
+            raise AWSCronExpressionMonthError(f"Invalid month value '{month}'.")
+        if not re.fullmatch(RegexUtils.day_of_week_regex(), day_of_week):
+            raise AWSCronExpressionDayOfWeekError(f"Invalid day-of-week value '{day_of_week}'.")
+        if not re.fullmatch(RegexUtils.year_regex(), year):
+            raise AWSCronExpressionYearError(f"Invalid year value '{year}'.")
+
+        # If validation passes, then parse the cron expression
+        self.__parse()
+
+    def occurrence(self, utc_datetime):
+        if utc_datetime.tzinfo is None or utc_datetime.tzinfo != datetime.timezone.utc:
+            raise Exception("Occurrence utc_datetime must have tzinfo == datetime.timezone.utc")
+        return Occurrence(self, utc_datetime)
+
+    def __str__(self):
+        return f"cron({self.cron})"
+
+    def __replace(self, s, rules):
+        rs = str(s).upper()
+        for rule in rules:
+            rs = rs.replace(rule[0], rule[1])
+        return rs
+
+    def __parse(self):
+        self.minutes = self.__parse_one_rule(self.rules[0], 0, 59)
+        self.hours = self.__parse_one_rule(self.rules[1], 0, 23)
+        self.days_of_month = self.__parse_one_rule(self.rules[2], 1, 31)
+        self.months = self.__parse_one_rule(self.__replace(self.rules[3], AWSCron.MONTH_REPLACES), 1, 12)
+        self.days_of_week = self.__parse_one_rule(self.__replace(self.rules[4], AWSCron.DAY_WEEK_REPLACES), 1, 7)
+        self.years = self.__parse_one_rule(self.rules[5], 1970, 2199)
+
+    @staticmethod
+    def __parse_one_rule(rule, min_value, max_value):
+        if rule == "?":
+            return []
+        if rule == "L":
+            return ["L", 0]
+        if rule.startswith("L-"):
+            return ["L", int(rule[2:])]
+        if rule.endswith("L"):
+            return ["L", int(rule[0:-1])]
+        if rule.endswith("W"):
+            return ["W", int(rule[0:-1])]
+        if "#" in rule:
+            return ["#", int(rule.split("#")[0]), int(rule.split("#")[1])]
+
+        new_rule = None
+        if rule == "*":
+            new_rule = str(min_value) + "-" + str(max_value)
+        elif "/" in rule:
+            parts = rule.split("/")
+            start = None
+            end = None
+            if parts[0] == "*":
+                start = min_value
+                end = max_value
+            elif "-" in parts[0]:
+                splits = parts[0].split("-")
+                start = int(splits[0])
+                end = int(splits[1])
+            else:
+                start = int(parts[0])
+                end = max_value
+            increment = int(parts[1])
+            new_rule = ""
+            while start <= end:
+                new_rule += "," + str(start)
+                start += increment
+            new_rule = new_rule[1:]
+        else:
+            new_rule = rule
+        allows = []
+        for s in new_rule.split(","):
+            if "-" in s:
+                parts = s.split("-")
+                start = int(parts[0])
+                end = int(parts[1])
+                for i in range(start, end + 1, 1):
+                    allows.append(i)
+            else:
+                allows.append(int(s))
+        allows.sort()
+        return allows
+
+    @staticmethod
+    def get_next_n_schedule(n, from_date, cron):
+        """
+        Returns a list with the n next datetime(s) that match the aws cron expression from the provided start date.
+
+        :param n: Int of the n next datetime(s)
+        :param from_date: datetime with the start date
+        :param cron: str of aws cron to be parsed
+        :return: list of datetime objects
+        """
+        schedule_list = list()
+        if not isinstance(from_date, datetime.datetime):
+            raise ValueError(
+                "Invalid from_date. Must be of type datetime.datetime" " and have tzinfo = datetime.timezone.utc"
+            )
+        else:
+            cron_iterator = AWSCron(cron)
+            for i in range(n):
+                from_date = cron_iterator.occurrence(from_date).next()
+                schedule_list.append(from_date)
+
+            return schedule_list
+
+    @staticmethod
+    def get_prev_n_schedule(n, from_date, cron):
+        """
+        Returns a list with the n prev datetime(s) that match the aws cron expression
+        from the provided start date.
+
+        :param n: Int of the n next datetime(s)
+        :param from_date: datetime with the start date
+        :param cron: str of aws cron to be parsed
+        :return: list of datetime objects
+        """
+        schedule_list = list()
+        if not isinstance(from_date, datetime.datetime):
+            raise ValueError(
+                "Invalid from_date. Must be of type datetime.datetime" " and have tzinfo = datetime.timezone.utc"
+            )
+        else:
+            cron_iterator = AWSCron(cron)
+            for i in range(n):
+                from_date = cron_iterator.occurrence(from_date).prev()
+                schedule_list.append(from_date)
+
+            return schedule_list
+
+    @staticmethod
+    def get_all_schedule_bw_dates(from_date, to_date, cron, exclude_ends=False):
+        """
+        Get all datetimes from from_date to to_date matching the given cron expression.
+        If the cron expression matches either 'from_date' and/or 'to_date',
+        those times will be returned as well unless 'exclude_ends=True' is passed.
+
+        :param from_date: datetime object from where the schedule will start with tzinfo in utc.
+        :param to_date: datetime object to where the schedule will end with tzinfo in utc.
+        :param cron: str of aws cron to be parsed
+        :param exclude_ends: bool defaulted to False, to not exclude the end date
+        :return: list of datetime objects
+        """
+
+        if type(from_date) != type(to_date) and not (
+            isinstance(from_date, type(to_date)) or isinstance(to_date, type(from_date))
+        ):
+            raise ValueError(
+                "The from_date and to_date must be same type." "  {0} != {1}".format(type(from_date), type(to_date))
+            )
+
+        elif not isinstance(from_date, datetime.datetime) or (from_date.tzinfo != datetime.timezone.utc):
+            raise ValueError(
+                "Invalid from_date and to_date. Must be of type datetime.datetime"
+                " and have tzinfo = datetime.timezone.utc"
+            )
+        else:
+            schedule_list = []
+            cron_iterator = AWSCron(cron)
+            start = from_date.replace(second=0, microsecond=0) - datetime.timedelta(seconds=1)
+            stop = to_date.replace(second=0, microsecond=0)
+
+            while start is not None and start <= stop:
+                start = cron_iterator.occurrence(start).next()
+                if start is None or start > stop:
+                    break
+                schedule_list.append(start)
+
+            # If exclude_ends=True ,
+            # remove first & last element from the list if they match from_date & to_date
+            if exclude_ends:
+                if schedule_list[0] == from_date.replace(second=0, microsecond=0):
+                    schedule_list.pop(0)
+                if schedule_list[-1] == to_date.replace(second=0, microsecond=0):
+                    schedule_list.pop()
+            return schedule_list

aws_croniter-0.1.0/src/aws_croniter/exceptions.py

@@ -0,0 +1,40 @@
+class AWSCronExpressionError(ValueError):
+    """Base exception for errors in AWS cron expressions."""
+
+    pass
+
+
+class AWSCronExpressionMinuteError(AWSCronExpressionError):
+    """Exception raised for invalid minute values in an AWS cron expression."""
+
+    pass
+
+
+class AWSCronExpressionHourError(AWSCronExpressionError):
+    """Exception raised for invalid hour values in an AWS cron expression."""
+
+    pass
+
+
+class AWSCronExpressionMonthError(AWSCronExpressionError):
+    """Exception raised for invalid month values in an AWS cron expression."""
+
+    pass
+
+
+class AWSCronExpressionYearError(AWSCronExpressionError):
+    """Exception raised for invalid year values in an AWS cron expression."""
+
+    pass
+
+
+class AWSCronExpressionDayOfMonthError(AWSCronExpressionError):
+    """Exception raised for invalid day-of-month values in an AWS cron expression."""
+
+    pass
+
+
+class AWSCronExpressionDayOfWeekError(AWSCronExpressionError):
+    """Exception raised for invalid day-of-week values in an AWS cron expression."""
+
+    pass

aws_croniter-0.1.0/src/aws_croniter/occurrence.py

@@ -0,0 +1,173 @@
+import datetime
+import math
+
+from dateutil.relativedelta import relativedelta
+
+from aws_croniter.utils import DateUtils
+from aws_croniter.utils import SequenceUtils
+from aws_croniter.utils import TimeUtils
+
+
+class Occurrence:
+    def __init__(self, AWSCron, utc_datetime):
+        if utc_datetime.tzinfo is None or utc_datetime.tzinfo != datetime.timezone.utc:
+            raise Exception("Occurrence utc_datetime must have tzinfo == datetime.timezone.utc")
+        self.utc_datetime = utc_datetime
+        self.cron = AWSCron
+        self.iter = 0
+
+    def __find_once(self, parsed, datetime_from):
+        if self.iter > 10:
+            raise Exception(f"AwsCronParser : this shouldn't happen, but iter {self.iter} > 10 ")
+        self.iter += 1
+        current_year = datetime_from.year
+        current_month = datetime_from.month
+        current_day_of_month = datetime_from.day
+        current_hour = datetime_from.hour
+        current_minute = datetime_from.minute
+
+        year = SequenceUtils.array_find_first(parsed.years, lambda c: c >= current_year)
+        if year is None:
+            return None
+
+        month = SequenceUtils.array_find_first(
+            parsed.months, lambda c: c >= (current_month if year == current_year else 1)
+        )
+        if not month:
+            return self.__find_once(parsed, datetime.datetime(year + 1, 1, 1, tzinfo=datetime.timezone.utc))
+
+        is_same_month = True if year == current_year and month == current_month else False
+        p_days_of_month = parsed.days_of_month
+        is_w_in_current_month = None
+
+        if len(p_days_of_month) == 0:
+            p_days_of_month = DateUtils.get_days_of_month_from_days_of_week(year, month, parsed.days_of_week)
+        elif p_days_of_month[0] == "L":
+            p_days_of_month = DateUtils.get_days_of_month_for_L(year, month, int(p_days_of_month[1]))
+        elif p_days_of_month[0] == "W":
+            if DateUtils.is_day_in_month(year, month, int(p_days_of_month[1])):
+                p_days_of_month = DateUtils.get_days_of_month_for_W(year, month, int(p_days_of_month[1]))
+                is_w_in_current_month = True
+            else:
+                is_w_in_current_month = False
+        if is_w_in_current_month is not None and not is_w_in_current_month:
+            day_of_month = False
+        else:
+            day_of_month = SequenceUtils.array_find_first(
+                p_days_of_month, lambda c: c >= (current_day_of_month if is_same_month else 1)
+            )
+        if not day_of_month:
+            dt = datetime.datetime(year, month, 1, tzinfo=datetime.timezone.utc) + relativedelta(months=+1)
+            return self.__find_once(parsed, dt)
+
+        is_same_date = is_same_month and day_of_month == current_day_of_month
+
+        hour = SequenceUtils.array_find_first(parsed.hours, lambda c: c >= (current_hour if is_same_date else 0))
+        if hour is None:
+            dt = datetime.datetime(year, month, day_of_month, tzinfo=datetime.timezone.utc) + relativedelta(days=+1)
+            return self.__find_once(parsed, dt)
+
+        minute = SequenceUtils.array_find_first(
+            parsed.minutes, lambda c: c >= (current_minute if is_same_date and hour == current_hour else 0)
+        )
+        if minute is None:
+            dt = datetime.datetime(year, month, day_of_month, hour, tzinfo=datetime.timezone.utc) + relativedelta(
+                hours=+1
+            )
+            return self.__find_once(parsed, dt)
+
+        return datetime.datetime(year, month, day_of_month, hour, minute, tzinfo=datetime.timezone.utc)
+
+    def __find_prev_once(self, parsed, datetime_from: datetime):
+        if self.iter > 10:
+            raise Exception("AwsCronParser : this shouldn't happen, but iter > 10")
+        self.iter += 1
+        current_year = datetime_from.year
+        current_month = datetime_from.month
+        current_day_of_month = datetime_from.day
+        current_hour = datetime_from.hour
+        current_minute = datetime_from.minute
+
+        year = SequenceUtils.array_find_last(parsed.years, lambda c: c <= current_year)
+        if year is None:
+            return None
+
+        month = SequenceUtils.array_find_last(
+            parsed.months, lambda c: c <= (current_month if year == current_year else 12)
+        )
+        if not month:
+            dt = datetime.datetime(year, 1, 1, tzinfo=datetime.timezone.utc) + relativedelta(seconds=-1)
+            return self.__find_prev_once(parsed, dt)
+
+        is_same_month = True if year == current_year and month == current_month else False
+        p_days_of_month = parsed.days_of_month
+        is_w_in_current_month = None
+
+        if len(p_days_of_month) == 0:
+            p_days_of_month = DateUtils.get_days_of_month_from_days_of_week(year, month, parsed.days_of_week)
+        elif p_days_of_month[0] == "L":
+            p_days_of_month = DateUtils.get_days_of_month_for_L(year, month, int(p_days_of_month[1]))
+        elif p_days_of_month[0] == "W":
+            if DateUtils.is_day_in_month(year, month, int(p_days_of_month[1])):
+                p_days_of_month = DateUtils.get_days_of_month_for_W(year, month, int(p_days_of_month[1]))
+                is_w_in_current_month = True
+            else:
+                is_w_in_current_month = False
+        if is_w_in_current_month is not None and not is_w_in_current_month:
+            day_of_month = False
+        else:
+            day_of_month = SequenceUtils.array_find_last(
+                p_days_of_month, lambda c: c <= (current_day_of_month if is_same_month else 31)
+            )
+
+        if not day_of_month:
+            dt = datetime.datetime(year, month, 1, tzinfo=datetime.timezone.utc) + relativedelta(seconds=-1)
+            return self.__find_prev_once(parsed, dt)
+
+        is_same_date = is_same_month and day_of_month == current_day_of_month
+
+        hour = SequenceUtils.array_find_last(parsed.hours, lambda c: c <= (current_hour if is_same_date else 23))
+        if hour is None:
+            dt = datetime.datetime(year, month, day_of_month, tzinfo=datetime.timezone.utc) + relativedelta(seconds=-1)
+            return self.__find_prev_once(parsed, dt)
+
+        minute = SequenceUtils.array_find_last(
+            parsed.minutes, lambda c: c <= (current_minute if is_same_date and hour == current_hour else 59)
+        )
+        if minute is None:
+            dt = datetime.datetime(year, month, day_of_month, hour, tzinfo=datetime.timezone.utc) + relativedelta(
+                seconds=-1
+            )
+            return self.__find_prev_once(parsed, dt)
+
+        return datetime.datetime(year, month, day_of_month, hour, minute, tzinfo=datetime.timezone.utc)
+
+    def next(self, datetime_inclusive=False):
+        """
+        Generate the next occurrence after the current time.
+
+        :param datetime_inclusive: If True, include the current time if it matches a valid execution.
+        :return: The next occurrence as a datetime object.
+        """
+        self.iter = 0
+        from_epoch = (math.floor(TimeUtils.datetime_to_millisec(self.utc_datetime) / 60000.0) + 1) * 60000
+        if datetime_inclusive:
+            # Do not add extra minute, include current time
+            from_epoch = math.floor(TimeUtils.datetime_to_millisec(self.utc_datetime) / 60000.0) * 60000
+        dt = datetime.datetime.fromtimestamp(from_epoch / 1000.0, tz=datetime.timezone.utc)
+        return self.__find_once(self.cron, dt)
+
+    def prev(self, datetime_inclusive=False):
+        """
+        Generate the prev before the occurrence date value
+
+        :param datetime_inclusive: If True, include the current time if it matches a valid execution.
+        :return: The next occurrence as a datetime object.
+        """
+        self.iter = 0
+        from_epoch = (math.floor(TimeUtils.datetime_to_millisec(self.utc_datetime) / 60000.0) - 1) * 60000
+        if datetime_inclusive:
+            # Do not subtract extra minute, include current time
+            from_epoch = math.floor(TimeUtils.datetime_to_millisec(self.utc_datetime) / 60000.0) * 60000
+        dt = datetime.datetime.fromtimestamp(from_epoch / 1000.0, tz=datetime.timezone.utc)
+        return self.__find_prev_once(self.cron, dt)

aws_croniter-0.1.0/src/aws_croniter/utils.py

@@ -0,0 +1,165 @@
+import calendar
+import datetime
+
+from dateutil.relativedelta import relativedelta
+
+
+class RegexUtils:
+    MINUTE_VALUES = r"(0?[0-9]|[1-5][0-9])"  # [0]0-59
+    HOUR_VALUES = r"(0?[0-9]|1[0-9]|2[0-3])"  # [0]0-23
+    MONTH_OF_DAY_VALUES = r"(0?[1-9]|[1-2][0-9]|3[0-1])"  # [0]1-31
+    MONTH_VALUES = r"(?i:0?[1-9]|1[0-2]|JAN|FEB|MAR|APR|MAY|JUN|JUL|AUG|SEP|OCT|NOV|DEC)"  # [0]1-12 or JAN-DEC
+    DAY_OF_WEEK_VALUES = r"(?i:[1-7]|SUN|MON|TUE|WED|THU|FRI|SAT)"  # 1-7 or SAT-SUN
+    DAY_OF_WEEK_HASH = rf"({DAY_OF_WEEK_VALUES}#[1-5])"  # Day of the week in the Nth week of the month
+    YEAR_VALUES = r"((19[7-9][0-9])|(2[0-1][0-9][0-9]))"  # 1970-2199
+
+    @classmethod
+    def range_regex(cls, values: str) -> str:
+        return rf"({values}|(\*\-{values})|({values}\-{values})|({values}\-\*))"  # v , *-v , v-v or v-*
+
+    @classmethod
+    def list_range_regex(cls, values: str) -> str:
+        range_ = cls.range_regex(values)
+        return rf"({range_}(\,{range_})*)"  # One or more ranges separated by a comma
+
+    @classmethod
+    def slash_regex(cls, values: str) -> str:
+        range_ = cls.range_regex(values)
+        return rf"((\*|{range_}|{values})\/{values})"
+        # Slash can be preceded by *, range, or a valid value and must be followed by a natural
+        # number as the increment.
+
+    @classmethod
+    def list_slash_regex(cls, values: str) -> str:
+        slash = cls.slash_regex(values)
+        slash_or_range = rf"({slash}|{cls.range_regex(values)})"
+        return rf"({slash_or_range}(\,{slash_or_range})*)"  # One or more separated by a comma
+
+    @classmethod
+    def common_regex(cls, values: str) -> str:
+        return rf"({cls.list_range_regex(values)}|\*|{cls.list_slash_regex(values)})"  # values , - * /
+
+    @classmethod
+    def minute_regex(cls) -> str:
+        return rf"^({cls.common_regex(cls.MINUTE_VALUES)})$"  # values , - * /
+
+    @classmethod
+    def hour_regex(cls) -> str:
+        return rf"^({cls.common_regex(cls.HOUR_VALUES)})$"  # values , - * /
+
+    @classmethod
+    def day_of_month_regex(cls) -> str:
+        return (
+            rf"^({cls.common_regex(cls.MONTH_OF_DAY_VALUES)}|\?|L|L-[1-9]|[1-2][0-9]|3[0-1]|LW|{cls.MONTH_OF_DAY_VALUES}W)$"
+            # values , - * / ? L W
+        )
+
+    @classmethod
+    def month_regex(cls):
+        return rf"^({cls.common_regex(cls.MONTH_VALUES)})$"  # values , - * /
+
+    @classmethod
+    def day_of_week_regex(cls):
+        range_list = cls.list_range_regex(cls.DAY_OF_WEEK_VALUES)
+        return rf"^({range_list}|\*|\?|{cls.DAY_OF_WEEK_VALUES}L|L|L-[1-7]|{cls.DAY_OF_WEEK_HASH})$"
+        # values , - * ? L #
+
+    @classmethod
+    def year_regex(cls):
+        return rf"^({cls.common_regex(cls.YEAR_VALUES)})$"  # values , - * /
+
+
+class DateUtils:
+    @staticmethod
+    def python_to_aws_day_of_week(python_day_of_week):
+        """Convert Python day of week (Mon=0) to AWS day of week (Mon=2)."""
+        mapping = {0: 2, 1: 3, 2: 4, 3: 5, 4: 6, 5: 7, 6: 1}
+        return mapping[python_day_of_week]
+
+    @staticmethod
+    def get_days_of_month_from_days_of_week(year, month, days_of_week):
+        """Get all days of the month that match the given days of the week."""
+        days_of_month = []
+        index = 0  # only for "#" use case
+        no_of_days_in_month = calendar.monthrange(year, month)[1]
+        for i in range(1, no_of_days_in_month + 1, 1):
+            this_date = datetime.datetime(year, month, i, tzinfo=datetime.timezone.utc)
+            if days_of_week[0] == "L":
+                if days_of_week[1] == DateUtils.python_to_aws_day_of_week(this_date.weekday()):
+                    same_day_next_week = datetime.datetime.fromtimestamp(
+                        int(this_date.timestamp()) + 7 * 24 * 3600, tz=datetime.timezone.utc
+                    )
+                    if same_day_next_week.month != this_date.month:
+                        return [i]
+            elif days_of_week[0] == "#":
+                if days_of_week[1] == DateUtils.python_to_aws_day_of_week(this_date.weekday()):
+                    index += 1
+                if days_of_week[2] == index:
+                    return [i]
+            elif DateUtils.python_to_aws_day_of_week(this_date.weekday()) in days_of_week:
+                days_of_month.append(i)
+        return days_of_month
+
+    @staticmethod
+    def get_days_of_month_for_L(year, month, days_before):
+        """Get the last day of the month adjusted by a specific number of days."""
+        for i in range(31, 28 - 1, -1):
+            this_date = datetime.datetime(year, month, 1, tzinfo=datetime.timezone.utc) + relativedelta(days=i - 1)
+            if this_date.month == month:
+                return [i - days_before]
+
+    @staticmethod
+    def get_days_of_month_for_W(year, month, day):
+        """
+        Get the closest weekday for the specified day of the month.
+        Adjusts for weekends and ensures the date is within the month.
+        """
+        offset = SequenceUtils.array_find_first([0, 1, -1, 2, -2], lambda c: DateUtils.is_weekday(year, month, day + c))
+        if offset is None:
+            return []
+        result = day + offset
+        return [result]
+
+    @staticmethod
+    def is_weekday(year, month, day):
+        """Check if a specific day is a weekday (Mon-Fri)."""
+        if day < 1 or day > 31:
+            return False
+        this_date = datetime.datetime(year, month, 1, tzinfo=datetime.timezone.utc) + relativedelta(days=day - 1)
+        if this_date.month != month or this_date.year != year:
+            return False
+        return this_date.weekday() >= 0 and this_date.weekday() <= 4  # Mon=0, Fri=4
+
+    @staticmethod
+    def is_day_in_month(year, month, test_day):
+        """Check if a specific day exists in a given month."""
+        try:
+            datetime.datetime(year, month, test_day, tzinfo=datetime.timezone.utc)
+            return True
+        except ValueError:
+            return False
+
+
+class TimeUtils:
+    @staticmethod
+    def datetime_to_millisec(dt_obj):
+        """Convert a datetime object to milliseconds since epoch."""
+        return round(dt_obj.timestamp() * 1000)
+
+
+class SequenceUtils:
+    @staticmethod
+    def array_find_first(sequence, function):
+        """Find the first element in a sequence that satisfies the given function."""
+        for item in sequence:
+            if function(item):
+                return item
+        return None
+
+    @staticmethod
+    def array_find_last(sequence, function):
+        """Find the last element in a sequence that satisfies the given function."""
+        for item in reversed(sequence):
+            if function(item):
+                return item
+        return None