fabricatio 0.2.1.dev0__cp313-cp313-win_amd64.whl → 0.3.14.dev4__cp313-cp313-win_amd64.whl

fabricatio/{core.py → emitter.py}

@@ -1,25 +1,21 @@
 """Core module that contains the Env class for managing event handling."""
+from dataclasses import dataclass
+from typing import Callable, ClassVar, Optional, Self, overload
 
-from typing import Callable, Optional, Self, overload
-
-from pydantic import BaseModel, ConfigDict, PrivateAttr
 from pymitter import EventEmitter
 
-from fabricatio.config import configs
-from fabricatio.models.events import Event
+from fabricatio.rust import CONFIG, Event
 
 
-class Env(BaseModel):
+@dataclass
+class Env:
     """Environment class that manages event handling using EventEmitter."""
 
-    model_config = ConfigDict(use_attribute_docstrings=True)
-    _ee: EventEmitter = PrivateAttr(
-        default_factory=lambda: EventEmitter(
-            delimiter=configs.pymitter.delimiter,
-            new_listener=configs.pymitter.new_listener_event,
-            max_listeners=configs.pymitter.max_listeners,
-            wildcard=True,
-        )
+    ee: ClassVar[EventEmitter] = EventEmitter(
+        delimiter=CONFIG.pymitter.delimiter,
+        new_listener=CONFIG.pymitter.new_listener_event,
+        max_listeners=CONFIG.pymitter.max_listeners,
+        wildcard=True,
     )
 
     @overload
@@ -77,9 +73,8 @@ class Env(BaseModel):
         if isinstance(event, Event):
             event = event.collapse()
         if func is None:
-            return self._ee.on(event, ttl=ttl)
-
-        self._ee.on(event, func, ttl=ttl)
+            return self.ee.on(event, ttl=ttl)
+        self.ee.on(event, func, ttl=ttl)
         return self
 
     @overload
@@ -133,9 +128,9 @@ class Env(BaseModel):
         if isinstance(event, Event):
             event = event.collapse()
         if func is None:
-            return self._ee.once(event)
+            return self.ee.once(event)
 
-        self._ee.once(event, func)
+        self.ee.once(event, func)
         return self
 
     def emit[**P](self, event: str | Event, *args: P.args, **kwargs: P.kwargs) -> None:
@@ -149,7 +144,7 @@ class Env(BaseModel):
         if isinstance(event, Event):
             event = event.collapse()
 
-        self._ee.emit(event, *args, **kwargs)
+        self.ee.emit(event, *args, **kwargs)
 
     async def emit_async[**P](self, event: str | Event, *args: P.args, **kwargs: P.kwargs) -> None:
         """Asynchronously emits an event to all registered listeners.
@@ -161,7 +156,22 @@ class Env(BaseModel):
         """
         if isinstance(event, Event):
             event = event.collapse()
-        return await self._ee.emit_async(event, *args, **kwargs)
+        return await self.ee.emit_async(event, *args, **kwargs)
+
+    def emit_future[**P](self, event: str | Event, *args: P.args, **kwargs: P.kwargs) -> None:
+        """Emits an event to all registered listeners and returns a future object.
+
+        Args:
+            event (str | Event): The event to emit.
+            *args: Positional arguments to pass to the listeners.
+            **kwargs: Keyword arguments to pass to the listeners.
+
+        Returns:
+            None: The future object.
+        """
+        if isinstance(event, Event):
+            event = event.collapse()
+        return self.ee.emit_future(event, *args, **kwargs)
 
 
 env = Env()

fabricatio/fs/__init__.py

@@ -1,5 +1,35 @@
 """FileSystem manipulation module for Fabricatio."""
+from importlib.util import find_spec
 
-from fabricatio.fs.readers import magika
+from fabricatio.fs.curd import (
+    absolute_path,
+    copy_file,
+    create_directory,
+    delete_directory,
+    delete_file,
+    dump_text,
+    gather_files,
+    move_file,
+    tree,
+)
+from fabricatio.fs.readers import safe_json_read, safe_text_read
 
-__all__ = ["magika"]
+__all__ = [
+    "absolute_path",
+    "copy_file",
+    "create_directory",
+    "delete_directory",
+    "delete_file",
+    "dump_text",
+    "gather_files",
+    "move_file",
+    "safe_json_read",
+    "safe_text_read",
+    "tree",
+]
+
+if find_spec("magika"):
+    from magika import Magika
+
+    MAGIKA = Magika()
+    __all__ += ["MAGIKA"]

fabricatio/fs/curd.py

@@ -2,14 +2,14 @@
 
 import shutil
 import subprocess
+from os import PathLike
 from pathlib import Path
 from typing import Union
 
-from fabricatio.decorators import depend_on_external_cmd, logging_execution_info
+from fabricatio.decorators import depend_on_external_cmd
 from fabricatio.journal import logger
 
 
-@logging_execution_info
 def dump_text(path: Union[str, Path], text: str) -> None:
     """Dump text to a file. you need to make sure the file's parent directory exists.
 
@@ -20,10 +20,9 @@ def dump_text(path: Union[str, Path], text: str) -> None:
     Returns:
         None
     """
-    Path(path).write_text(text, encoding="utf-8", errors="ignore")
+    Path(path).write_text(text, encoding="utf-8", errors="ignore", newline="\n")
 
 
-@logging_execution_info
 def copy_file(src: Union[str, Path], dst: Union[str, Path]) -> None:
     """Copy a file from source to destination.
 
@@ -43,7 +42,6 @@ def copy_file(src: Union[str, Path], dst: Union[str, Path]) -> None:
         raise
 
 
-@logging_execution_info
 def move_file(src: Union[str, Path], dst: Union[str, Path]) -> None:
     """Move a file from source to destination.
 
@@ -63,7 +61,6 @@ def move_file(src: Union[str, Path], dst: Union[str, Path]) -> None:
         raise
 
 
-@logging_execution_info
 def delete_file(file_path: Union[str, Path]) -> None:
     """Delete a file.
 
@@ -82,7 +79,6 @@ def delete_file(file_path: Union[str, Path]) -> None:
         raise
 
 
-@logging_execution_info
 def create_directory(dir_path: Union[str, Path], parents: bool = True, exist_ok: bool = True) -> None:
     """Create a directory.
 
@@ -99,7 +95,6 @@ def create_directory(dir_path: Union[str, Path], parents: bool = True, exist_ok:
         raise
 
 
-@logging_execution_info
 @depend_on_external_cmd(
     "erd",
     "Please install `erd` using `cargo install erdtree` or `scoop install erdtree`.",
@@ -111,7 +106,6 @@ def tree(dir_path: Union[str, Path]) -> str:
     return subprocess.check_output(("erd", dir_path.as_posix()), encoding="utf-8")  # noqa: S603
 
 
-@logging_execution_info
 def delete_directory(dir_path: Union[str, Path]) -> None:
     """Delete a directory and its contents.
 
@@ -128,3 +122,32 @@ def delete_directory(dir_path: Union[str, Path]) -> None:
     except OSError as e:
         logger.error(f"Failed to delete directory {dir_path}: {e!s}")
         raise
+
+
+def absolute_path(path: str | Path | PathLike) -> str:
+    """Get the absolute path of a file or directory.
+
+    Args:
+        path (str, Path, PathLike): The path to the file or directory.
+
+    Returns:
+        str: The absolute path of the file or directory.
+    """
+    return Path(path).expanduser().resolve().as_posix()
+
+
+def gather_files(directory: str | Path | PathLike, extension: str) -> list[str]:
+    """Gather all files with a specific extension in a directory.
+
+    Args:
+        directory (str, Path, PathLike): The directory to search in.
+        extension (str): The file extension to look for.
+
+    Returns:
+        list[str]: A list of file paths with the specified extension.
+
+    Example:
+        >>> gather_files('/path/to/directory', 'txt')
+        ['/path/to/directory/file1.txt', '/path/to/directory/file2.txt']
+    """
+    return [file.as_posix() for file in Path(directory).rglob(f"*.{extension}")]

fabricatio/fs/readers.py

@@ -1,24 +1,61 @@
 """Filesystem readers for Fabricatio."""
 
+import re
 from pathlib import Path
+from typing import Dict, List, Tuple
 
-from magika import Magika
+import ujson
 
-from fabricatio.config import configs
+from fabricatio.journal import logger
 
-magika = Magika(model_dir=configs.magika.model_dir)
 
-
-def safe_text_read(path: Path) -> str:
+def safe_text_read(path: Path | str) -> str:
     """Safely read the text from a file.
 
     Args:
-        path (Path): The path to the file.
+        path (Path|str): The path to the file.
 
     Returns:
         str: The text from the file.
     """
+    path = Path(path)
     try:
         return path.read_text(encoding="utf-8")
-    except (UnicodeDecodeError, IsADirectoryError, FileNotFoundError):
+    except (UnicodeDecodeError, IsADirectoryError, FileNotFoundError) as e:
+        logger.error(f"Failed to read file {path}: {e!s}")
         return ""
+
+
+def safe_json_read(path: Path | str) -> Dict:
+    """Safely read the JSON from a file.
+
+    Args:
+        path (Path|str): The path to the file.
+
+    Returns:
+        dict: The JSON from the file.
+    """
+    path = Path(path)
+    try:
+        return ujson.loads(path.read_text(encoding="utf-8"))
+    except (ujson.JSONDecodeError, IsADirectoryError, FileNotFoundError) as e:
+        logger.error(f"Failed to read file {path}: {e!s}")
+        return {}
+
+
+def extract_sections(string: str, level: int, section_char: str = "#") -> List[Tuple[str, str]]:
+    """Extract sections from markdown-style text by header level.
+
+    Args:
+        string (str): Input text to parse
+        level (int): Header level (e.g., 1 for '#', 2 for '##')
+        section_char (str, optional): The character used for headers (default: '#')
+
+    Returns:
+        List[Tuple[str, str]]: List of (header_text, section_content) tuples
+    """
+    return re.findall(
+        r"^%s{%d}\s+(.+?)\n((?:(?!^%s{%d}\s).|\n)*)" % (section_char, level, section_char, level),
+        string,
+        re.MULTILINE,
+    )

fabricatio/journal.py

@@ -3,26 +3,10 @@
 import sys
 
 from loguru import logger
-from rich import pretty, traceback
 
-from fabricatio.config import configs
+from fabricatio.rust import CONFIG
 
-pretty.install()
-traceback.install()
 logger.remove()
-logger.add(
-    configs.debug.log_file,
-    level=configs.debug.log_level,
-    rotation=f"{configs.debug.rotation} weeks",
-    retention=f"{configs.debug.retention} weeks",
-)
-logger.add(sys.stderr, level=configs.debug.log_level)
+logger.add(sys.stderr, level=CONFIG.debug.log_level)
 
-
-if __name__ == "__main__":
-    logger.debug("This is a trace message.")
-    logger.info("This is an information message.")
-    logger.success("This is a success message.")
-    logger.warning("This is a warning message.")
-    logger.error("This is an error message.")
-    logger.critical("This is a critical message.")
+__all__ = ["logger"]

fabricatio/models/action.py

@@ -1,139 +1,263 @@
-"""Module that contains the classes for actions and workflows."""
+"""Module that contains the classes for defining and executing task workflows.
+
+This module provides the Action and WorkFlow classes for creating structured
+task execution pipelines. Actions represent atomic operations, while WorkFlows
+orchestrate sequences of actions with shared context and error handling.
+
+Classes:
+    Action: Base class for defining executable actions with context management.
+    WorkFlow: Manages action sequences, context propagation, and task lifecycle.
+"""
 
 import traceback
 from abc import abstractmethod
-from asyncio import Queue
-from typing import Any, Dict, Self, Tuple, Type, Union, Unpack
+from asyncio import Queue, create_task
+from typing import Any, ClassVar, Dict, Generator, Self, Sequence, Tuple, Type, Union, final
 
 from fabricatio.journal import logger
-from fabricatio.models.advanced import HandleTask, ProposeTask
 from fabricatio.models.generic import WithBriefing
 from fabricatio.models.task import Task
-from fabricatio.models.usages import ToolBoxUsage
+from fabricatio.utils import override_kwargs
 from pydantic import Field, PrivateAttr
 
+OUTPUT_KEY = "task_output"
+
+INPUT_KEY = "task_input"
+
+
+class Action(WithBriefing):
+    """Class that represents an action to be executed in a workflow.
+
+    Actions are the atomic units of work in a workflow. Each action performs
+    a specific operation and can modify the shared context data.
+    """
+
+    ctx_override: ClassVar[bool] = False
+    """Whether to override the instance attr by the context variable."""
 
-class Action(HandleTask, ProposeTask):
-    """Class that represents an action to be executed in a workflow."""
+    name: str = Field(default="")
+    """The name of the action."""
+
+    description: str = Field(default="")
+    """The description of the action."""
 
     personality: str = Field(default="")
-    """The personality of whom the action belongs to."""
+    """The personality traits or context for the action executor."""
+
     output_key: str = Field(default="")
-    """The key of the output data."""
+    """The key used to store this action's output in the context dictionary."""
+
+    @final
+    def model_post_init(self, __context: Any) -> None:
+        """Initialize the action by setting default name and description if not provided.
+
+        Args:
+            __context: The context to be used for initialization.
+        """
+        self.name = self.name or self.__class__.__name__
+        self.description = self.description or self.__class__.__doc__ or ""
 
     @abstractmethod
-    async def _execute(self, **cxt: Unpack) -> Any:
-        """Execute the action with the provided arguments.
+    async def _execute(self, *_: Any, **cxt) -> Any:
+        """Implement the core logic of the action.
 
         Args:
-            **cxt: The context dictionary containing input and output data.
+            **cxt: Context dictionary containing input/output data.
 
         Returns:
-            The result of the action execution.
+            Result of the action execution to be stored in context.
         """
         pass
 
+    @final
     async def act(self, cxt: Dict[str, Any]) -> Dict[str, Any]:
-        """Perform the action by executing it and setting the output data.
+        """Execute action and update context.
 
         Args:
-            cxt: The context dictionary containing input and output data.
+            cxt (Dict[str, Any]): Shared context dictionary.
+
+        Returns:
+            Updated context dictionary with new/modified entries.
         """
         ret = await self._execute(**cxt)
+
         if self.output_key:
             logger.debug(f"Setting output: {self.output_key}")
             cxt[self.output_key] = ret
+
         return cxt
 
+    @property
     def briefing(self) -> str:
-        """Return a brief description of the action."""
+        """Generate formatted action description with personality context.
+
+        Returns:
+            Briefing text combining personality and action description.
+        """
         if self.personality:
             return f"## Your personality: \n{self.personality}\n# The action you are going to perform: \n{super().briefing}"
         return f"# The action you are going to perform: \n{super().briefing}"
 
+    def to_task_output(self, to: Union[str, "WorkFlow"] = OUTPUT_KEY) -> Self:
+        """Set the output key to OUTPUT_KEY and return the action instance."""
+        self.output_key = to.task_output_key if isinstance(to, WorkFlow) else to
+        return self
+
 
-class WorkFlow(WithBriefing, ToolBoxUsage):
-    """Class that represents a workflow to be executed in a task."""
+class WorkFlow(WithBriefing):
+    """Manages sequences of actions to fulfill tasks.
+
+    Handles context propagation between actions, error handling, and task lifecycle
+    events like cancellation and completion.
+    """
+
+    name: str = "WorkFlow"
+    """The name of the workflow, which is used to identify and describe the workflow."""
+    description: str = ""
+    """The description of the workflow, which describes the workflow's purpose and requirements."""
 
     _context: Queue[Dict[str, Any]] = PrivateAttr(default_factory=lambda: Queue(maxsize=1))
-    """ The context dictionary to be used for workflow execution."""
+    """Queue for storing the workflow execution context."""
+
+    _instances: Tuple[Action, ...] = PrivateAttr(default_factory=tuple)
+    """Instantiated action objects to be executed in this workflow."""
 
-    _instances: Tuple[Action, ...] = PrivateAttr(...)
-    """ The instances of the workflow steps."""
+    steps: Sequence[Union[Type[Action], Action]] = Field(frozen=True)
+    """The sequence of actions to be executed, can be action classes or instances."""
+
+    task_input_key: ClassVar[str] = INPUT_KEY
+    """Key used to store the input task in the context dictionary."""
+
+    task_output_key: ClassVar[str] = OUTPUT_KEY
+    """Key used to extract the final result from the context dictionary."""
 
-    steps: Tuple[Union[Type[Action], Action], ...] = Field(...)
-    """ The steps to be executed in the workflow, actions or action classes."""
-    task_input_key: str = Field(default="task_input")
-    """ The key of the task input data."""
-    task_output_key: str = Field(default="task_output")
-    """ The key of the task output data."""
     extra_init_context: Dict[str, Any] = Field(default_factory=dict, frozen=True)
-    """ The extra context dictionary to be used for workflow initialization."""
+    """Additional initial context values to be included at workflow start."""
 
     def model_post_init(self, __context: Any) -> None:
-        """Initialize the workflow by setting fallbacks for each step.
+        """Initialize the workflow by instantiating any action classes.
 
         Args:
             __context: The context to be used for initialization.
+
         """
-        temp = []
-        for step in self.steps:
-            temp.append(step if isinstance(step, Action) else step())
-        self._instances = tuple(temp)
+        self.name = self.name or self.__class__.__name__
+        # Convert any action classes to instances
+        self._instances = tuple(step if isinstance(step, Action) else step() for step in self.steps)
+
+    def iter_actions(self) -> Generator[Action, None, None]:
+        """Iterate over action instances."""
+        yield from self._instances
 
     def inject_personality(self, personality: str) -> Self:
-        """Inject the personality of the workflow.
+        """Set personality for actions without existing personality.
 
         Args:
-            personality: The personality to be injected.
+            personality (str): Shared personality context
 
         Returns:
-            Self: The instance of the workflow with the injected personality.
+            Workflow instance with updated actions
         """
-        for a in self._instances:
-            if not a.personality:
-                a.personality = personality
+        for action in filter(lambda a: not a.personality, self._instances):
+            action.personality = personality
+        return self
+
+    def override_action_variable(self, action: Action, ctx: Dict[str, Any]) -> Self:
+        """Override action variable with context values."""
+        if action.ctx_override:
+            for k, v in ctx.items():
+                if hasattr(action, k):
+                    setattr(action, k, v)
+
         return self
 
     async def serve(self, task: Task) -> None:
-        """Serve the task by executing the workflow steps.
+        """Execute workflow to complete given task.
 
         Args:
-            task: The task to be served.
+            task (Task): Task instance to be processed.
+
+        Steps:
+            1. Initialize context with task instance and extra data
+            2. Execute each action sequentially
+            3. Handle task cancellation and exceptions
+            4. Extract final result from context
         """
+        logger.info(f"Start execute workflow: {self.name}")
+
         await task.start()
         await self._init_context(task)
+
         current_action = None
         try:
-            for step in self._instances:
-                logger.debug(f"Executing step: {step.name}")
-                modified_ctx = await step.act(await self._context.get())
+            # Process each action in sequence
+            for i, step in enumerate(self._instances):
+                logger.info(f"Executing step [{i}] >> {(current_action := step.name)}")
+
+                # Get current context and execute action
+                context = await self._context.get()
+
+                self.override_action_variable(step, context)
+                act_task = create_task(step.act(context))
+                # Handle task cancellation
+                if task.is_cancelled():
+                    logger.warning(f"Workflow cancelled by task: {task.name}")
+                    act_task.cancel(f"Cancelled by task: {task.name}")
+                    break
+
+                # Update context with modified values
+                modified_ctx = await act_task
+                logger.success(f"Step [{i}] `{current_action}` execution finished.")
+                if step.output_key:
+                    logger.success(f"Setting action `{current_action}` output to `{step.output_key}`")
                 await self._context.put(modified_ctx)
-                current_action = step.name
-            logger.info(f"Finished executing workflow: {self.name}")
+
+            logger.success(f"Workflow `{self.name}` execution finished.")
+
+            # Get final context and extract result
             final_ctx = await self._context.get()
+            result = final_ctx.get(self.task_output_key)
+
             if self.task_output_key not in final_ctx:
                 logger.warning(
-                    f"Task output key: {self.task_output_key} not found in the context, None will be returned. You can check if `Action.output_key` is set the same as `WorkFlow.task_output_key`."
+                    f"Task output key: `{self.task_output_key}` not found in the context, None will be returned. "
+                    f"You can check if `Action.output_key` is set the same as `WorkFlow.task_output_key`."
                 )
 
-            await task.finish(final_ctx.get(self.task_output_key, None))
-        except RuntimeError as e:
-            logger.error(f"Error during task: {current_action} execution: {e}")  # Log the exception
-            logger.error(traceback.format_exc())  # Add this line to log the traceback
-            await task.fail()  # Mark the task as failed
+            await task.finish(result)
+
+        except Exception as e:  # noqa: BLE001
+            logger.critical(f"Error during task: {current_action} execution: {e}")
+            logger.critical(traceback.format_exc())
+            await task.fail()
 
     async def _init_context[T](self, task: Task[T]) -> None:
-        """Initialize the context dictionary for workflow execution."""
+        """Initialize workflow execution context.
+
+        Args:
+            task (Task[T]): Task being processed
+
+        Context includes:
+            - Task instance stored under task_input_key
+            - Any extra_init_context values
+        """
         logger.debug(f"Initializing context for workflow: {self.name}")
-        await self._context.put({self.task_input_key: task, **dict(self.extra_init_context)})
+        ctx = override_kwargs(self.extra_init_context, **task.extra_init_context)
+        if self.task_input_key in ctx:
+            raise ValueError(
+                f"Task input key: `{self.task_input_key}`, which is reserved, is already set in the init context"
+            )
 
-    def steps_fallback_to_self(self) -> Self:
-        """Set the fallback for each step to the workflow itself."""
-        self.hold_to(self._instances)
-        return self
+        await self._context.put({self.task_input_key: task, **ctx})
+
+    def update_init_context(self, /, **kwargs) -> Self:
+        """Update the initial context with additional key-value pairs.
+
+        Args:
+            **kwargs: Key-value pairs to add to the initial context.
 
-    def steps_supply_tools_from_self(self) -> Self:
-        """Supply the tools from the workflow to each step."""
-        self.provide_tools_to(self._instances)
+        Returns:
+            Self: The workflow instance for method chaining.
+        """
+        self.extra_init_context.update(kwargs)
         return self