ddeutil-workflow 0.0.5__py3-none-any.whl → 0.0.7__py3-none-any.whl

ddeutil/workflow/repeat.py

@@ -0,0 +1,134 @@
+# ------------------------------------------------------------------------------
+# Copyright (c) 2023 Priyanshu Panwar. All rights reserved.
+# Licensed under the MIT License.
+# This code refs from: https://github.com/priyanshu-panwar/fastapi-utilities
+# ------------------------------------------------------------------------------
+import asyncio
+import logging
+from asyncio import ensure_future
+from datetime import datetime
+from functools import wraps
+
+from croniter import croniter
+from starlette.concurrency import run_in_threadpool
+
+
+def get_delta(cron: str):
+    """This function returns the time delta between now and the next cron
+    execution time.
+    """
+    now: datetime = datetime.now()
+    cron = croniter(cron, now)
+    return (cron.get_next(datetime) - now).total_seconds()
+
+
+def repeat_at(
+    *,
+    cron: str,
+    logger: logging.Logger = None,
+    raise_exceptions: bool = False,
+    max_repetitions: int = None,
+):
+    """This function returns a decorator that makes a function execute
+    periodically as per the cron expression provided.
+
+    :param cron: str
+        Cron-style string for periodic execution, eg. '0 0 * * *' every midnight
+    :param logger: logging.Logger (default None)
+        Logger object to log exceptions
+    :param raise_exceptions: bool (default False)
+        Whether to raise exceptions or log them
+    :param max_repetitions: int (default None)
+        Maximum number of times to repeat the function. If None, repeat
+        indefinitely.
+
+    """
+
+    def decorator(func):
+        is_coroutine = asyncio.iscoroutinefunction(func)
+
+        @wraps(func)
+        def wrapper(*_args, **_kwargs):
+            repititions = 0
+            if not croniter.is_valid(cron):
+                raise ValueError("Invalid cron expression")
+
+            async def loop(*args, **kwargs):
+                nonlocal repititions
+                while max_repetitions is None or repititions < max_repetitions:
+                    try:
+                        sleepTime = get_delta(cron)
+                        await asyncio.sleep(sleepTime)
+                        if is_coroutine:
+                            await func(*args, **kwargs)
+                        else:
+                            await run_in_threadpool(func, *args, **kwargs)
+                    except Exception as e:
+                        if logger is not None:
+                            logger.exception(e)
+                        if raise_exceptions:
+                            raise e
+                    repititions += 1
+
+            ensure_future(loop(*_args, **_kwargs))
+
+        return wrapper
+
+    return decorator
+
+
+def repeat_every(
+    *,
+    seconds: float,
+    wait_first: bool = False,
+    logger: logging.Logger = None,
+    raise_exceptions: bool = False,
+    max_repetitions: int = None,
+):
+    """This function returns a decorator that schedules a function to execute
+    periodically after every `seconds` seconds.
+
+    :param seconds: float
+        The number of seconds to wait before executing the function again.
+    :param wait_first: bool (default False)
+        Whether to wait `seconds` seconds before executing the function for the
+        first time.
+    :param logger: logging.Logger (default None)
+        The logger to use for logging exceptions.
+    :param raise_exceptions: bool (default False)
+        Whether to raise exceptions instead of logging them.
+    :param max_repetitions: int (default None)
+        The maximum number of times to repeat the function. If None, the
+        function will repeat indefinitely.
+    """
+
+    def decorator(func):
+        is_coroutine = asyncio.iscoroutinefunction(func)
+
+        @wraps(func)
+        async def wrapper(*_args, **_kwargs):
+            repetitions = 0
+
+            async def loop(*args, **kwargs):
+                nonlocal repetitions
+                if wait_first:
+                    await asyncio.sleep(seconds)
+                while max_repetitions is None or repetitions < max_repetitions:
+                    try:
+                        if is_coroutine:
+                            await func(*args, **kwargs)
+                        else:
+                            await run_in_threadpool(func, *args, **kwargs)
+                    except Exception as e:
+                        if logger is not None:
+                            logger.exception(e)
+                        if raise_exceptions:
+                            raise e
+                    repetitions += 1
+                    await asyncio.sleep(seconds)
+
+            ensure_future(loop(*_args, **_kwargs))
+
+        return wrapper
+
+    return decorator

ddeutil/workflow/route.py

@@ -0,0 +1,78 @@
+from enum import Enum
+
+from fastapi import APIRouter, Request, status
+from pydantic import BaseModel, ConfigDict, Field
+
+from .log import get_logger
+
+logger = get_logger(__name__)
+workflow_route = APIRouter(prefix="/workflow")
+
+
+@workflow_route.get("/{name}")
+async def get_pipeline(name: str):
+    return {"message": f"getting pipeline {name}"}
+
+
+@workflow_route.get("/{name}/logs")
+async def get_pipeline_log(name: str):
+    return {"message": f"getting pipeline {name} logs"}
+
+
+class JobNotFoundError(Exception):
+    pass
+
+
+schedule_route = APIRouter(prefix="/schedule", tags=["schedule"])
+
+
+class TriggerEnum(str, Enum):
+    interval = "interval"
+    cron = "cron"
+
+
+class Job(BaseModel):
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "func": "example.main:pytest_job",
+                "trigger": "interval",
+                "seconds": 3,
+                "id": "pytest_job",
+            },
+        },
+    )
+    func: str = Field()
+    trigger: TriggerEnum = Field(title="Trigger type")
+    seconds: int = Field(title="Interval in seconds")
+    id: str = Field(title="Job ID")
+
+
+@schedule_route.post(
+    "/", name="scheduler:add_job", status_code=status.HTTP_201_CREATED
+)
+async def add_job(request: Request, job: Job):
+    job = request.app.scheduler.add_job(**job.dict())
+    return {"job": f"{job.id}"}
+
+
+@schedule_route.get("/", name="scheduler:get_jobs", response_model=list)
+async def get_jobs(request: Request):
+    jobs = request.app.scheduler.get_jobs()
+    jobs = [
+        {k: v for k, v in job.__getstate__().items() if k != "trigger"}
+        for job in jobs
+    ]
+    return jobs
+
+
+@schedule_route.delete("/{job_id}", name="scheduler:remove_job")
+async def remove_job(request: Request, job_id: str):
+    try:
+        deleted = request.app.scheduler.remove_job(job_id=job_id)
+        logger.debug(f"Job {job_id} deleted: {deleted}")
+        return {"job": f"{job_id}"}
+    except AttributeError as err:
+        raise JobNotFoundError(
+            f"No job by the id of {job_id} was found"
+        ) from err

ddeutil/workflow/{__scheduler.py → scheduler.py}

@@ -8,13 +8,9 @@ from __future__ import annotations
 import copy
 from collections.abc import Iterator
 from dataclasses import dataclass, field
-from datetime import datetime, timedelta, timezone
+from datetime import datetime, timedelta
 from functools import partial, total_ordering
-from typing import (
-    Callable,
-    Optional,
-    Union,
-)
+from typing import Callable, Optional, Union
 from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
 
 from ddeutil.core import (
@@ -117,7 +113,7 @@ CRON_UNITS: tuple[Unit, ...] = (
     ),
 )
 
-CRON_UNITS_AWS: tuple[Unit, ...] = CRON_UNITS + (
+CRON_UNITS_YEAR: tuple[Unit, ...] = CRON_UNITS + (
     Unit(
         name="year",
         range=partial(range, 1990, 2101),
@@ -152,6 +148,7 @@ class CronPart:
             values: list[int] = self.replace_weekday(values)
         else:
             raise TypeError(f"Invalid type of value in cron part: {values}.")
+
         self.values: list[int] = self.out_of_range(
             sorted(dict.fromkeys(values))
         )
@@ -190,10 +187,16 @@ class CronPart:
         )
 
     def __lt__(self, other) -> bool:
-        return self.values < other.values
+        if isinstance(other, CronPart):
+            return self.values < other.values
+        elif isinstance(other, list):
+            return self.values < other
 
     def __eq__(self, other) -> bool:
-        return self.values == other.values
+        if isinstance(other, CronPart):
+            return self.values == other.values
+        elif isinstance(other, list):
+            return self.values == other
 
     @property
     def min(self) -> int:
@@ -225,11 +228,11 @@ class CronPart:
         """Parses a string as a range of positive integers. The string should
         include only `-` and `,` special strings.
 
-        :param value: A string value
+        :param value: A string value that want to parse
         :type value: str
 
         TODO: support for `L`, `W`, and `#`
-        TODO:     if you didn't care what day of the week the 7th was, you
+        TODO: if you didn't care what day of the week the 7th was, you
             could enter ? in the Day-of-week field.
         TODO: L : the Day-of-month or Day-of-week fields specifies the last day
             of the month or week.
@@ -239,7 +242,7 @@ class CronPart:
         TODO: # : 3#2 would be the second Tuesday of the month,
             the 3 refers to Tuesday because it is the third day of each week.
 
-        Examples:
+        Noted:
             -   0 10 * * ? *
                 Run at 10:00 am (UTC) every day
 
@@ -302,9 +305,14 @@ class CronPart:
         return value
 
     def replace_weekday(self, values: list[int] | Iterator[int]) -> list[int]:
-        """Replaces all 7 with 0 as Sunday can be represented by both."""
+        """Replaces all 7 with 0 as Sunday can be represented by both.
+
+        :param values: list or iter of int that want to mode by 7
+        :rtype: list[int]
+        """
         if self.unit.name == "weekday":
-            return [0 if value == 7 else value for value in values]
+            # NOTE: change weekday value in range 0-6 (div-mod by 7).
+            return [value % 7 for value in values]
         return list(values)
 
     def out_of_range(self, values: list[int]) -> list[int]:
@@ -531,27 +539,27 @@ class CronJob:
         return reversed(self.parts[:3] + [self.parts[4], self.parts[3]])
 
     @property
-    def minute(self):
+    def minute(self) -> CronPart:
         """Return part of minute."""
         return self.parts[0]
 
     @property
-    def hour(self):
+    def hour(self) -> CronPart:
         """Return part of hour."""
         return self.parts[1]
 
     @property
-    def day(self):
+    def day(self) -> CronPart:
         """Return part of day."""
         return self.parts[2]
 
     @property
-    def month(self):
+    def month(self) -> CronPart:
         """Return part of month."""
         return self.parts[3]
 
     @property
-    def dow(self):
+    def dow(self) -> CronPart:
         """Return part of day of month."""
         return self.parts[4]
 
@@ -560,15 +568,29 @@ class CronJob:
         return [part.values for part in self.parts]
 
     def schedule(
-        self, date: Optional[datetime] = None, _tz: Optional[str] = None
+        self,
+        date: datetime | None = None,
+        *,
+        tz: str | None = None,
     ) -> CronRunner:
-        """Returns the time the schedule would run next."""
-        return CronRunner(self, date, tz_str=_tz)
+        """Returns the schedule datetime runner with this cronjob. It would run
+        ``next``, ``prev``, or ``reset`` to generate running date that you want.
+
+        :param date: An initial date that want to mark as the start point.
+        :param tz: A string timezone that want to change on runner.
+        :rtype: CronRunner
+        """
+        return CronRunner(self, date, tz=tz)
 
 
-class CronJobAWS(CronJob):
+class CronJobYear(CronJob):
     cron_length = 6
-    cron_units = CRON_UNITS_AWS
+    cron_units = CRON_UNITS_YEAR
+
+    @property
+    def year(self) -> CronPart:
+        """Return part of year."""
+        return self.parts[5]
 
 
 class CronRunner:
@@ -586,33 +608,37 @@ class CronRunner:
 
     def __init__(
         self,
-        cron: CronJob,
-        date: Optional[datetime] = None,
+        cron: CronJob | CronJobYear,
+        date: datetime | None = None,
         *,
-        tz_str: Optional[str] = None,
+        tz: str | None = None,
     ) -> None:
-        # NOTE: Prepare date and tz_info
-        self.tz = timezone.utc
-        if tz_str:
+        # NOTE: Prepare timezone if this value does not set, it will use UTC.
+        self.tz: ZoneInfo = ZoneInfo("UTC")
+        if tz:
             try:
-                self.tz = ZoneInfo(tz_str)
+                self.tz = ZoneInfo(tz)
             except ZoneInfoNotFoundError as err:
-                raise ValueError(f"Invalid timezone: {tz_str}") from err
+                raise ValueError(f"Invalid timezone: {tz}") from err
+
+        # NOTE: Prepare date
         if date:
             if not isinstance(date, datetime):
                 raise ValueError(
                     "Input schedule start time is not a valid datetime object."
                 )
-            self.tz = date.tzinfo
-            self.date: datetime = date
+            if tz is None:
+                self.tz = date.tzinfo
+            self.date: datetime = date.astimezone(self.tz)
         else:
             self.date: datetime = datetime.now(tz=self.tz)
 
+        # NOTE: Add one minute if the second value more than 0.
         if self.date.second > 0:
-            self.date: datetime = self.date + timedelta(minutes=+1)
+            self.date: datetime = self.date + timedelta(minutes=1)
 
         self.__start_date: datetime = self.date
-        self.cron: CronJob = cron
+        self.cron: CronJob | CronJobYear = cron
         self.reset_flag: bool = True
 
     def reset(self) -> None:
@@ -637,7 +663,11 @@ class CronRunner:
         return self.find_date(reverse=True)
 
     def find_date(self, reverse: bool = False) -> datetime:
-        """Returns the time the schedule would run by `next` or `prev`."""
+        """Returns the time the schedule would run by `next` or `prev`.
+
+        :param reverse: A reverse flag.
+        """
+        # NOTE: Set reset flag to false if start any action.
         self.reset_flag: bool = False
         for _ in range(25):
             if all(
@@ -656,7 +686,7 @@ class CronRunner:
             "minute": "hour",
         }
         current_value: int = getattr(self.date, switch[mode])
-        _addition: Callable[[], bool] = (
+        _addition_condition: Callable[[], bool] = (
             (
                 lambda: WEEKDAYS.get(self.date.strftime("%a"))
                 not in self.cron.dow.values
@@ -664,15 +694,12 @@ class CronRunner:
             if mode == "day"
             else lambda: False
         )
+        # NOTE: Start while-loop for checking this date include in this cronjob.
         while (
             getattr(self.date, mode) not in getattr(self.cron, mode).values
-        ) or _addition():
-            self.date: datetime = next_date(
-                self.date, mode=mode, reverse=reverse
-            )
-            self.date: datetime = replace_date(
-                self.date, mode=mode, reverse=reverse
-            )
+        ) or _addition_condition():
+            self.date: datetime = next_date(self.date, mode, reverse=reverse)
+            self.date: datetime = replace_date(self.date, mode, reverse=reverse)
             if current_value != getattr(self.date, switch[mode]):
                 return mode != "month"
         return False
@@ -680,6 +707,7 @@ class CronRunner:
 
 __all__ = (
     "CronJob",
+    "CronJobYear",
     "CronRunner",
     "WEEKDAYS",
 )