ddeutil-workflow 0.0.56__tar.gz → 0.0.58__tar.gz

{ddeutil_workflow-0.0.56 → ddeutil_workflow-0.0.58}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ddeutil-workflow
-Version: 0.0.56
+Version: 0.0.58
 Summary: Lightweight workflow orchestration
 Author-email: ddeutils <korawich.anu@gmail.com>
 License: MIT
@@ -22,8 +22,8 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: >=3.9.13
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: ddeutil[checksum]>=0.4.7
-Requires-Dist: ddeutil-io[toml,yaml]>=0.2.11
+Requires-Dist: ddeutil[checksum]>=0.4.8
+Requires-Dist: ddeutil-io[toml,yaml]>=0.2.12
 Requires-Dist: pydantic==2.11.1
 Requires-Dist: python-dotenv==1.1.0
 Requires-Dist: schedule<2.0.0,==1.2.2
@@ -250,42 +250,48 @@ from ddeutil.workflow import Workflow, Result
 
 workflow: Workflow = Workflow.from_conf('run-py-local')
 result: Result = workflow.execute(
-   params={"source-extract": "USD-THB", "asat-dt": "2024-01-01"}
+   params={"source-extract": "USD-THB", "run-date": "2024-01-01"}
 )
 ```
 
-So, this package provide the `Schedule` template for this action, and you can dynamic
-pass the parameters for changing align with that running time by the `release` prefix.
-
-```yaml
-schedule-run-local-wf:
-
-   # Validate model that use to parsing exists for template file
-   type: Schedule
-   workflows:
-
-      # Map existing workflow that want to deploy with scheduler application.
-      # It allows you to pass release parameter that dynamic change depend on the
-      # current context of this scheduler application releasing that time.
-      - name: run-py-local
-        params:
-          source-extract: "USD-THB"
-          asat-dt: "${{ release.logical_date }}"
-```
-
-The main method of the `Schedule` model that use to running is `pending`. If you
-do not pass the `stop` date on this method, it will use config with `WORKFLOW_APP_STOP_BOUNDARY_DELTA`
-key for generate this stop date.
-
-```python
-from ddeutil.workflow import Schedule
+> [!NOTE]
+> So, this package provide the `Schedule` template for this action, and you can
+> pass the parameters dynamically for changing align with that running time by
+> the `release` prefix.
+>
+> ```yaml
+> schedule-run-local-wf:
+>
+>    # Validate model that use to parsing exists for template file
+>    type: Schedule
+>    workflows:
+>
+>       # Map existing workflow that want to deploy with scheduler application.
+>       # It allows you to pass release parameter that dynamic change depend on the
+>       # current context of this scheduler application releasing that time.
+>       - name: run-py-local
+>         params:
+>           source-extract: "USD-THB"
+>           run-date: "${{ release.logical_date }}"
+> ```
+>
+> The main method of the `Schedule` model that use to running is `pending`. If you
+> do not pass the `stop` date on this method, it will use config with
+> `WORKFLOW_APP_STOP_BOUNDARY_DELTA` key for generate this stop date.
+>
+> ```python
+> from ddeutil.workflow import Schedule
+>
+> (
+>    Schedule
+>    .from_conf("schedule-run-local-wf")
+>    .pending(stop=None)
+> )
+> ```
 
-(
-   Schedule
-   .from_conf("schedule-run-local-wf")
-   .pending(stop=None)
-)
-```
+> [!WARNING]
+> The scheduler feature is the expensive feature of this project. You should
+> avoid to use it and find a scheduler tool instead.
 
 ## :cookie: Configuration
 

{ddeutil_workflow-0.0.56 → ddeutil_workflow-0.0.58}/README.md

@@ -205,42 +205,48 @@ from ddeutil.workflow import Workflow, Result
 
 workflow: Workflow = Workflow.from_conf('run-py-local')
 result: Result = workflow.execute(
-   params={"source-extract": "USD-THB", "asat-dt": "2024-01-01"}
+   params={"source-extract": "USD-THB", "run-date": "2024-01-01"}
 )
 ```
 
-So, this package provide the `Schedule` template for this action, and you can dynamic
-pass the parameters for changing align with that running time by the `release` prefix.
-
-```yaml
-schedule-run-local-wf:
-
-   # Validate model that use to parsing exists for template file
-   type: Schedule
-   workflows:
-
-      # Map existing workflow that want to deploy with scheduler application.
-      # It allows you to pass release parameter that dynamic change depend on the
-      # current context of this scheduler application releasing that time.
-      - name: run-py-local
-        params:
-          source-extract: "USD-THB"
-          asat-dt: "${{ release.logical_date }}"
-```
-
-The main method of the `Schedule` model that use to running is `pending`. If you
-do not pass the `stop` date on this method, it will use config with `WORKFLOW_APP_STOP_BOUNDARY_DELTA`
-key for generate this stop date.
-
-```python
-from ddeutil.workflow import Schedule
+> [!NOTE]
+> So, this package provide the `Schedule` template for this action, and you can
+> pass the parameters dynamically for changing align with that running time by
+> the `release` prefix.
+>
+> ```yaml
+> schedule-run-local-wf:
+>
+>    # Validate model that use to parsing exists for template file
+>    type: Schedule
+>    workflows:
+>
+>       # Map existing workflow that want to deploy with scheduler application.
+>       # It allows you to pass release parameter that dynamic change depend on the
+>       # current context of this scheduler application releasing that time.
+>       - name: run-py-local
+>         params:
+>           source-extract: "USD-THB"
+>           run-date: "${{ release.logical_date }}"
+> ```
+>
+> The main method of the `Schedule` model that use to running is `pending`. If you
+> do not pass the `stop` date on this method, it will use config with
+> `WORKFLOW_APP_STOP_BOUNDARY_DELTA` key for generate this stop date.
+>
+> ```python
+> from ddeutil.workflow import Schedule
+>
+> (
+>    Schedule
+>    .from_conf("schedule-run-local-wf")
+>    .pending(stop=None)
+> )
+> ```
 
-(
-   Schedule
-   .from_conf("schedule-run-local-wf")
-   .pending(stop=None)
-)
-```
+> [!WARNING]
+> The scheduler feature is the expensive feature of this project. You should
+> avoid to use it and find a scheduler tool instead.
 
 ## :cookie: Configuration
 

{ddeutil_workflow-0.0.56 → ddeutil_workflow-0.0.58}/pyproject.toml

@@ -25,8 +25,8 @@ classifiers = [
 ]
 requires-python = ">=3.9.13"
 dependencies = [
-    "ddeutil[checksum]>=0.4.7",
-    "ddeutil-io[yaml,toml]>=0.2.11",
+    "ddeutil[checksum]>=0.4.8",
+    "ddeutil-io[yaml,toml]>=0.2.12",
     "pydantic==2.11.1",
     "python-dotenv==1.1.0",
     "schedule==1.2.2,<2.0.0",
@@ -82,8 +82,9 @@ source = ["src.ddeutil.workflow"]
 omit = [
     "src/ddeutil/workflow/__about__.py",
     "src/ddeutil/workflow/__cron.py",
+    "src/ddeutil/workflow/__main__.py",
     "src/ddeutil/workflow/api/__init__.py",
-    "src/ddeutil/workflow/api/log.py",
+    "src/ddeutil/workflow/api/logs.py",
     "src/ddeutil/workflow/api/utils.py",
     "src/ddeutil/workflow/api/routes/__init__.py",
     "src/ddeutil/workflow/api/routes/job.py",

ddeutil_workflow-0.0.58/src/ddeutil/workflow/__about__.py

@@ -0,0 +1 @@
+__version__: str = "0.0.58"

{ddeutil_workflow-0.0.56 → ddeutil_workflow-0.0.58}/src/ddeutil/workflow/__cron.py

@@ -502,10 +502,10 @@ class CronPart:
             except IndexError:
                 next_value: int = -1
             if value != (next_value - 1):
-                # NOTE: ``next_value`` is not the subsequent number
+                # NOTE: `next_value` is not the subsequent number
                 if start_number is None:
                     # NOTE:
-                    #   The last number of the list ``self.values`` is not in a
+                    #   The last number of the list `self.values` is not in a
                     #   range.
                     multi_dim_values.append(value)
                 else:
@@ -703,11 +703,14 @@ class CronJob:
         *,
         tz: str | None = None,
     ) -> CronRunner:
-        """Returns the schedule datetime runner with this cronjob. It would run
-        ``next``, ``prev``, or ``reset`` to generate running date that you want.
+        """Returns CronRunner instance that be datetime runner with this
+        cronjob. It can use `next`, `prev`, or `reset` methods to generate
+        running date.
 
-        :param date: An initial date that want to mark as the start point.
-        :param tz: A string timezone that want to change on runner.
+        :param date: (datetime) An initial date that want to mark as the start
+            point. (Default is use the current datetime)
+        :param tz: (str) A string timezone that want to change on runner.
+            (Default is None)
 
         :rtype: CronRunner
         """
@@ -743,6 +746,10 @@ class CronJobYear(CronJob):
 class CronRunner:
     """Create an instance of Date Runner object for datetime generate with
     cron schedule object value.
+
+    :param cron: (CronJob | CronJobYear)
+    :param date: (datetime)
+    :param tz: (str)
     """
 
     shift_limit: ClassVar[int] = 25
@@ -761,11 +768,17 @@ class CronRunner:
         cron: CronJob | CronJobYear,
         date: datetime | None = None,
         *,
-        tz: str | None = None,
+        tz: str | ZoneInfo | None = None,
     ) -> None:
-        # NOTE: Prepare timezone if this value does not set, it will use UTC.
-        self.tz: ZoneInfo = ZoneInfo("UTC")
+        self.tz: ZoneInfo | None = None
         if tz:
+            if isinstance(tz, ZoneInfo):
+                self.tz = tz
+            elif not isinstance(tz, str):
+                raise TypeError(
+                    "Invalid type of `tz` parameter, it should be str or "
+                    "ZoneInfo instance."
+                )
             try:
                 self.tz = ZoneInfo(tz)
             except ZoneInfoNotFoundError as err:
@@ -777,9 +790,10 @@ class CronRunner:
                 raise ValueError(
                     "Input schedule start time is not a valid datetime object."
                 )
-            if tz is None:
-                self.tz = date.tzinfo
-            self.date: datetime = date.astimezone(self.tz)
+            if tz is not None:
+                self.date: datetime = date.astimezone(self.tz)
+            else:
+                self.date: datetime = date
         else:
             self.date: datetime = datetime.now(tz=self.tz)
 

{ddeutil_workflow-0.0.56 → ddeutil_workflow-0.0.58}/src/ddeutil/workflow/__types.py

@@ -20,6 +20,7 @@ from typing import Any, Optional, TypedDict, Union
 
 from typing_extensions import Self
 
+StrOrInt = Union[str, int]
 TupleStr = tuple[str, ...]
 DictData = dict[str, Any]
 DictStr = dict[str, str]

{ddeutil_workflow-0.0.56 → ddeutil_workflow-0.0.58}/src/ddeutil/workflow/conf.py

@@ -200,7 +200,10 @@ class APIConfig:
         return str2bool(env("API_ENABLE_ROUTE_SCHEDULE", "true"))
 
 
-class BaseLoad(ABC):
+class BaseLoad(ABC):  # pragma: no cov
+    """Base Load object is the abstraction object for any Load object that
+    should to inherit from this base class.
+    """
 
     @classmethod
     @abstractmethod
@@ -215,7 +218,7 @@ class BaseLoad(ABC):
 
 class FileLoad(BaseLoad):
     """Base Load object that use to search config data by given some identity
-    value like name of `Workflow` or `On` templates.
+    value like name of `Workflow` or `Crontab` templates.
 
     :param name: (str) A name of key of config data that read with YAML
         Environment object.
@@ -335,8 +338,13 @@ class FileLoad(BaseLoad):
         """
         excluded: list[str] = excluded or []
         path: Path = dynamic("conf_path", f=path, extras=extras)
+        paths: Optional[list[Path]] = paths or (extras or {}).get("conf_paths")
         if not paths:
             paths: list[Path] = [path]
+        elif not isinstance(paths, list):
+            raise TypeError(
+                f"Multi-config paths does not support for type: {type(paths)}"
+            )
         else:
             paths.append(path)
 
@@ -431,17 +439,21 @@ def dynamic(
     """Dynamic get config if extra value was passed at run-time.
 
     :param key: (str) A config key that get from Config object.
-    :param f: An inner config function scope.
+    :param f: (T) An inner config function scope.
     :param extras: An extra values that pass at run-time.
+
+    :rtype: T
     """
-    rsx: Optional[T] = extras[key] if extras and key in extras else None
-    rs: Optional[T] = getattr(config, key, None) if f is None else f
-    if rsx is not None and not isinstance(rsx, type(rs)):
+    extra: Optional[T] = (extras or {}).get(key, None)
+    conf: Optional[T] = getattr(config, key, None) if f is None else f
+    if extra is None:
+        return conf
+    if not isinstance(extra, type(conf)):
         raise TypeError(
-            f"Type of config {key!r} from extras: {rsx!r} does not valid "
-            f"as config {type(rs)}."
+            f"Type of config {key!r} from extras: {extra!r} does not valid "
+            f"as config {type(conf)}."
         )
-    return rsx if rsx is not None else rs
+    return extra
 
 
 class Loader(Protocol):  # pragma: no cov

{ddeutil_workflow-0.0.56 → ddeutil_workflow-0.0.58}/src/ddeutil/workflow/event.py

@@ -3,8 +3,8 @@
 # Licensed under the MIT License. See LICENSE in the project root for
 # license information.
 # ------------------------------------------------------------------------------
-"""Event module that store all event object. Now, it has only `On` and `OnYear`
-model these are schedule with crontab event.
+"""Event module that store all event object. Now, it has only `Crontab` and
+`CrontabYear` model these are schedule with crontab event.
 """
 from __future__ import annotations
 
@@ -63,9 +63,9 @@ def interval2crontab(
     return f"{h} {m} {'1' if interval == 'monthly' else '*'} * {d}"
 
 
-class On(BaseModel):
-    """On model (Warped crontab object by Pydantic model) to keep crontab value
-    and generate CronRunner object from this crontab value.
+class Crontab(BaseModel):
+    """Cron event model (Warped the CronJob object by Pydantic model) to keep
+    crontab value and generate CronRunner object from this crontab value.
 
     Methods:
         - generate: is the main use-case of this schedule object.
@@ -117,6 +117,7 @@ class On(BaseModel):
         passing["cronjob"] = interval2crontab(
             **{v: value[v] for v in value if v in ("interval", "day", "time")}
         )
+        print(passing)
         return cls(extras=extras | passing.pop("extras", {}), **passing)
 
     @classmethod
@@ -127,7 +128,7 @@ class On(BaseModel):
         extras: DictData | None = None,
     ) -> Self:
         """Constructor from the name of config loader that will use loader
-        object for getting the `On` data.
+        object for getting the `Crontab` data.
 
         :param name: (str) A name of config that will get from loader.
         :param extras: (DictData) An extra parameter that use to override core
@@ -171,7 +172,7 @@ class On(BaseModel):
     def __prepare_values(cls, data: Any) -> Any:
         """Extract tz key from value and change name to timezone key.
 
-        :param data: (DictData) A data that want to pass for create an On
+        :param data: (DictData) A data that want to pass for create an Crontab
             model.
 
         :rtype: DictData
@@ -264,9 +265,9 @@ class On(BaseModel):
         return runner
 
 
-class YearOn(On):
-    """On with enhance Year Pydantic model for limit year matrix that use by
-    some data schedule tools like AWS Glue.
+class CrontabYear(Crontab):
+    """Cron event with enhance Year Pydantic model for limit year matrix that
+    use by some data schedule tools like AWS Glue.
     """
 
     model_config = ConfigDict(arbitrary_types_allowed=True)

{ddeutil_workflow-0.0.56 → ddeutil_workflow-0.0.58}/src/ddeutil/workflow/exceptions.py

@@ -9,16 +9,16 @@ annotate for handle error only.
 """
 from __future__ import annotations
 
-from typing import TypedDict
+from typing import Literal, TypedDict, overload
 
-ErrorData = TypedDict(
-    "ErrorData",
-    {
-        "class": Exception,
-        "name": str,
-        "message": str,
-    },
-)
+
+class ErrorData(TypedDict):
+    """Error data type dict for typing necessary keys of return of to_dict func
+    and method.
+    """
+
+    name: str
+    message: str
 
 
 def to_dict(exception: Exception) -> ErrorData:  # pragma: no cov
@@ -29,20 +29,41 @@ def to_dict(exception: Exception) -> ErrorData:  # pragma: no cov
     :rtype: ErrorData
     """
     return {
-        "class": exception,
         "name": exception.__class__.__name__,
         "message": str(exception),
     }
 
 
 class BaseWorkflowException(Exception):
+    """Base Workflow exception class will implement the `refs` argument for
+    making an error context to the result context.
+    """
+
+    def __init__(self, message: str, *, refs: str | None = None):
+        super().__init__(message)
+        self.refs: str | None = refs
+
+    @overload
+    def to_dict(
+        self, with_refs: Literal[True] = ...
+    ) -> dict[str, ErrorData]: ...  # pragma: no cov
+
+    @overload
+    def to_dict(
+        self, with_refs: Literal[False] = ...
+    ) -> ErrorData: ...  # pragma: no cov
 
-    def to_dict(self) -> ErrorData:
+    def to_dict(
+        self, with_refs: bool = False
+    ) -> ErrorData | dict[str, ErrorData]:
         """Return ErrorData data from the current exception object.
 
         :rtype: ErrorData
         """
-        return to_dict(self)
+        data: ErrorData = to_dict(self)
+        if with_refs and (self.refs is not None and self.refs != "EMPTY"):
+            return {self.refs: data}
+        return data
 
 
 class UtilException(BaseWorkflowException): ...