quartz-cron-checker 0.1.0__tar.gz

quartz_cron_checker-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Jessica Smith
+
+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.

quartz_cron_checker-0.1.0/PKG-INFO

@@ -0,0 +1,57 @@
+Metadata-Version: 2.4
+Name: quartz-cron-checker
+Version: 0.1.0
+Summary: Simple Python library to check if a Quartz cron expression is valid.
+Author-email: Jessica Smith <j.smith.git1@gmail.com>
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# quartz-cron-checker
+
+**quartz-cron-checker** is a lightweight, strict validator for [Quartz-style cron expressions](https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html) in Python.
+
+It ensures all parts of the cron string conform to the Quartz cron spec—including support for special characters, named values, and mutual exclusivity of day-of-month and day-of-week.
+
+## Features
+
+- ✅ Full support for 6- or 7-field Quartz cron expressions (`second minute hour day-of-month month day-of-week [year]`)
+- ✅ Literal handling (`*`, `?`, `L`, `W`, `#`)
+- ✅ Named months (`JAN`, `FEB`, etc.) and days (`MON`, `TUE`, etc.)
+- ✅ Detailed error messages and exceptions
+- ✅ Clean object-oriented API
+- ✅ Extensible field-level validation
+
+## Installation
+
+```bash
+pip install quartz-cron-checker
+```
+
+## Usage
+
+Calling `validate` will raise an exception if the cron string is invalid. The method will return `True` otherwise.
+
+```python
+from quartz_cron_checker import QuartzCronChecker
+
+# Parse and validate a cron string
+cron = QuartzCronChecker.from_cron_string("0 0 12 ? * MON-FRI")
+cron.validate()  # Raises if invalid
+
+print(str(cron))  # "0 0 12 ? * MON-FRI"
+```
+
+You can also validate either a whole cron string or individual fields without creating an object:
+```python
+from quartz_cron_checker import validate_cron_string, validate_year, validate_second
+
+# Validate a full cron string
+validate_cron_string("0 0 12 ? * MON-FRI")  # Raises if invalid
+
+# Validate individual fields
+validate_second("0")  # Raises if invalid
+
+validate_year("2023")  # Raises if invalid
+```

quartz_cron_checker-0.1.0/README.md

@@ -0,0 +1,47 @@
+# quartz-cron-checker
+
+**quartz-cron-checker** is a lightweight, strict validator for [Quartz-style cron expressions](https://www.quartz-scheduler.org/documentation/quartz-2.3.0/tutorials/crontrigger.html) in Python.
+
+It ensures all parts of the cron string conform to the Quartz cron spec—including support for special characters, named values, and mutual exclusivity of day-of-month and day-of-week.
+
+## Features
+
+- ✅ Full support for 6- or 7-field Quartz cron expressions (`second minute hour day-of-month month day-of-week [year]`)
+- ✅ Literal handling (`*`, `?`, `L`, `W`, `#`)
+- ✅ Named months (`JAN`, `FEB`, etc.) and days (`MON`, `TUE`, etc.)
+- ✅ Detailed error messages and exceptions
+- ✅ Clean object-oriented API
+- ✅ Extensible field-level validation
+
+## Installation
+
+```bash
+pip install quartz-cron-checker
+```
+
+## Usage
+
+Calling `validate` will raise an exception if the cron string is invalid. The method will return `True` otherwise.
+
+```python
+from quartz_cron_checker import QuartzCronChecker
+
+# Parse and validate a cron string
+cron = QuartzCronChecker.from_cron_string("0 0 12 ? * MON-FRI")
+cron.validate()  # Raises if invalid
+
+print(str(cron))  # "0 0 12 ? * MON-FRI"
+```
+
+You can also validate either a whole cron string or individual fields without creating an object:
+```python
+from quartz_cron_checker import validate_cron_string, validate_year, validate_second
+
+# Validate a full cron string
+validate_cron_string("0 0 12 ? * MON-FRI")  # Raises if invalid
+
+# Validate individual fields
+validate_second("0")  # Raises if invalid
+
+validate_year("2023")  # Raises if invalid
+```

quartz_cron_checker-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "quartz-cron-checker"
+version = "0.1.0"
+description = "Simple Python library to check if a Quartz cron expression is valid."
+authors = [{ name = "Jessica Smith", email = "j.smith.git1@gmail.com" }]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = []
+
+[dependency-groups]
+test = ["hypothesis>=6.131.30", "pytest>=8.3.5"]
+
+
+[tool.uv]
+default-groups = ["test"]
+
+[build-system]
+requires = ["setuptools >= 80"]
+build-backend = "setuptools.build_meta"

quartz_cron_checker-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

quartz_cron_checker-0.1.0/src/quartz_cron_checker/__init__.py

@@ -0,0 +1,25 @@
+from .checker import (
+    QuartzCronChecker,
+    validate_cron_string,
+    validate_day_of_month,
+    validate_day_of_month_or_week,
+    validate_day_of_week,
+    validate_hour,
+    validate_minute,
+    validate_month,
+    validate_second,
+    validate_year,
+)
+
+__all__ = [
+    "QuartzCronChecker",
+    "validate_cron_string",
+    "validate_day_of_month",
+    "validate_day_of_month_or_week",
+    "validate_day_of_week",
+    "validate_hour",
+    "validate_minute",
+    "validate_month",
+    "validate_second",
+    "validate_year",
+]

quartz_cron_checker-0.1.0/src/quartz_cron_checker/checker.py

@@ -0,0 +1,271 @@
+from dataclasses import dataclass
+from typing import Literal
+
+from quartz_cron_checker.exceptions import InvalidCronStructureError
+from quartz_cron_checker.validators import validate_day_of_month_or_week
+
+from .field_configs import (
+    DAY_OF_MONTH_CONFIG,
+    DAY_OF_WEEK_CONFIG,
+    HOUR_CONFIG,
+    MINUTE_CONFIG,
+    MONTH_CONFIG,
+    SECOND_CONFIG,
+    YEAR_CONFIG,
+)
+
+CRON_TEMPLATE_NO_YEAR = "{second} {minute} {hour} {day_of_month} {month} {day_of_week}"
+CRON_TEMPLATE = CRON_TEMPLATE_NO_YEAR + " {year}"
+REQUIRED_PARTS = ["second", "minute", "hour", "day_of_month", "month", "day_of_week"]
+
+
+@dataclass
+class QuartzCronChecker:
+    second: str
+    minute: str
+    hour: str
+    day_of_month: str
+    month: str
+    day_of_week: str
+    year: str | None = None
+    cron_string: str | None = None
+
+    def __post_init__(self):
+        self.second = self.second.replace(" ", "")
+        self.minute = self.minute.replace(" ", "")
+        self.hour = self.hour.replace(" ", "")
+        self.day_of_month = self.day_of_month.replace(" ", "")
+        self.month = self.month.replace(" ", "")
+        self.day_of_week = self.day_of_week.replace(" ", "")
+        self.year = self.year.replace(" ", "") if self.year else None
+
+    def __repr__(self) -> str:
+        return f"<QuartzCronChecker {self!s}>"
+
+    def __str__(self) -> str:
+        parts = {
+            "second": self.second,
+            "minute": self.minute,
+            "hour": self.hour,
+            "day_of_month": self.day_of_month,
+            "month": self.month,
+            "day_of_week": self.day_of_week,
+        }
+
+        if self.year is not None:
+            parts["year"] = self.year
+            return CRON_TEMPLATE.format(**parts)
+
+        return CRON_TEMPLATE_NO_YEAR.format(**parts)
+
+    def validate(self) -> Literal[True]:
+        """Validate the cron string.
+
+        This method performs the following checks:
+            1. Ensuring required parts are present.
+            2. Checking mutual exclusivity of day_of_month and day_of_week.
+            3. Validating each part using its corresponding field config.
+
+        Raises:
+            InvalidCronStructureError: If the cron string is missing required parts or has invalid structure.
+            InvalidCronPartError: If any part of the cron string is invalid.
+            ValueOutOfBoundsError: If any part of the cron string is out of bounds.
+            IncrementOutOfBoundsError: If an increment value is out of bounds.
+            RangeOutOfBoundsError: If a range is out of bounds.
+            RangeIncrementOutOfBoundsError: If a range with increment is out of bounds.
+            SpecificsOutOfBoundsError: If specific values are out of bounds.
+
+        Returns:
+            Literal[True]: Returns True if the cron string is valid.
+        """
+        if not all(getattr(self, part) for part in REQUIRED_PARTS):
+            missing_parts = [part for part in REQUIRED_PARTS if not getattr(self, part)]
+            raise InvalidCronStructureError(f"Missing required parts in cron string: {', '.join(missing_parts)}")
+
+        validate_day_of_month_or_week(self.day_of_month, self.day_of_week)
+
+        for config, value in [
+            (SECOND_CONFIG, self.second),
+            (MINUTE_CONFIG, self.minute),
+            (HOUR_CONFIG, self.hour),
+            (DAY_OF_MONTH_CONFIG, self.day_of_month),
+            (MONTH_CONFIG, self.month),
+            (DAY_OF_WEEK_CONFIG, self.day_of_week),
+        ]:
+            config.validate(value)
+
+        if self.year:
+            YEAR_CONFIG.validate(self.year)
+
+        return True
+
+    @classmethod
+    def from_cron_string(cls, cron_str: str) -> "QuartzCronChecker":
+        """Convert a cron string to a QuartzCronChecker object.
+
+        Args:
+            cron_str (str): The cron string to convert.
+
+        Returns:
+            QuartzCronChecker: A QuartzCronChecker object with the converted values.
+        """
+        cron_parts = cron_str.strip().split(" ")
+        if len(cron_parts) == 6:
+            # this slightly weird looking syntax makes the type checker happy
+            # we add a None for the year part, since it's not present in 6-part cron strings
+            return cls(*[*cron_parts, None], cron_string=cron_str)
+        if len(cron_parts) == 7:
+            return cls(*cron_parts, cron_string=cron_str)
+
+        raise InvalidCronStructureError(
+            f"Invalid cron string: {cron_str}. Expected 6 or 7 parts, got {len(cron_parts)}."
+        )
+
+    @staticmethod
+    def validate_cron_string(cron_str: str) -> Literal[True]:
+        """Validate a cron string.
+
+        Args:
+            cron_str (str): The cron string to validate.
+
+        Returns:
+            Literal[True]: Returns True if the cron string is valid.
+
+        Raises:
+            InvalidCronStructureError: If the cron string is invalid.
+            InvalidCronPartError: If any part of the cron string is invalid.
+            ValueOutOfBoundsError: If any part of the cron string is out of bounds.
+            IncrementOutOfBoundsError: If an increment value is out of bounds.
+            RangeOutOfBoundsError: If a range is out of bounds.
+            RangeIncrementOutOfBoundsError: If a range with increment is out of bounds.
+            SpecificsOutOfBoundsError: If specific values are out of bounds.
+        """
+        cron = QuartzCronChecker.from_cron_string(cron_str)
+        cron.validate()
+        return True
+
+
+def validate_second(part: str) -> Literal[True]:
+    """Validate the 'second' part of a cron string.
+
+    Args:
+        part (str): The 'second' part of the cron string to validate.
+
+    Returns:
+        Literal[True]: Returns True if validation is successful.
+
+    Raises:
+        InvalidCronPartError: If the 'second' part is invalid - exact error depends on the specific validation failure.
+    """
+    return SECOND_CONFIG.validate(part)
+
+
+def validate_minute(part: str) -> Literal[True]:
+    """Validate the 'minute' part of a cron string.
+
+    Args:
+        part (str): The 'minute' part of the cron string to validate.
+
+    Returns:
+        Literal[True]: Returns True if validation is successful.
+
+    Raises:
+        InvalidCronPartError: If the part is invalid - exact error depends on the specific validation failure.
+    """
+    return MINUTE_CONFIG.validate(part)
+
+
+def validate_hour(part: str) -> Literal[True]:
+    """Validate the 'hour' part of a cron string.
+
+    Args:
+        part (str): The 'hour' part of the cron string to validate.
+
+    Returns:
+        Literal[True]: Returns True if validation is successful.
+
+    Raises:
+        InvalidCronPartError: If the part is invalid - exact error depends on the specific validation failure.
+    """
+    return HOUR_CONFIG.validate(part)
+
+
+def validate_day_of_month(part: str) -> Literal[True]:
+    """Validate the 'day_of_month' part of a cron string.
+
+    Args:
+        part (str): The 'day_of_month' part of the cron string to validate.
+
+    Returns:
+        Literal[True]: Returns True if validation is successful.
+
+    Raises:
+        InvalidCronPartError: If the part is invalid - exact error depends on the specific validation failure.
+    """
+    return DAY_OF_MONTH_CONFIG.validate(part)
+
+
+def validate_month(part: str) -> Literal[True]:
+    """Validate the 'month' part of a cron string.
+
+    Args:
+        part (str): The 'month' part of the cron string to validate.
+
+    Returns:
+        Literal[True]: Returns True if validation is successful.
+
+    Raises:
+        InvalidCronPartError: If the part is invalid - exact error depends on the specific validation failure.
+    """
+    return MONTH_CONFIG.validate(part)
+
+
+def validate_day_of_week(part: str) -> Literal[True]:
+    """Validate the 'day_of_week' part of a cron string.
+
+    Args:
+        part (str): The 'day_of_week' part of the cron string to validate.
+
+    Returns:
+        Literal[True]: Returns True if validation is successful.
+
+    Raises:
+        InvalidCronPartError: If the part is invalid - exact error depends on the specific validation failure.
+    """
+    return DAY_OF_WEEK_CONFIG.validate(part)
+
+
+def validate_year(part: str) -> Literal[True]:
+    """Validate the 'year' part of a cron string.
+
+    Args:
+        part (str): The 'year' part of the cron string to validate.
+
+    Returns:
+        Literal[True]: Returns True if validation is successful.
+
+    Raises:
+        InvalidCronPartError: If the part is invalid - exact error depends on the specific validation failure.
+    """
+    return YEAR_CONFIG.validate(part)
+
+
+def validate_cron_string(cron_str: str) -> Literal[True]:
+    """Validate a cron string.
+
+    Args:
+        cron_str (str): The cron string to validate.
+
+    Returns:
+        Literal[True]: Returns True if the cron string is valid.
+
+    Raises:
+        InvalidCronStructureError: If the cron string is invalid.
+        InvalidCronPartError: If any part of the cron string is invalid.
+        ValueOutOfBoundsError: If any part of the cron string is out of bounds.
+        IncrementOutOfBoundsError: If an increment value is out of bounds.
+        RangeOutOfBoundsError: If a range is out of bounds.
+        RangeIncrementOutOfBoundsError: If a range with increment is out of bounds.
+        SpecificsOutOfBoundsError: If specific values are out of bounds.
+    """
+    return QuartzCronChecker.validate_cron_string(cron_str)

quartz_cron_checker-0.1.0/src/quartz_cron_checker/constants.py

@@ -0,0 +1,40 @@
+import calendar
+import re
+
+SINGLE_LITERAL_PATTERN = re.compile(r"^\d+$")
+WILDCARD_PATTERN = re.compile(r"^\*$")
+INCREMENT_PATTERN = re.compile(r"^(\*|\d+)(/\d+)$")
+RANGE_PATTERN = re.compile(r"^\d+-\d+$")
+RANGE_WITH_INCREMENT_PATTERN = re.compile(r"^\d+-\d+/\d+$")
+LIST_OF_DIGITS_PATTERN = re.compile(r"^\d+(,\d+)+$")
+LIST_OF_STRINGS_PATTERN = re.compile(r"^[A-Z]{3}(,[A-Z]{3})+$", re.IGNORECASE)
+
+
+# DOW patterns
+DOW_LIST = list(map(str.upper, calendar.day_abbr))
+DOW_OR_PATTERN = f"({'|'.join(DOW_LIST)})"
+
+DOW_OCCURRENCE_PATTERN = re.compile(r"\d+#\d+")
+LAST_DOW_IN_MONTH_PATTERN = re.compile(r"\d+L", re.IGNORECASE)
+DOW_RANGE_PATTERN = re.compile(f"^{DOW_OR_PATTERN}-{DOW_OR_PATTERN}$", re.IGNORECASE)
+SPECIFIC_DOW_PATTERN = re.compile(f"^{DOW_OR_PATTERN}(,{DOW_OR_PATTERN})*$", re.IGNORECASE)
+
+# Month patterns
+MONTH_LIST = list(map(str.upper, calendar.month_abbr))[1:]
+
+MONTH_OR_PATTERN = f"({'|'.join(MONTH_LIST)})"
+MONTH_RANGE_PATTERN = re.compile(f"^{MONTH_OR_PATTERN}-{MONTH_OR_PATTERN}$", re.IGNORECASE)
+SPECIFIC_MONTH_PATTERN = re.compile(f"^{MONTH_OR_PATTERN}(,{MONTH_OR_PATTERN})*$", re.IGNORECASE)
+
+# Day of month patterns
+LAST_DAY_OF_MONTH = "L"
+LAST_WEEKDAY_OF_MONTH = "LW"
+LAST_N_DAYS_OF_MONTH_PATTERN = re.compile(r"^L-\d+$", re.IGNORECASE)
+NEAREST_WEEKDAY_DAY_OF_MONTH_PATTERN = re.compile(r"^\d+W$", re.IGNORECASE)
+
+DEFAULT_NUMERIC_PATTERNS = (
+    RANGE_PATTERN,  # e.g. 1-31
+    INCREMENT_PATTERN,  # e.g. 1/2
+    RANGE_WITH_INCREMENT_PATTERN,  # e.g. 1-31/2
+    LIST_OF_DIGITS_PATTERN,  # e.g. 1,2,3
+)

quartz_cron_checker-0.1.0/src/quartz_cron_checker/exceptions.py

@@ -0,0 +1,107 @@
+import re
+from collections.abc import Sequence
+
+
+class CronValidationError(ValueError):
+    """Base class for all cron validation errors."""
+
+
+class InvalidCronStructureError(CronValidationError):
+    """Raised when the overall structure of a cron string is invalid.
+
+    This includes cases like:
+    - wrong number of parts
+    - mutually exclusive fields both set to values
+    """
+
+    def __init__(self, message: str):
+        super().__init__(message)
+
+
+class InvalidCronPartError(CronValidationError):
+    part_name: str
+    part_value: str | None
+
+    def __init__(self, part_name: str, part_value: str | None, message: str) -> None:
+        self.part_name = part_name
+        self.part_value = part_value
+        super().__init__(f"[{part_name}={part_value}] {message}")
+
+
+class ValueOutOfBoundsError(InvalidCronPartError):
+    def __init__(self, part_name: str, part_value: str, min_value: int, max_value: int) -> None:
+        msg = f"Value {part_value} is out of bounds ({min_value}-{max_value})"
+        super().__init__(part_name, part_value, msg)
+
+
+class IncrementOutOfBoundsError(InvalidCronPartError):
+    def __init__(self, part_name: str, part_value: str, increment_max: int) -> None:
+        msg = f"Increment is out of bounds (1-{increment_max})"
+        super().__init__(part_name, part_value, msg)
+
+
+class RangeOutOfBoundsError(InvalidCronPartError):
+    def __init__(
+        self,
+        part_name: str,
+        part_value: str,
+        start: int,
+        end: int,
+        min_value: int,
+        max_value: int,
+    ) -> None:
+        msg = f"Range {start}-{end} is out of bounds ({min_value}-{max_value})"
+        super().__init__(part_name, part_value, msg)
+
+
+class RangeIncrementOutOfBoundsError(InvalidCronPartError):
+    def __init__(
+        self,
+        part_name: str,
+        part_value: str,
+        start: int,
+        end: int,
+        increment: int,
+        min_value: int,
+        max_value: int,
+        increment_max: int,
+    ) -> None:
+        msg = (
+            f"Range with increment {start}-{end}/{increment} is out of bounds "
+            f"({min_value}-{max_value}, 1-{increment_max})"
+        )
+        super().__init__(part_name, part_value, msg)
+
+
+class SpecificsOutOfBoundsError(InvalidCronPartError):
+    def __init__(
+        self,
+        part_name: str,
+        part_value: str,
+        values: Sequence[str],
+        min_value: int,
+        max_value: int,
+    ) -> None:
+        joined = ", ".join(values)
+        msg = f"Specific values {joined} are out of bounds ({min_value}-{max_value})"
+        super().__init__(part_name, part_value, msg)
+
+
+class PatternOrLiteralMatchError(InvalidCronPartError):
+    def __init__(
+        self,
+        part_name: str,
+        part_value: str,
+        patterns: Sequence[re.Pattern],
+        literals: set[str],
+    ) -> None:
+        pattern_str = ", ".join(p.pattern for p in patterns)
+        literal_str = ", ".join(literals)
+        msg = f"Part '{part_value}' does not match any allowed pattern ({pattern_str}) or literal ({literal_str})"
+        super().__init__(part_name, part_value, msg)
+
+
+class PartCannotBeNoneError(InvalidCronPartError):
+    def __init__(self, part_name: str) -> None:
+        msg = "Part cannot be None"
+        super().__init__(part_name, None, msg)