schedule-ng 1.3.0__py3-none-any.whl

schedule_ng/__init__.py

@@ -0,0 +1,1001 @@
+"""
+Python job scheduling for humans.
+
+github.com/Adz-ai/schedule-ng, a maintained fork of github.com/dbader/schedule
+
+An in-process scheduler for periodic jobs that uses the builder pattern
+for configuration. Schedule lets you run Python functions (or any other
+callable) periodically at pre-determined intervals using a simple,
+human-friendly syntax.
+
+Inspired by Addam Wiggins' article "Rethinking Cron" [1] and the
+"clockwork" Ruby module [2][3].
+
+Features:
+    - A simple to use API for scheduling jobs.
+    - Very lightweight and no external dependencies.
+    - Excellent test coverage.
+    - Tested on Python 3.9 to 3.14 on Linux, macOS and Windows
+
+Usage:
+    >>> import schedule
+    >>> import time
+
+    >>> def job(message='stuff'):
+    >>>     print("I'm working on:", message)
+
+    >>> schedule.every(10).minutes.do(job)
+    >>> schedule.every(5).to(10).days.do(job)
+    >>> schedule.every().hour.do(job, message='things')
+    >>> schedule.every().day.at("10:30").do(job)
+
+    >>> while True:
+    >>>     schedule.run_pending()
+    >>>     time.sleep(1)
+
+[1] https://adam.herokuapp.com/past/2010/4/13/rethinking_cron/
+[2] https://github.com/Rykian/clockwork
+[3] https://adam.herokuapp.com/past/2010/6/30/replace_cron_with_clockwork/
+"""
+
+from collections.abc import Hashable
+import datetime
+import functools
+import logging
+import random
+import re
+import time
+from typing import Set, List, Optional, Callable, Union
+
+__version__ = "1.3.0"
+
+logger = logging.getLogger("schedule")
+
+
+class ScheduleError(Exception):
+    """Base schedule exception"""
+
+    pass
+
+
+class ScheduleValueError(ScheduleError):
+    """Base schedule value error"""
+
+    pass
+
+
+class IntervalError(ScheduleValueError):
+    """An improper interval was used"""
+
+    pass
+
+
+class CancelJob:
+    """
+    Can be returned from a job to unschedule itself.
+    """
+
+    pass
+
+
+class Scheduler:
+    """
+    Objects instantiated by the :class:`Scheduler <Scheduler>` are
+    factories to create jobs, keep record of scheduled jobs and
+    handle their execution.
+    """
+
+    def __init__(self) -> None:
+        self.jobs: List[Job] = []
+
+    def run_pending(self) -> None:
+        """
+        Run all jobs that are scheduled to run.
+
+        Please note that it is *intended behavior that run_pending()
+        does not run missed jobs*. For example, if you've registered a job
+        that should run every minute and you only call run_pending()
+        in one hour increments then your job won't be run 60 times in
+        between but only once.
+        """
+        runnable_jobs = (job for job in self.jobs if job.should_run)
+        for job in sorted(runnable_jobs):
+            self._run_job(job)
+
+    def run_all(self, delay_seconds: int = 0) -> None:
+        """
+        Run all jobs regardless if they are scheduled to run or not.
+
+        A delay of `delay` seconds is added between each job. This helps
+        distribute system load generated by the jobs more evenly
+        over time.
+
+        :param delay_seconds: A delay added between every executed job
+        """
+        logger.debug(
+            "Running *all* %i jobs with %is delay in between",
+            len(self.jobs),
+            delay_seconds,
+        )
+        for job in self.jobs[:]:
+            self._run_job(job)
+            time.sleep(delay_seconds)
+
+    def get_jobs(self, tag: Optional[Hashable] = None) -> List["Job"]:
+        """
+        Gets scheduled jobs marked with the given tag, or all jobs
+        if tag is omitted.
+
+        :param tag: An identifier used to identify a subset of
+                    jobs to retrieve
+        """
+        if tag is None:
+            return self.jobs[:]
+        else:
+            return [job for job in self.jobs if tag in job.tags]
+
+    def clear(self, tag: Optional[Hashable] = None) -> None:
+        """
+        Deletes scheduled jobs marked with the given tag, or all jobs
+        if tag is omitted.
+
+        :param tag: An identifier used to identify a subset of
+                    jobs to delete
+        """
+        if tag is None:
+            logger.debug("Deleting *all* jobs")
+            del self.jobs[:]
+        else:
+            logger.debug('Deleting all jobs tagged "%s"', tag)
+            self.jobs[:] = (job for job in self.jobs if tag not in job.tags)
+
+    def cancel_job(self, job: "Job") -> None:
+        """
+        Delete a scheduled job.
+
+        :param job: The job to be unscheduled
+        """
+        try:
+            logger.debug('Cancelling job "%s"', job)
+            self.jobs.remove(job)
+        except ValueError:
+            logger.debug('Cancelling not-scheduled job "%s"', job)
+
+    def every(self, interval: int = 1) -> "Job":
+        """
+        Schedule a new periodic job.
+
+        :param interval: A quantity of a certain time unit
+        :return: An unconfigured :class:`Job <Job>`
+        """
+        job = Job(interval, self)
+        return job
+
+    def _run_job(self, job: "Job") -> None:
+        ret = job.run()
+        if isinstance(ret, CancelJob) or ret is CancelJob:
+            self.cancel_job(job)
+
+    def get_next_run(
+        self, tag: Optional[Hashable] = None
+    ) -> Optional[datetime.datetime]:
+        """
+        Datetime when the next job should run.
+
+        :param tag: Filter the next run for the given tag parameter
+
+        :return: A :class:`~datetime.datetime` object
+                 or None if no jobs scheduled
+        """
+        if not self.jobs:
+            return None
+        jobs_filtered = self.get_jobs(tag)
+        if not jobs_filtered:
+            return None
+        return min(jobs_filtered).next_run
+
+    next_run = property(get_next_run)
+
+    @property
+    def idle_seconds(self) -> Optional[float]:
+        """
+        :return: Number of seconds until
+                 :meth:`next_run <Scheduler.next_run>`
+                 or None if no jobs are scheduled
+        """
+        if not self.jobs:
+            return None
+        next_run = min(self.jobs)._next_run
+        if next_run is None:
+            return None
+        # Subtract in UTC: local times can be an hour off around DST changes.
+        return (next_run - _now_utc()).total_seconds()
+
+
+class Job:
+    """
+    A periodic job as used by :class:`Scheduler`.
+
+    :param interval: A quantity of a certain time unit
+    :param scheduler: The :class:`Scheduler <Scheduler>` instance that
+                      this job will register itself with once it has
+                      been fully configured in :meth:`Job.do()`.
+
+    Every job runs at a given fixed time interval that is defined by:
+
+    * a :meth:`time unit <Job.second>`
+    * a quantity of `time units` defined by `interval`
+
+    A job is usually created and returned by :meth:`Scheduler.every`
+    method, which also defines its `interval`.
+    """
+
+    def __init__(self, interval: int, scheduler: Optional[Scheduler] = None):
+        if interval <= 0:
+            raise ScheduleValueError("Interval must be greater than zero")
+        self.interval: int = interval  # pause interval * unit between runs
+        self.latest: Optional[int] = None  # upper limit to the interval
+        self.job_func: Optional[functools.partial] = None  # the job job_func to run
+
+        # time units, e.g. 'minutes', 'hours', ...
+        self.unit: Optional[str] = None
+
+        # optional time at which this job runs
+        self.at_time: Optional[datetime.time] = None
+
+        # optional time zone of the self.at_time field. Only relevant when at_time is not None
+        self.at_time_zone: Optional[datetime.tzinfo] = None
+
+        # datetime of the last run
+        self.last_run: Optional[datetime.datetime] = None
+
+        # datetime of the next run, in UTC. Exposed in local time as next_run.
+        self._next_run: Optional[datetime.datetime] = None
+
+        # Weekday to run the job at. Only relevant when unit is 'weeks'.
+        # For example, when asking 'every week on tuesday' the start_day is 'tuesday'.
+        self.start_day: Optional[str] = None
+
+        # optional time of final run
+        self.cancel_after: Optional[datetime.datetime] = None
+
+        self.tags: Set[Hashable] = set()  # unique set of tags for the job
+        self.scheduler: Optional[Scheduler] = scheduler  # scheduler to register with
+
+    def __lt__(self, other) -> bool:
+        """
+        PeriodicJobs are sortable based on the scheduled time they
+        run next.
+        """
+        return self._next_run < other._next_run
+
+    @property
+    def next_run(self) -> Optional[datetime.datetime]:
+        """
+        Datetime of the next run, as a naive datetime in local time.
+        """
+        if self._next_run is None:
+            return None
+        return self._next_run.astimezone().replace(tzinfo=None)
+
+    @next_run.setter
+    def next_run(self, value: Optional[datetime.datetime]) -> None:
+        # Naive datetimes are interpreted as local time.
+        self._next_run = None if value is None else value.astimezone(_UTC)
+
+    def __str__(self) -> str:
+        if hasattr(self.job_func, "__name__"):
+            job_func_name = self.job_func.__name__  # type: ignore
+        else:
+            job_func_name = repr(self.job_func)
+
+        return ("Job(interval={}, unit={}, {}do={}, args={}, kwargs={})").format(
+            self.interval,
+            self.unit,
+            "" if self.at_time is None else "at={}, ".format(self.at_time),
+            job_func_name,
+            "()" if self.job_func is None else self.job_func.args,
+            "{}" if self.job_func is None else self.job_func.keywords,
+        )
+
+    def __repr__(self):
+        def format_time(t):
+            return t.strftime("%Y-%m-%d %H:%M:%S") if t else "[never]"
+
+        def is_repr(j):
+            return not isinstance(j, Job)
+
+        timestats = "(last run: %s, next run: %s)" % (
+            format_time(self.last_run),
+            format_time(self.next_run),
+        )
+
+        if hasattr(self.job_func, "__name__"):
+            job_func_name = self.job_func.__name__
+        else:
+            job_func_name = repr(self.job_func)
+
+        if self.job_func is not None:
+            args = [repr(x) if is_repr(x) else str(x) for x in self.job_func.args]
+            kwargs = ["%s=%s" % (k, repr(v)) for k, v in self.job_func.keywords.items()]
+            call_repr = job_func_name + "(" + ", ".join(args + kwargs) + ")"
+        else:
+            call_repr = "[None]"
+
+        if self.at_time is not None:
+            return "Every %s %s at %s do %s %s" % (
+                self.interval,
+                self.unit[:-1] if self.interval == 1 and self.unit else self.unit,
+                self.at_time,
+                call_repr,
+                timestats,
+            )
+        else:
+            fmt = (
+                "Every %(interval)s "
+                + ("to %(latest)s " if self.latest is not None else "")
+                + "%(unit)s do %(call_repr)s %(timestats)s"
+            )
+
+            return fmt % dict(
+                interval=self.interval,
+                latest=self.latest,
+                unit=(
+                    self.unit[:-1] if self.interval == 1 and self.unit else self.unit
+                ),
+                call_repr=call_repr,
+                timestats=timestats,
+            )
+
+    @property
+    def second(self):
+        if self.interval != 1:
+            raise IntervalError("Use seconds instead of second")
+        return self.seconds
+
+    @property
+    def seconds(self):
+        self.unit = "seconds"
+        return self
+
+    @property
+    def minute(self):
+        if self.interval != 1:
+            raise IntervalError("Use minutes instead of minute")
+        return self.minutes
+
+    @property
+    def minutes(self):
+        self.unit = "minutes"
+        return self
+
+    @property
+    def hour(self):
+        if self.interval != 1:
+            raise IntervalError("Use hours instead of hour")
+        return self.hours
+
+    @property
+    def hours(self):
+        self.unit = "hours"
+        return self
+
+    @property
+    def day(self):
+        if self.interval != 1:
+            raise IntervalError("Use days instead of day")
+        return self.days
+
+    @property
+    def days(self):
+        self.unit = "days"
+        return self
+
+    @property
+    def week(self):
+        if self.interval != 1:
+            raise IntervalError("Use weeks instead of week")
+        return self.weeks
+
+    @property
+    def weeks(self):
+        self.unit = "weeks"
+        return self
+
+    @property
+    def monday(self):
+        if self.interval != 1:
+            raise IntervalError(
+                "Scheduling .monday() jobs is only allowed for weekly jobs. "
+                "Using .monday() on a job scheduled to run every 2 or more weeks "
+                "is not supported."
+            )
+        self.start_day = "monday"
+        return self.weeks
+
+    @property
+    def tuesday(self):
+        if self.interval != 1:
+            raise IntervalError(
+                "Scheduling .tuesday() jobs is only allowed for weekly jobs. "
+                "Using .tuesday() on a job scheduled to run every 2 or more weeks "
+                "is not supported."
+            )
+        self.start_day = "tuesday"
+        return self.weeks
+
+    @property
+    def wednesday(self):
+        if self.interval != 1:
+            raise IntervalError(
+                "Scheduling .wednesday() jobs is only allowed for weekly jobs. "
+                "Using .wednesday() on a job scheduled to run every 2 or more weeks "
+                "is not supported."
+            )
+        self.start_day = "wednesday"
+        return self.weeks
+
+    @property
+    def thursday(self):
+        if self.interval != 1:
+            raise IntervalError(
+                "Scheduling .thursday() jobs is only allowed for weekly jobs. "
+                "Using .thursday() on a job scheduled to run every 2 or more weeks "
+                "is not supported."
+            )
+        self.start_day = "thursday"
+        return self.weeks
+
+    @property
+    def friday(self):
+        if self.interval != 1:
+            raise IntervalError(
+                "Scheduling .friday() jobs is only allowed for weekly jobs. "
+                "Using .friday() on a job scheduled to run every 2 or more weeks "
+                "is not supported."
+            )
+        self.start_day = "friday"
+        return self.weeks
+
+    @property
+    def saturday(self):
+        if self.interval != 1:
+            raise IntervalError(
+                "Scheduling .saturday() jobs is only allowed for weekly jobs. "
+                "Using .saturday() on a job scheduled to run every 2 or more weeks "
+                "is not supported."
+            )
+        self.start_day = "saturday"
+        return self.weeks
+
+    @property
+    def sunday(self):
+        if self.interval != 1:
+            raise IntervalError(
+                "Scheduling .sunday() jobs is only allowed for weekly jobs. "
+                "Using .sunday() on a job scheduled to run every 2 or more weeks "
+                "is not supported."
+            )
+        self.start_day = "sunday"
+        return self.weeks
+
+    def tag(self, *tags: Hashable):
+        """
+        Tags the job with one or more unique identifiers.
+
+        Tags must be hashable. Duplicate tags are discarded.
+
+        :param tags: A unique list of ``Hashable`` tags.
+        :return: The invoked job instance
+        """
+        if not all(isinstance(tag, Hashable) for tag in tags):
+            raise TypeError("Tags must be hashable")
+        self.tags.update(tags)
+        return self
+
+    def at(self, time_str: str, tz: Union[str, datetime.tzinfo, None] = None) -> "Job":
+        """
+        Specify a particular time that the job should be run at.
+
+        :param time_str: A string in one of the following formats:
+
+            - For daily jobs -> `HH:MM:SS` or `HH:MM`
+            - For hourly jobs -> `MM:SS` or `:MM`
+            - For minute jobs -> `:SS`
+
+            The format must make sense given how often the job is
+            repeating; for example, a job that repeats every minute
+            should not be given a string in the form `HH:MM:SS`. The
+            difference between `:MM` and `:SS` is inferred from the
+            selected time-unit (e.g. `every().hour.at(':30')` vs.
+            `every().minute.at(':30')`).
+
+        :param tz: The timezone that this timestamp refers to. Can be a
+            timezone name such as ``"Europe/Amsterdam"``, or a
+            :class:`datetime.tzinfo` such as a :class:`zoneinfo.ZoneInfo` or
+            pytz timezone. Names are looked up with pytz if it is installed,
+            and with :mod:`zoneinfo` otherwise.
+
+        :return: The invoked job instance
+        """
+        if self.unit not in ("days", "hours", "minutes") and not self.start_day:
+            raise ScheduleValueError(
+                "Invalid unit (valid units are `days`, `hours`, and `minutes`)"
+            )
+
+        if not isinstance(time_str, str):
+            raise TypeError("at() should be passed a string")
+        if self.unit == "days" or self.start_day:
+            if not re.match(r"^[0-2]\d:[0-5]\d(:[0-5]\d)?$", time_str):
+                raise ScheduleValueError(
+                    "Invalid time format for a daily job (valid format is HH:MM(:SS)?)"
+                )
+        if self.unit == "hours":
+            if not re.match(r"^([0-5]\d)?:[0-5]\d$", time_str):
+                raise ScheduleValueError(
+                    "Invalid time format for an hourly job (valid format is (MM)?:SS)"
+                )
+
+        if self.unit == "minutes":
+            if not re.match(r"^:[0-5]\d$", time_str):
+                raise ScheduleValueError(
+                    "Invalid time format for a minutely job (valid format is :SS)"
+                )
+        time_values = time_str.split(":")
+        hour: Union[str, int]
+        minute: Union[str, int]
+        second: Union[str, int]
+        if len(time_values) == 3:
+            hour, minute, second = time_values
+        elif len(time_values) == 2 and self.unit == "minutes":
+            hour = 0
+            minute = 0
+            _, second = time_values
+        elif len(time_values) == 2 and self.unit == "hours" and len(time_values[0]):
+            hour = 0
+            minute, second = time_values
+        else:
+            hour, minute = time_values
+            second = 0
+        if self.unit == "days" or self.start_day:
+            hour = int(hour)
+            if not (0 <= hour <= 23):
+                raise ScheduleValueError(
+                    "Invalid number of hours ({} is not between 0 and 23)".format(hour)
+                )
+        elif self.unit == "hours":
+            hour = 0
+        elif self.unit == "minutes":
+            hour = 0
+            minute = 0
+        hour = int(hour)
+        minute = int(minute)
+        second = int(second)
+        at_time = datetime.time(hour, minute, second)
+        if tz is not None:
+            self.at_time_zone = _parse_timezone(tz)
+
+        self.at_time = at_time
+        return self
+
+    def to(self, latest: int):
+        """
+        Schedule the job to run at an irregular (randomized) interval.
+
+        The job's interval will randomly vary from the value given
+        to  `every` to `latest`. The range defined is inclusive on
+        both ends. For example, `every(A).to(B).seconds` executes
+        the job function every N seconds such that A <= N <= B.
+
+        :param latest: Maximum interval between randomized job runs
+        :return: The invoked job instance
+        """
+        self.latest = latest
+        return self
+
+    def until(
+        self,
+        until_time: Union[datetime.datetime, datetime.timedelta, datetime.time, str],
+    ):
+        """
+        Schedule job to run until the specified moment.
+
+        The job is canceled whenever the next run is calculated and it turns out the
+        next run is after the until_time. The job is also canceled right before it runs,
+        if the current time is after until_time. This latter case can happen when the
+        the job was scheduled to run before until_time, but runs after until_time.
+
+        If until_time is a moment in the past, ScheduleValueError is thrown.
+
+        :param until_time: A moment in the future representing the latest time a job can
+           be run. If only a time is supplied, the date is set to today.
+           The following formats are accepted:
+
+           - datetime.datetime
+           - datetime.timedelta
+           - datetime.time
+           - String in one of the following formats: "%Y-%m-%d %H:%M:%S",
+             "%Y-%m-%d %H:%M", "%Y-%m-%d", "%H:%M:%S", "%H:%M"
+             as defined by strptime() behaviour. If an invalid string format is passed,
+             ScheduleValueError is thrown.
+
+        :return: The invoked job instance
+        """
+
+        cancel_after: Optional[datetime.datetime]
+        if isinstance(until_time, datetime.datetime):
+            cancel_after = until_time
+        elif isinstance(until_time, datetime.timedelta):
+            cancel_after = datetime.datetime.now() + until_time
+        elif isinstance(until_time, datetime.time):
+            cancel_after = datetime.datetime.combine(
+                datetime.datetime.now(), until_time
+            )
+        elif isinstance(until_time, str):
+            cancel_after = self._decode_datetimestr(
+                until_time,
+                [
+                    "%Y-%m-%d %H:%M:%S",
+                    "%Y-%m-%d %H:%M",
+                    "%Y-%m-%d",
+                    "%H:%M:%S",
+                    "%H:%M",
+                ],
+            )
+            if cancel_after is None:
+                raise ScheduleValueError("Invalid string format for until()")
+            if "-" not in until_time:
+                # the until_time is a time-only format. Set the date to today
+                now = datetime.datetime.now()
+                cancel_after = cancel_after.replace(
+                    year=now.year, month=now.month, day=now.day
+                )
+        else:
+            raise TypeError(
+                "until() takes a string, datetime.datetime, datetime.timedelta, "
+                "datetime.time parameter"
+            )
+        now = (
+            datetime.datetime.now(tz=cancel_after.tzinfo)
+            if cancel_after.tzinfo is not None
+            else datetime.datetime.now()
+        )
+        if cancel_after < now:
+            raise ScheduleValueError(
+                "Cannot schedule a job to run until a time in the past"
+            )
+        self.cancel_after = cancel_after
+        return self
+
+    def do(self, job_func: Callable, *args, **kwargs):
+        """
+        Specifies the job_func that should be called every time the
+        job runs.
+
+        Any additional arguments are passed on to job_func when
+        the job runs.
+
+        :param job_func: The function to be scheduled
+        :return: The invoked job instance
+        """
+        self.job_func = functools.partial(job_func, *args, **kwargs)
+        functools.update_wrapper(self.job_func, job_func)
+        self._schedule_next_run()
+        if self.scheduler is None:
+            raise ScheduleError(
+                "Unable to a add job to schedule. "
+                "Job is not associated with an scheduler"
+            )
+        if self not in self.scheduler.jobs:
+            self.scheduler.jobs.append(self)
+        return self
+
+    @property
+    def should_run(self) -> bool:
+        """
+        :return: ``True`` if the job should be run now.
+        """
+        assert self._next_run is not None, "must run _schedule_next_run before"
+        return _now_utc() >= self._next_run
+
+    def run(self):
+        """
+        Run the job and immediately reschedule it.
+        If the job's deadline is reached (configured using .until()), the job is not
+        run and CancelJob is returned immediately. If the next scheduled run exceeds
+        the job's deadline, CancelJob is returned after the execution. In this latter
+        case CancelJob takes priority over any other returned value.
+
+        :return: The return value returned by the `job_func`, or CancelJob if the job's
+                 deadline is reached.
+
+        """
+        if self._is_overdue(datetime.datetime.now()):
+            logger.debug("Cancelling job %s", self)
+            return CancelJob
+
+        logger.debug("Running job %s", self)
+        ret = self.job_func()
+        self.last_run = datetime.datetime.now()
+        self._schedule_next_run()
+
+        if self._is_overdue(self._next_run):
+            logger.debug("Cancelling job %s", self)
+            return CancelJob
+        return ret
+
+    def _schedule_next_run(self) -> None:
+        """
+        Compute the instant when this job should run next.
+        """
+        if self.unit not in ("seconds", "minutes", "hours", "days", "weeks"):
+            raise ScheduleValueError(
+                "Invalid unit (valid units are `seconds`, `minutes`, `hours`, "
+                "`days`, and `weeks`)"
+            )
+        if self.latest is not None:
+            if not (self.latest >= self.interval):
+                raise ScheduleError(
+                    "`latest` ({}) is smaller than `interval` ({})".format(
+                        self.latest, self.interval
+                    )
+                )
+            interval = _random_interval(self.interval, self.latest)
+        else:
+            interval = self.interval
+
+        period = datetime.timedelta(**{self.unit: interval})
+        now = _now_utc()
+
+        if self.start_day is not None and self.unit != "weeks":
+            raise ScheduleValueError("`unit` should be 'weeks'")
+
+        if self.unit in ("days", "weeks"):
+            # Days and weeks follow the wall clock of the job's timezone, so a
+            # daily job at 10:30 stays at 10:30 when clocks change. Candidates
+            # are compared in UTC, because wall-clock times can repeat.
+            wall = _wall_clock(now, self.at_time_zone)
+            if self.start_day is not None:
+                wall = _move_to_next_weekday(wall, self.start_day)
+            if self.at_time is not None:
+                wall = wall.replace(
+                    hour=self.at_time.hour,
+                    minute=self.at_time.minute,
+                    second=self.at_time.second,
+                    microsecond=0,
+                )
+            if interval != 1:
+                wall += period
+            next_run = _localize(wall, self.at_time_zone)
+            while next_run <= now:
+                wall += period
+                next_run = _localize(wall, self.at_time_zone)
+        else:
+            # Shorter units measure elapsed time, which is unaffected by
+            # clock changes.
+            next_run = now
+            if self.at_time is not None:
+                # The offset is taken from the current time, which keeps
+                # minutes correct in timezones with a non-whole-hour offset.
+                current = now.astimezone(self.at_time_zone)
+                current = current.replace(second=self.at_time.second, microsecond=0)
+                if self.unit == "hours":
+                    current = current.replace(minute=self.at_time.minute)
+                next_run = current.astimezone(_UTC)
+            if interval != 1:
+                next_run += period
+            while next_run <= now:
+                next_run += period
+
+        self._next_run = next_run
+
+    def _is_overdue(self, when: datetime.datetime):
+        if self.cancel_after is None:
+            return False
+        # Compare in UTC; naive datetimes are in local time.
+        return when.astimezone(_UTC) > self.cancel_after.astimezone(_UTC)
+
+    def _decode_datetimestr(
+        self, datetime_str: str, formats: List[str]
+    ) -> Optional[datetime.datetime]:
+        for f in formats:
+            try:
+                return datetime.datetime.strptime(datetime_str, f)
+            except ValueError:
+                pass
+        return None
+
+
+# The following methods are shortcuts for not having to
+# create a Scheduler instance:
+
+#: Default :class:`Scheduler <Scheduler>` object
+default_scheduler = Scheduler()
+
+#: Default :class:`Jobs <Job>` list
+jobs = default_scheduler.jobs  # todo: should this be a copy, e.g. jobs()?
+
+
+def every(interval: int = 1) -> Job:
+    """Calls :meth:`every <Scheduler.every>` on the
+    :data:`default scheduler instance <default_scheduler>`.
+    """
+    return default_scheduler.every(interval)
+
+
+def run_pending() -> None:
+    """Calls :meth:`run_pending <Scheduler.run_pending>` on the
+    :data:`default scheduler instance <default_scheduler>`.
+    """
+    default_scheduler.run_pending()
+
+
+def run_all(delay_seconds: int = 0) -> None:
+    """Calls :meth:`run_all <Scheduler.run_all>` on the
+    :data:`default scheduler instance <default_scheduler>`.
+    """
+    default_scheduler.run_all(delay_seconds=delay_seconds)
+
+
+def get_jobs(tag: Optional[Hashable] = None) -> List[Job]:
+    """Calls :meth:`get_jobs <Scheduler.get_jobs>` on the
+    :data:`default scheduler instance <default_scheduler>`.
+    """
+    return default_scheduler.get_jobs(tag)
+
+
+def clear(tag: Optional[Hashable] = None) -> None:
+    """Calls :meth:`clear <Scheduler.clear>` on the
+    :data:`default scheduler instance <default_scheduler>`.
+    """
+    default_scheduler.clear(tag)
+
+
+def cancel_job(job: Job) -> None:
+    """Calls :meth:`cancel_job <Scheduler.cancel_job>` on the
+    :data:`default scheduler instance <default_scheduler>`.
+    """
+    default_scheduler.cancel_job(job)
+
+
+def next_run(tag: Optional[Hashable] = None) -> Optional[datetime.datetime]:
+    """Calls :meth:`next_run <Scheduler.next_run>` on the
+    :data:`default scheduler instance <default_scheduler>`.
+    """
+    return default_scheduler.get_next_run(tag)
+
+
+def idle_seconds() -> Optional[float]:
+    """Calls :meth:`idle_seconds <Scheduler.idle_seconds>` on the
+    :data:`default scheduler instance <default_scheduler>`.
+    """
+    return default_scheduler.idle_seconds
+
+
+def repeat(job, *args, **kwargs):
+    """
+    Decorator to schedule a new periodic job.
+
+    Any additional arguments are passed on to the decorated function
+    when the job runs.
+
+    :param job: a :class:`Jobs <Job>`
+    """
+
+    def _schedule_decorator(decorated_function):
+        job.do(decorated_function, *args, **kwargs)
+        return decorated_function
+
+    return _schedule_decorator
+
+
+def _random_interval(
+    earliest: Union[int, float], latest: Union[int, float]
+) -> Union[int, float]:
+    """
+    Pick a random interval between `earliest` and `latest`, inclusive.
+
+    Whole numbers (including floats such as 2.0) give a whole number, as
+    random.randint() did before Python 3.12 stopped accepting floats. Other
+    floats give any value in the range.
+    """
+    if float(earliest).is_integer() and float(latest).is_integer():
+        return random.randint(int(earliest), int(latest))
+    return random.uniform(earliest, latest)
+
+
+_UTC = datetime.timezone.utc
+
+
+def _parse_timezone(tz: Union[str, datetime.tzinfo]) -> datetime.tzinfo:
+    if isinstance(tz, datetime.tzinfo):
+        return tz
+    if not isinstance(tz, str):
+        raise ScheduleValueError("Timezone must be a string or a tzinfo object")
+    try:
+        import pytz
+    except ModuleNotFoundError:
+        pass
+    else:
+        # Prefer pytz when installed, for compatibility with schedule 1.2.
+        return pytz.timezone(tz)
+
+    import zoneinfo
+
+    try:
+        return zoneinfo.ZoneInfo(tz)
+    except (zoneinfo.ZoneInfoNotFoundError, ValueError) as e:
+        raise ScheduleValueError(
+            "Unknown timezone {!r}. On Windows, install the tzdata package "
+            "for timezone names to work.".format(tz)
+        ) from e
+
+
+def _now_utc() -> datetime.datetime:
+    return datetime.datetime.now(_UTC)
+
+
+def _wall_clock(moment: datetime.datetime, tz) -> datetime.datetime:
+    """
+    The naive wall-clock time of a UTC moment in `tz`, or in local time if
+    `tz` is None.
+    """
+    return moment.astimezone(tz).replace(tzinfo=None)
+
+
+def _localize(wall: datetime.datetime, tz) -> datetime.datetime:
+    """
+    The UTC moment at which the clock in `tz` shows the naive time `wall`.
+    Local time is used if `tz` is None.
+
+    A wall-clock time that happens twice, when clocks go back, resolves to its
+    first occurrence. A wall-clock time that does not exist, when clocks go
+    forward, is moved forward by the size of the gap: 02:30 becomes 03:30
+    when clocks jump from 02:00 to 03:00.
+    """
+    if tz is None:
+        return wall.replace(fold=0).astimezone(_UTC)
+    if hasattr(tz, "localize"):
+        # pytz timezones need localize() to pick the correct UTC offset.
+        import pytz
+
+        try:
+            aware = tz.localize(wall, is_dst=None)
+        except pytz.AmbiguousTimeError:
+            aware = tz.localize(wall, is_dst=True)
+        except pytz.NonExistentTimeError:
+            aware = tz.localize(wall, is_dst=False)
+        return aware.astimezone(_UTC)
+    return wall.replace(tzinfo=tz, fold=0).astimezone(_UTC)
+
+
+def _move_to_next_weekday(moment: datetime.datetime, weekday: str):
+    """
+    Move the given timestamp to the nearest given weekday. May be this week
+    or next week. If the timestamp is already at the given weekday, it is not
+    moved.
+    """
+    weekday_index = _weekday_index(weekday)
+
+    days_ahead = weekday_index - moment.weekday()
+    if days_ahead < 0:
+        # Target day already happened this week, move to next week
+        days_ahead += 7
+    return moment + datetime.timedelta(days=days_ahead)
+
+
+def _weekday_index(day: str) -> int:
+    weekdays = (
+        "monday",
+        "tuesday",
+        "wednesday",
+        "thursday",
+        "friday",
+        "saturday",
+        "sunday",
+    )
+    if day not in weekdays:
+        raise ScheduleValueError(
+            "Invalid start day (valid start days are {})".format(weekdays)
+        )
+    return weekdays.index(day)

schedule_ng-1.3.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.5
+Name: schedule-ng
+Version: 1.3.0
+Summary: Job scheduling for humans. A maintained, drop-in successor to schedule.
+Project-URL: Repository, https://github.com/Adz-ai/schedule-ng
+Project-URL: Issues, https://github.com/Adz-ai/schedule-ng/issues
+Project-URL: Changelog, https://github.com/Adz-ai/schedule-ng/blob/main/HISTORY.rst
+Author-email: Daniel Bader <mail@dbader.org>
+Maintainer: Adarssh
+License-Expression: MIT
+License-File: LICENSE.txt
+Keywords: clockwork,cron,job scheduling,jobs,periodic,schedule,scheduler,scheduling
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: timezone
+Requires-Dist: pytz; extra == 'timezone'
+Description-Content-Type: text/x-rst
+
+schedule-ng
+===========
+
+.. image:: https://github.com/Adz-ai/schedule-ng/actions/workflows/ci.yml/badge.svg
+        :target: https://github.com/Adz-ai/schedule-ng/actions/workflows/ci.yml
+
+.. image:: https://img.shields.io/pypi/v/schedule-ng.svg
+        :target: https://pypi.org/project/schedule-ng/
+
+Python job scheduling for humans. Run Python functions (or any other callable) periodically using a friendly syntax.
+
+**schedule-ng is a maintained, drop-in compatible fork of** `schedule <https://github.com/dbader/schedule>`_
+**by Daniel Bader**, which has not had a release since 1.2.2 (May 2024). The API is unchanged: existing code
+keeps working by changing one import.
+
+- A simple to use API for scheduling jobs, made for humans.
+- In-process scheduler for periodic jobs. No extra processes needed!
+- Very lightweight and no external dependencies.
+- Excellent test coverage.
+- Tested on Python 3.9 to 3.14 on Linux, macOS and Windows.
+
+Usage
+-----
+
+.. code-block:: bash
+
+    $ pip install schedule-ng
+
+.. code-block:: python
+
+    import schedule_ng as schedule
+    import time
+
+    def job():
+        print("I'm working...")
+
+    schedule.every(10).seconds.do(job)
+    schedule.every(10).minutes.do(job)
+    schedule.every().hour.do(job)
+    schedule.every().day.at("10:30").do(job)
+    schedule.every(5).to(10).minutes.do(job)
+    schedule.every().monday.do(job)
+    schedule.every().wednesday.at("13:15").do(job)
+    schedule.every().day.at("12:42", "Europe/Amsterdam").do(job)
+    schedule.every().minute.at(":17").do(job)
+
+    def job_with_argument(name):
+        print(f"I am {name}")
+
+    schedule.every(10).seconds.do(job_with_argument, name="Peter")
+
+    while True:
+        schedule.run_pending()
+        time.sleep(1)
+
+Migrating from schedule
+-----------------------
+
+1. Replace ``schedule`` with ``schedule-ng`` in your dependencies.
+2. Replace ``import schedule`` with ``import schedule_ng as schedule``.
+
+Behaviour, exceptions and the ``"schedule"`` logger name are unchanged. Any behavioural fix is listed in the
+`changelog <https://github.com/Adz-ai/schedule-ng/blob/main/HISTORY.rst>`_.
+
+Why a fork?
+-----------
+
+``schedule`` is used by millions of projects every month, but issues and pull requests have gone unanswered
+since 2024. This fork exists to keep it working on new Python versions, fix long-standing bugs and review the
+community's pull requests, while keeping what made ``schedule`` popular: a small, simple, dependency-free API.
+
+If the original project becomes active again, this fork will happily contribute its fixes back upstream.
+
+Meta
+----
+
+Original author: Daniel Bader - mail@dbader.org. Thanks to Sijmen Huizenga and everyone listed in
+`AUTHORS.rst <https://github.com/Adz-ai/schedule-ng/blob/main/AUTHORS.rst>`_ for their work on ``schedule``.
+
+Inspired by `Adam Wiggins' <https://github.com/adamwiggins>`_ article `"Rethinking Cron" <https://adam.herokuapp.com/past/2010/4/13/rethinking_cron/>`_ and the `clockwork <https://github.com/Rykian/clockwork>`_ Ruby module.
+
+Distributed under the MIT license. See `LICENSE.txt <https://github.com/Adz-ai/schedule-ng/blob/main/LICENSE.txt>`_ for more information.

schedule_ng-1.3.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+schedule_ng/__init__.py,sha256=BquBy4xHbZwsfTJjCUocZzRRotx_olyzxU9MW6vAN54,33854
+schedule_ng/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+schedule_ng-1.3.0.dist-info/METADATA,sha256=bo_HYXyHOyZazXQwn5XOKQTQ70UFmKHTsuqQKtReY4g,4414
+schedule_ng-1.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+schedule_ng-1.3.0.dist-info/licenses/LICENSE.txt,sha256=oS1kzxXgr0r8dvUqmgoDmUQrtDcFXAXOng74_x4sVvA,1143
+schedule_ng-1.3.0.dist-info/RECORD,,

schedule_ng-1.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

schedule_ng-1.3.0.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2013 Daniel Bader (http://dbader.org)
+Copyright (c) 2026 schedule-ng contributors
+
+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.