ddeutil-workflow 0.0.67__tar.gz → 0.0.68__tar.gz

{ddeutil_workflow-0.0.67 → ddeutil_workflow-0.0.68}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ddeutil-workflow
-Version: 0.0.67
+Version: 0.0.68
 Summary: Lightweight workflow orchestration with YAML template
 Author-email: ddeutils <korawich.anu@gmail.com>
 License: MIT
@@ -24,10 +24,10 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: ddeutil[checksum]>=0.4.8
 Requires-Dist: ddeutil-io[toml,yaml]>=0.2.14
-Requires-Dist: pydantic==2.11.4
+Requires-Dist: pydantic==2.11.5
 Requires-Dist: pydantic-extra-types==2.10.4
 Requires-Dist: python-dotenv==1.1.0
-Requires-Dist: typer==0.15.4
+Requires-Dist: typer>=0.16.0
 Provides-Extra: all
 Requires-Dist: fastapi<1.0.0,>=0.115.0; extra == "all"
 Requires-Dist: uvicorn; extra == "all"

{ddeutil_workflow-0.0.67 → ddeutil_workflow-0.0.68}/pyproject.toml

@@ -27,10 +27,10 @@ requires-python = ">=3.9.13"
 dependencies = [
     "ddeutil[checksum]>=0.4.8",
     "ddeutil-io[yaml,toml]>=0.2.14",
-    "pydantic==2.11.4",
+    "pydantic==2.11.5",
     "pydantic-extra-types==2.10.4",
     "python-dotenv==1.1.0",
-    "typer==0.15.4",
+    "typer>=0.16.0",
 ]
 dynamic = ["version"]
 
@@ -78,9 +78,10 @@ omit = [
     "src/ddeutil/workflow/__about__.py",
     "src/ddeutil/workflow/__cron.py",
     "src/ddeutil/workflow/__main__.py",
+    "src/ddeutil/workflow/__types.py",
     "src/ddeutil/workflow/cli.py",
     "src/ddeutil/workflow/api/__init__.py",
-    "src/ddeutil/workflow/api/logs.py",
+    "src/ddeutil/workflow/api/log_conf.py",
     "src/ddeutil/workflow/api/routes/__init__.py",
     "src/ddeutil/workflow/api/routes/job.py",
     "src/ddeutil/workflow/api/routes/logs.py",

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

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

{ddeutil_workflow-0.0.67 → ddeutil_workflow-0.0.68}/src/ddeutil/workflow/api/__init__.py

@@ -6,6 +6,7 @@
 from __future__ import annotations
 
 import contextlib
+import logging
 from collections.abc import AsyncIterator
 
 from dotenv import load_dotenv
@@ -19,11 +20,10 @@ from fastapi.responses import UJSONResponse
 
 from ..__about__ import __version__
 from ..conf import api_config
-from ..logs import get_logger
 from .routes import job, log, workflow
 
 load_dotenv()
-logger = get_logger("uvicorn.error")
+logger = logging.getLogger("uvicorn.error")
 
 
 @contextlib.asynccontextmanager
@@ -58,12 +58,16 @@ app.add_middleware(
 
 
 @app.get(path="/", response_class=UJSONResponse)
-async def health():
+async def health() -> UJSONResponse:
     """Index view that not return any template without json status."""
-    return {"message": "Workflow already start up with healthy status."}
+    logger.info("[API]: Workflow API Application already running ...")
+    return UJSONResponse(
+        content={"message": "Workflow already start up with healthy status."},
+        status_code=st.HTTP_200_OK,
+    )
 
 
-# NOTE Add the jobs and logs routes by default.
+# NOTE: Add the jobs and logs routes by default.
 app.include_router(job, prefix=api_config.prefix_path)
 app.include_router(log, prefix=api_config.prefix_path)
 app.include_router(workflow, prefix=api_config.prefix_path)
@@ -71,21 +75,18 @@ app.include_router(workflow, prefix=api_config.prefix_path)
 
 @app.exception_handler(RequestValidationError)
 async def validation_exception_handler(
-    request: Request, exc: RequestValidationError
-):
+    request: Request,
+    exc: RequestValidationError,
+) -> UJSONResponse:
+    """Error Handler for model validate does not valid."""
     _ = request
     return UJSONResponse(
         status_code=st.HTTP_422_UNPROCESSABLE_ENTITY,
-        content=jsonable_encoder({"detail": exc.errors(), "body": exc.body}),
-    )
-
-
-if __name__ == "__main__":
-    import uvicorn
-
-    uvicorn.run(
-        app,
-        host="0.0.0.0",
-        port=80,
-        log_level="DEBUG",
+        content=jsonable_encoder(
+            {
+                "message": "Body does not parsing with model.",
+                "detail": exc.errors(),
+                "body": exc.body,
+            }
+        ),
     )

ddeutil_workflow-0.0.67/src/ddeutil/workflow/api/logs.py → ddeutil_workflow-0.0.68/src/ddeutil/workflow/api/log_conf.py

@@ -1,6 +1,8 @@
+from typing import Any
+
 from ..conf import config
 
-LOGGING_CONFIG = {  # pragma: no cov
+LOGGING_CONFIG: dict[str, Any] = {  # pragma: no cov
     "version": 1,
     "disable_existing_loggers": False,
     "formatters": {
@@ -22,38 +24,49 @@ LOGGING_CONFIG = {  # pragma: no cov
             "stream": "ext://sys.stderr",
         },
         "stream_handler": {
+            # "formatter": "standard",
             "formatter": "custom_formatter",
             "class": "logging.StreamHandler",
             "stream": "ext://sys.stdout",
         },
-        "file_handler": {
-            "formatter": "custom_formatter",
-            "class": "logging.handlers.RotatingFileHandler",
-            "filename": "logs/app.log",
-            "maxBytes": 1024 * 1024 * 1,
-            "backupCount": 3,
-        },
+        # "file_handler": {
+        #     "formatter": "custom_formatter",
+        #     "class": "logging.handlers.RotatingFileHandler",
+        #     "filename": "logs/app.log",
+        #     "maxBytes": 1024 * 1024 * 1,
+        #     "backupCount": 3,
+        # },
     },
     "loggers": {
         "uvicorn": {
-            "handlers": ["default", "file_handler"],
+            # "handlers": ["default", "file_handler"],
+            "handlers": ["default"],
             "level": "DEBUG" if config.debug else "INFO",
             "propagate": False,
         },
         "uvicorn.access": {
-            "handlers": ["stream_handler", "file_handler"],
+            # "handlers": ["stream_handler", "file_handler"],
+            "handlers": ["stream_handler"],
             "level": "DEBUG" if config.debug else "INFO",
             "propagate": False,
         },
         "uvicorn.error": {
-            "handlers": ["stream_handler", "file_handler"],
+            # "handlers": ["stream_handler", "file_handler"],
+            "handlers": ["stream_handler"],
             "level": "DEBUG" if config.debug else "INFO",
             "propagate": False,
         },
-        # "uvicorn.asgi": {
-        #     "handlers": ["stream_handler", "file_handler"],
-        #     "level": "TRACE",
-        #     "propagate": False,
+        "uvicorn.asgi": {
+            # "handlers": ["stream_handler", "file_handler"],
+            "handlers": ["stream_handler"],
+            "level": "TRACE",
+            "propagate": False,
+        },
+        # "ddeutil.workflow": {
+        #     "handlers": ["stream_handler"],
+        #     "level": "INFO",
+        #     # "propagate": False,
+        #     "propagate": True,
         # },
     },
 }

{ddeutil_workflow-0.0.67 → ddeutil_workflow-0.0.68}/src/ddeutil/workflow/api/routes/__init__.py

@@ -3,6 +3,6 @@
 # Licensed under the MIT License. See LICENSE in the project root for
 # license information.
 # ------------------------------------------------------------------------------
-from .job import job_route as job
-from .logs import log_route as log
-from .workflows import workflow_route as workflow
+from .job import router as job
+from .logs import router as log
+from .workflows import router as workflow

{ddeutil_workflow-0.0.67 → ddeutil_workflow-0.0.68}/src/ddeutil/workflow/api/routes/job.py

@@ -5,20 +5,21 @@
 # ------------------------------------------------------------------------------
 from __future__ import annotations
 
+import logging
 from typing import Any, Optional
 
 from fastapi import APIRouter
+from fastapi import status as st
 from fastapi.responses import UJSONResponse
 from pydantic import BaseModel, Field
 
 from ...__types import DictData
 from ...errors import JobError
 from ...job import Job
-from ...logs import get_logger
 from ...result import Result
 
-logger = get_logger("uvicorn.error")
-job_route = APIRouter(prefix="/job", tags=["job"])
+logger = logging.getLogger("uvicorn.error")
+router = APIRouter(prefix="/job", tags=["job"])
 
 
 class ResultCreate(BaseModel):
@@ -32,14 +33,19 @@ class ResultCreate(BaseModel):
     )
 
 
-@job_route.post(path="/execute/", response_class=UJSONResponse)
+@router.post(
+    path="/execute/",
+    response_class=UJSONResponse,
+    status_code=st.HTTP_200_OK,
+)
 async def job_execute(
     result: ResultCreate,
     job: Job,
     params: dict[str, Any],
     extras: Optional[dict[str, Any]] = None,
-):
+) -> UJSONResponse:
     """Execute job via RestAPI with execute route path."""
+    logger.info("[API]: Start execute job ...")
     rs: Result = Result(
         run_id=result.run_id,
         parent_run_id=result.parent_run_id,
@@ -61,15 +67,35 @@ async def job_execute(
         )
     except JobError as err:
         rs.trace.error(f"[JOB]: {err.__class__.__name__}: {err}")
+        return UJSONResponse(
+            content={
+                "message": str(err),
+                "result": {
+                    "run_id": rs.run_id,
+                    "parent_run_id": rs.parent_run_id,
+                },
+                "job": job.model_dump(
+                    by_alias=True,
+                    exclude_none=False,
+                    exclude_unset=True,
+                ),
+                "params": params,
+                "context": context,
+            },
+            status_code=st.HTTP_500_INTERNAL_SERVER_ERROR,
+        )
 
-    return {
-        "message": "Execute job via RestAPI.",
-        "result": {"run_id": rs.run_id, "parent_run_id": rs.parent_run_id},
-        "job": job.model_dump(
-            by_alias=True,
-            exclude_none=False,
-            exclude_unset=True,
-        ),
-        "params": params,
-        "context": context,
-    }
+    return UJSONResponse(
+        content={
+            "message": "Execute job via RestAPI successful.",
+            "result": {"run_id": rs.run_id, "parent_run_id": rs.parent_run_id},
+            "job": job.model_dump(
+                by_alias=True,
+                exclude_none=False,
+                exclude_unset=True,
+            ),
+            "params": params,
+            "context": context,
+        },
+        status_code=st.HTTP_200_OK,
+    )

{ddeutil_workflow-0.0.67 → ddeutil_workflow-0.0.68}/src/ddeutil/workflow/api/routes/logs.py

@@ -13,14 +13,14 @@ from fastapi.responses import UJSONResponse
 from ...logs import get_audit
 from ...result import Result
 
-log_route = APIRouter(
+router = APIRouter(
     prefix="/logs",
     tags=["logs"],
     default_response_class=UJSONResponse,
 )
 
 
-@log_route.get(
+@router.get(
     path="/traces/",
     response_class=UJSONResponse,
     status_code=st.HTTP_200_OK,
@@ -50,7 +50,7 @@ async def get_traces(
     }
 
 
-@log_route.get(
+@router.get(
     path="/traces/{run_id}",
     response_class=UJSONResponse,
     status_code=st.HTTP_200_OK,
@@ -77,7 +77,7 @@ async def get_trace_with_id(run_id: str):
     }
 
 
-@log_route.get(
+@router.get(
     path="/audits/",
     response_class=UJSONResponse,
     status_code=st.HTTP_200_OK,
@@ -94,7 +94,7 @@ async def get_audits():
     }
 
 
-@log_route.get(
+@router.get(
     path="/audits/{workflow}/",
     response_class=UJSONResponse,
     status_code=st.HTTP_200_OK,
@@ -113,7 +113,7 @@ async def get_audit_with_workflow(workflow: str):
     }
 
 
-@log_route.get(
+@router.get(
     path="/audits/{workflow}/{release}",
     response_class=UJSONResponse,
     status_code=st.HTTP_200_OK,
@@ -140,7 +140,7 @@ async def get_audit_with_workflow_release(
     }
 
 
-@log_route.get(
+@router.get(
     path="/audits/{workflow}/{release}/{run_id}",
     response_class=UJSONResponse,
     status_code=st.HTTP_200_OK,

{ddeutil_workflow-0.0.67 → ddeutil_workflow-0.0.68}/src/ddeutil/workflow/api/routes/workflows.py

@@ -5,6 +5,7 @@
 # ------------------------------------------------------------------------------
 from __future__ import annotations
 
+import logging
 from dataclasses import asdict
 from datetime import datetime
 from typing import Any
@@ -16,19 +17,19 @@ from pydantic import BaseModel
 
 from ...__types import DictData
 from ...conf import Loader
-from ...logs import Audit, get_audit, get_logger
+from ...logs import AuditModel, get_audit
 from ...result import Result
 from ...workflow import Workflow
 
-logger = get_logger("uvicorn.error")
-workflow_route = APIRouter(
+logger = logging.getLogger("uvicorn.error")
+router = APIRouter(
     prefix="/workflows",
     tags=["workflows"],
     default_response_class=UJSONResponse,
 )
 
 
-@workflow_route.get(path="/", status_code=st.HTTP_200_OK)
+@router.get(path="/", status_code=st.HTTP_200_OK)
 async def get_workflows() -> DictData:
     """Return all workflow workflows that exists in config path."""
     workflows: DictData = dict(Loader.finds(Workflow))
@@ -39,7 +40,7 @@ async def get_workflows() -> DictData:
     }
 
 
-@workflow_route.get(path="/{name}", status_code=st.HTTP_200_OK)
+@router.get(path="/{name}", status_code=st.HTTP_200_OK)
 async def get_workflow_by_name(name: str) -> DictData:
     """Return model of workflow that passing an input workflow name."""
     try:
@@ -63,7 +64,7 @@ class ExecutePayload(BaseModel):
     params: dict[str, Any]
 
 
-@workflow_route.post(path="/{name}/execute", status_code=st.HTTP_202_ACCEPTED)
+@router.post(path="/{name}/execute", status_code=st.HTTP_202_ACCEPTED)
 async def workflow_execute(name: str, payload: ExecutePayload) -> DictData:
     """Return model of workflow that passing an input workflow name."""
     try:
@@ -88,7 +89,7 @@ async def workflow_execute(name: str, payload: ExecutePayload) -> DictData:
     return asdict(result)
 
 
-@workflow_route.get(path="/{name}/audits", status_code=st.HTTP_200_OK)
+@router.get(path="/{name}/audits", status_code=st.HTTP_200_OK)
 async def get_workflow_audits(name: str):
     try:
         return {
@@ -109,11 +110,11 @@ async def get_workflow_audits(name: str):
         ) from None
 
 
-@workflow_route.get(path="/{name}/audits/{release}", status_code=st.HTTP_200_OK)
+@router.get(path="/{name}/audits/{release}", status_code=st.HTTP_200_OK)
 async def get_workflow_release_audit(name: str, release: str):
     """Get Workflow audit log with an input release value."""
     try:
-        audit: Audit = get_audit().find_audit_with_release(
+        audit: AuditModel = get_audit().find_audit_with_release(
             name=name,
             release=datetime.strptime(release, "%Y%m%d%H%M%S"),
         )

ddeutil_workflow-0.0.68/src/ddeutil/workflow/cli.py

@@ -0,0 +1,119 @@
+import json
+from pathlib import Path
+from platform import python_version
+from typing import Annotated, Any, Optional
+
+import typer
+import uvicorn
+
+from .__about__ import __version__
+from .__types import DictData
+from .api import app as fastapp
+from .errors import JobError
+from .job import Job
+from .result import Result
+
+app = typer.Typer(
+    pretty_exceptions_enable=True,
+)
+
+
+@app.callback()
+def callback():
+    """Manage Workflow CLI app.
+
+    Use it with the interface workflow engine.
+    """
+
+
+@app.command()
+def version():
+    """Get the ddeutil-workflow package version."""
+    typer.echo(f"ddeutil-workflow=={__version__}")
+    typer.echo(f"python-version=={python_version()}")
+
+
+@app.command()
+def job(
+    params: Annotated[str, typer.Option(help="A job execute parameters")],
+    job: Annotated[str, typer.Option(help="A job model")],
+    parent_run_id: Annotated[str, typer.Option(help="A parent running ID")],
+    run_id: Annotated[Optional[str], typer.Option(help="A running ID")] = None,
+) -> None:
+    """Job execution on the local.
+
+    Example:
+        ... workflow-cli job --params "{\"test\": 1}"
+    """
+    try:
+        params_dict: dict[str, Any] = json.loads(params)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Params does not support format: {params!r}.") from e
+
+    try:
+        job_dict: dict[str, Any] = json.loads(job)
+        _job: Job = Job.model_validate(obj=job_dict)
+    except json.JSONDecodeError as e:
+        raise ValueError(f"Params does not support format: {params!r}.") from e
+
+    typer.echo(f"Job params: {params_dict}")
+    rs: Result = Result(
+        run_id=run_id,
+        parent_run_id=parent_run_id,
+    )
+
+    context: DictData = {}
+    try:
+        _job.set_outputs(
+            _job.execute(
+                params=params_dict,
+                run_id=rs.run_id,
+                parent_run_id=rs.parent_run_id,
+            ).context,
+            to=context,
+        )
+    except JobError as err:
+        rs.trace.error(f"[JOB]: {err.__class__.__name__}: {err}")
+
+
+@app.command()
+def api(
+    host: Annotated[str, typer.Option(help="A host url.")] = "0.0.0.0",
+    port: Annotated[int, typer.Option(help="A port url.")] = 80,
+    debug: Annotated[bool, typer.Option(help="A debug mode flag")] = True,
+    workers: Annotated[int, typer.Option(help="A worker number")] = None,
+    reload: Annotated[bool, typer.Option(help="A reload flag")] = False,
+):
+    """
+    Provision API application from the FastAPI.
+    """
+    from .api.log_conf import LOGGING_CONFIG
+
+    # LOGGING_CONFIG = {}
+
+    uvicorn.run(
+        fastapp,
+        host=host,
+        port=port,
+        log_config=uvicorn.config.LOGGING_CONFIG | LOGGING_CONFIG,
+        # NOTE: Logging level of uvicorn should be lowered case.
+        log_level=("debug" if debug else "info"),
+        workers=workers,
+        reload=reload,
+    )
+
+
+@app.command()
+def make(
+    name: Annotated[Path, typer.Argument()],
+) -> None:
+    """
+    Create Workflow YAML template.
+
+    :param name:
+    """
+    typer.echo(f"Start create YAML template filename: {name.resolve()}")
+
+
+if __name__ == "__main__":
+    app()

{ddeutil_workflow-0.0.67 → ddeutil_workflow-0.0.68}/src/ddeutil/workflow/conf.py

@@ -109,9 +109,9 @@ class Config:  # pragma: no cov
         return env(
             "LOG_FORMAT",
             (
-                "%(asctime)s.%(msecs)03d (%(name)-10s, %(process)-5d, "
+                "%(asctime)s.%(msecs)03d (%(process)-5d, "
                 "%(thread)-5d) [%(levelname)-7s] %(message)-120s "
-                "(%(filename)s:%(lineno)s)"
+                "(%(filename)s:%(lineno)s) (%(name)-10s)"
             ),
         )
 
@@ -161,9 +161,13 @@ class Config:  # pragma: no cov
 class APIConfig:
     """API Config object."""
 
+    @property
+    def version(self) -> str:
+        return env("API_VERSION", "1")
+
     @property
     def prefix_path(self) -> str:
-        return env("API_PREFIX_PATH", "/api/v1")
+        return env("API_PREFIX_PATH", f"/api/v{self.version}")
 
 
 class BaseLoad(ABC):  # pragma: no cov

{ddeutil_workflow-0.0.67 → ddeutil_workflow-0.0.68}/src/ddeutil/workflow/event.py

@@ -3,8 +3,9 @@
 # Licensed under the MIT License. See LICENSE in the project root for
 # license information.
 # ------------------------------------------------------------------------------
-"""Event module include all event object for trigger the Workflow to release.
-Now, it has only `Crontab` and `CrontabYear` event models on this module because
+"""An Event module keep all triggerable object to the Workflow model. The simple
+event trigger that use to run workflow is `Crontab` model.
+Now, it has only `Crontab` and `CrontabYear` event models in this module because
 I think it is the core event for workflow orchestration.
 """
 from __future__ import annotations
@@ -95,7 +96,7 @@ class Crontab(BaseModel):
     tz: Annotated[
         TimeZoneName,
         Field(
-            description="A timezone string value",
+            description="A timezone string value.",
             alias="timezone",
         ),
     ] = "UTC"

{ddeutil_workflow-0.0.67 → ddeutil_workflow-0.0.68}/src/ddeutil/workflow/logs.py

@@ -37,33 +37,34 @@ METADATA: str = "metadata.json"
 
 
 @lru_cache
-def get_logger(name: str):
-    """Return logger object with an input module name.
+def set_logging(name: str) -> logging.Logger:
+    """Return logger object with an input module name that already implement the
+    custom handler and formatter from this package config.
 
     :param name: (str) A module name that want to log.
+
+    :rtype: logging.Logger
     """
-    lg = logging.getLogger(name)
+    _logger = logging.getLogger(name)
 
     # NOTE: Developers using this package can then disable all logging just for
     #   this package by;
     #
     #   `logging.getLogger('ddeutil.workflow').propagate = False`
     #
-    lg.addHandler(logging.NullHandler())
+    _logger.addHandler(logging.NullHandler())
 
     formatter = logging.Formatter(
-        fmt=config.log_format,
-        datefmt=config.log_datetime_format,
+        fmt=config.log_format, datefmt=config.log_datetime_format
     )
-    stream = logging.StreamHandler()
-    stream.setFormatter(formatter)
-    lg.addHandler(stream)
-
-    lg.setLevel(logging.DEBUG if config.debug else logging.INFO)
-    return lg
+    stream_handler = logging.StreamHandler()
+    stream_handler.setFormatter(formatter)
+    _logger.addHandler(stream_handler)
+    _logger.setLevel(logging.DEBUG if config.debug else logging.INFO)
+    return _logger
 
 
-logger = get_logger("ddeutil.workflow")
+logger = logging.getLogger("ddeutil.workflow")
 
 
 def get_dt_tznow() -> datetime:  # pragma: no cov
@@ -689,6 +690,9 @@ class BaseAudit(BaseModel, ABC):
         """
         if dynamic("enable_write_audit", extras=self.extras):
             self.do_before()
+
+        # NOTE: Start setting log config in this line with cache.
+        set_logging("ddeutil.workflow")
         return self
 
     @classmethod
@@ -732,7 +736,7 @@ class BaseAudit(BaseModel, ABC):
     @abstractmethod
     def save(self, excluded: Optional[list[str]]) -> None:  # pragma: no cov
         """Save this model logging to target logging store."""
-        raise NotImplementedError("Audit should implement ``save`` method.")
+        raise NotImplementedError("Audit should implement `save` method.")
 
 
 class FileAudit(BaseAudit):

{ddeutil_workflow-0.0.67 → ddeutil_workflow-0.0.68}/src/ddeutil/workflow/stages.py

@@ -3,7 +3,7 @@
 # Licensed under the MIT License. See LICENSE in the project root for
 # license information.
 # ------------------------------------------------------------------------------
-"""Stages module include all stage model that implemented to be the minimum execution
+r"""Stages module include all stage model that implemented to be the minimum execution
 layer of this workflow core engine. The stage handle the minimize task that run
 in a thread (same thread at its job owner) that mean it is the lowest executor that
 you can track logs.
@@ -15,17 +15,39 @@ have a lot of use-case, and it should does not worry about it error output.
     So, I will create `handler_execute` for any exception class that raise from
 the stage execution method.
 
-    Execution   --> Ok      ┬--( handler )--> Result with `SUCCESS` or `CANCEL`
-                            |
-                            ├--( handler )--> Result with `FAILED` (Set `raise_error` flag)
-                            |
-                            ╰--( handler )---> Result with `SKIP`
+    Handler     --> Ok      --> Result
+                                        |-status: SUCCESS
+                                        ╰-context:
+                                            ╰-outputs: ...
 
-                --> Error   ---( handler )--> Raise StageError(...)
+                --> Ok      --> Result
+                                ╰-status: CANCEL
+
+                --> Ok      --> Result
+                                ╰-status: SKIP
+
+                --> Ok      --> Result
+                                |-status: FAILED
+                                ╰-errors:
+                                    |-name: ...
+                                    ╰-message: ...
 
     On the context I/O that pass to a stage object at execute process. The
 execute method receives a `params={"params": {...}}` value for passing template
 searching.
+
+    All stages model inherit from `BaseStage` or `AsyncBaseStage` models that has the
+base fields:
+
+| field     | alias | data type   | default  | description                                                           |
+|-----------|-------|-------------|:--------:|-----------------------------------------------------------------------|
+| id        |       | str \| None |  `None`  | A stage ID that use to keep execution output or getting by job owner. |
+| name      |       | str         |          | A stage name that want to log when start execution.               |
+| condition | if    | str \| None |  `None`  | A stage condition statement to allow stage executable.                |
+| extras    |       | dict        | `dict()` | An extra parameter that override core config values.                  |
+
+    It has a special base class is `BaseRetryStage` that inherit from `AsyncBaseStage`
+that use to handle retry execution when it got any error with `retry` field.
 """
 from __future__ import annotations
 
@@ -450,6 +472,13 @@ class BaseStage(BaseModel, ABC):
         """
         return False
 
+    def docs(self) -> str:  # pragma: no cov
+        """Return generated document that will be the interface of this stage.
+
+        :rtype: str
+        """
+        return self.desc
+
 
 class BaseAsyncStage(BaseStage, ABC):
     """Base Async Stage model to make any stage model allow async execution for
@@ -594,7 +623,7 @@ class BaseRetryStage(BaseAsyncStage, ABC):  # pragma: no cov
         default=0,
         ge=0,
         lt=20,
-        description="Retry number if stage execution get the error.",
+        description="A retry number if stage execution get the error.",
     )
 
     def _execute(
@@ -1249,7 +1278,7 @@ class CallStage(BaseRetryStage):
     function complexly that you can for your objective to invoked by this stage
     object.
 
-        This stage is the most powerfull stage of this package for run every
+        This stage is the most powerful stage of this package for run every
     use-case by a custom requirement that you want by creating the Python
     function and adding it to the caller registry value by importer syntax like
     `module.caller.registry` not path style like `module/caller/registry`.

{ddeutil_workflow-0.0.67 → ddeutil_workflow-0.0.68}/src/ddeutil/workflow/utils.py

@@ -6,15 +6,13 @@
 """Utility function model."""
 from __future__ import annotations
 
-import asyncio
 import stat
 import time
 from collections.abc import Iterator
 from datetime import date, datetime, timedelta
-from functools import wraps
 from hashlib import md5
 from inspect import isfunction
-from itertools import chain, islice, product
+from itertools import product
 from pathlib import Path
 from random import randrange
 from typing import Any, Final, Optional, TypeVar, Union, overload
@@ -258,34 +256,6 @@ def cross_product(matrix: Matrix) -> Iterator[DictData]:
     )
 
 
-def batch(iterable: Union[Iterator[Any], range], n: int) -> Iterator[Any]:
-    """Batch data into iterators of length n. The last batch may be shorter.
-
-    Example:
-        >>> for b in batch(iter('ABCDEFG'), 3):
-        ...     print(list(b))
-        ['A', 'B', 'C']
-        ['D', 'E', 'F']
-        ['G']
-
-    :param iterable:
-    :param n: (int) A number of returning batch size.
-
-    :rtype: Iterator[Any]
-    """
-    if n < 1:
-        raise ValueError("n must be at least one")
-
-    it: Iterator[Any] = iter(iterable)
-    while True:
-        chunk_it = islice(it, n)
-        try:
-            first_el = next(chunk_it)
-        except StopIteration:
-            return
-        yield chain((first_el,), chunk_it)
-
-
 def cut_id(run_id: str, *, num: int = 6) -> str:
     """Cutting running ID with length.
 
@@ -325,24 +295,3 @@ def dump_all(
     elif isinstance(value, BaseModel):
         return value.model_dump(by_alias=by_alias)
     return value
-
-
-def awaitable(func):
-    """Dynamic function to async or not depend on the called statement."""
-
-    @wraps(func)
-    async def async_wrapper(*args, **kwargs):
-        return func(*args, **kwargs)
-
-    @wraps(func)
-    def sync_wrapper(*args, **kwargs):
-        return func(*args, **kwargs)
-
-    def dispatch(*args, **kwargs):
-        try:
-            asyncio.get_running_loop()
-            return async_wrapper(*args, **kwargs)
-        except RuntimeError:
-            return sync_wrapper(*args, **kwargs)
-
-    return dispatch

{ddeutil_workflow-0.0.67 → ddeutil_workflow-0.0.68}/src/ddeutil_workflow.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ddeutil-workflow
-Version: 0.0.67
+Version: 0.0.68
 Summary: Lightweight workflow orchestration with YAML template
 Author-email: ddeutils <korawich.anu@gmail.com>
 License: MIT
@@ -24,10 +24,10 @@ Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: ddeutil[checksum]>=0.4.8
 Requires-Dist: ddeutil-io[toml,yaml]>=0.2.14
-Requires-Dist: pydantic==2.11.4
+Requires-Dist: pydantic==2.11.5
 Requires-Dist: pydantic-extra-types==2.10.4
 Requires-Dist: python-dotenv==1.1.0
-Requires-Dist: typer==0.15.4
+Requires-Dist: typer>=0.16.0
 Provides-Extra: all
 Requires-Dist: fastapi<1.0.0,>=0.115.0; extra == "all"
 Requires-Dist: uvicorn; extra == "all"

{ddeutil_workflow-0.0.67 → ddeutil_workflow-0.0.68}/src/ddeutil_workflow.egg-info/SOURCES.txt

@@ -19,7 +19,7 @@ src/ddeutil/workflow/stages.py
 src/ddeutil/workflow/utils.py
 src/ddeutil/workflow/workflow.py
 src/ddeutil/workflow/api/__init__.py
-src/ddeutil/workflow/api/logs.py
+src/ddeutil/workflow/api/log_conf.py
 src/ddeutil/workflow/api/routes/__init__.py
 src/ddeutil/workflow/api/routes/job.py
 src/ddeutil/workflow/api/routes/logs.py

{ddeutil_workflow-0.0.67 → ddeutil_workflow-0.0.68}/src/ddeutil_workflow.egg-info/requires.txt

@@ -1,9 +1,9 @@
 ddeutil[checksum]>=0.4.8
 ddeutil-io[toml,yaml]>=0.2.14
-pydantic==2.11.4
+pydantic==2.11.5
 pydantic-extra-types==2.10.4
 python-dotenv==1.1.0
-typer==0.15.4
+typer>=0.16.0
 
 [all]
 fastapi<1.0.0,>=0.115.0

{ddeutil_workflow-0.0.67 → ddeutil_workflow-0.0.68}/tests/test_utils.py

@@ -6,7 +6,6 @@ from zoneinfo import ZoneInfo
 import pytest
 from ddeutil.workflow.utils import (
     UTC,
-    batch,
     cut_id,
     dump_all,
     filter_func,
@@ -91,15 +90,6 @@ def test_filter_func():
     }
 
 
-def test_batch():
-    with pytest.raises(ValueError):
-        next(batch(range(10), n=-1))
-
-    assert [[0, 1], [2, 3], [4, 5], [6, 7], [8, 9]] == [
-        list(i) for i in batch(range(10), n=2)
-    ]
-
-
 def test_make_exec():
     test_file: str = "./tmp_test_make_exec.txt"
 

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

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

ddeutil_workflow-0.0.67/src/ddeutil/workflow/cli.py

@@ -1,68 +0,0 @@
-import json
-from typing import Annotated, Any
-
-import typer
-import uvicorn
-
-from .__about__ import __version__
-from .api import app as fastapp
-from .api.logs import LOGGING_CONFIG
-
-app = typer.Typer(
-    pretty_exceptions_enable=True,
-)
-
-
-@app.callback()
-def callback():
-    """
-    Awesome Portal Gun
-    """
-    typer.echo("Start call from callback function")
-
-
-@app.command()
-def version():
-    """Get the ddeutil-workflow package version."""
-    typer.echo(__version__)
-
-
-@app.command()
-def job(
-    params: Annotated[str, typer.Option(help="A job execute parameters")],
-):
-    """Job execution on the local.
-
-    Example:
-        ... workflow-cli job --params "{\"test\": 1}"
-    """
-    try:
-        params_dict: dict[str, Any] = json.loads(params)
-    except json.JSONDecodeError as e:
-        raise ValueError(f"params does not support format: {params!r}.") from e
-    typer.echo(f"Job params: {params_dict}")
-
-
-@app.command()
-def api(
-    host: Annotated[str, typer.Option(help="A host url.")] = "0.0.0.0",
-    port: Annotated[int, typer.Option(help="A port url.")] = 80,
-    debug: Annotated[bool, typer.Option(help="A debug mode flag")] = True,
-    worker: Annotated[int, typer.Option(help="A worker number")] = None,
-):
-    """
-    Provision API application from the FastAPI.
-    """
-
-    uvicorn.run(
-        fastapp,
-        host=host,
-        port=port,
-        log_config=uvicorn.config.LOGGING_CONFIG | LOGGING_CONFIG,
-        log_level=("DEBUG" if debug else "INFO"),
-        workers=worker,
-    )
-
-
-if __name__ == "__main__":
-    app()