waldiez 0.2.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

waldiez/exporting/base/base_exporter.py

@@ -0,0 +1,118 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Base exporter class to be inherited by all exporters."""
+
+import abc
+from typing import Any, List, Optional, Tuple, TypedDict, Union
+
+from .agent_position import AgentPosition
+from .export_position import ExportPosition
+from .import_position import ImportPosition
+
+
+# flake8: noqa E501
+# pylint: disable=line-too-long
+class ExporterReturnType(TypedDict):
+    """Exporter Return Type.
+
+    Attributes
+    ----------
+    content : Optional[str]
+        The exported content.
+    imports : Optional[List[Tuple[str, ImportPosition]]]
+        The additional imports required for the exported content.
+    environment_variables : Optional[List[Tuple[str, str]]]
+        The environment variables to set.
+    before_export : Optional[List[Tuple[str, Union[ExportPosition, AgentPosition]]]]
+        The exported content before the main export and its position.
+    after_export : Optional[List[Tuple[str, Union[ExportPosition, AgentPosition]]]]
+        The exported content after the main export and its position.
+    """
+
+    content: Optional[str]
+    imports: Optional[List[Tuple[str, ImportPosition]]]
+    environment_variables: Optional[List[Tuple[str, str]]]
+    before_export: Optional[
+        List[Tuple[str, Union[ExportPosition, AgentPosition]]]
+    ]
+    after_export: Optional[
+        List[Tuple[str, Union[ExportPosition, AgentPosition]]]
+    ]
+
+
+class BaseExporter(abc.ABC):
+    """Base exporter."""
+
+    @abc.abstractmethod
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Initialize the exporter.
+
+        Parameters
+        ----------
+        *args : Any
+            The positional arguments.
+        **kwargs : Any
+            The keyword arguments.
+        """
+        raise NotImplementedError("Method not implemented.")
+
+    def get_environment_variables(self) -> Optional[List[Tuple[str, str]]]:
+        """Get the environment variables to set.
+
+        Returns
+        -------
+        Optional[Set[Tuple[str, str]]]
+            The environment variables to set if any.
+        """
+
+    def get_imports(self) -> Optional[List[Tuple[str, ImportPosition]]]:
+        """ "Generate the imports string for the exporter.
+
+        Returns
+        -------
+        Optional[Tuple[str, ImportPosition]]
+            The exported imports and the position of the imports.
+        """
+
+    def get_before_export(
+        self,
+    ) -> Optional[List[Tuple[str, Union[ExportPosition, AgentPosition]]]]:
+        """Generate the content before the main export.
+
+        Returns
+        -------
+        Optional[List[Tuple[str, Union[ExportPosition, AgentPosition]]]]
+            The exported content before the main export and its position.
+        """
+
+    def generate(
+        self,
+    ) -> Optional[str]:
+        """Generate the main export.
+
+        Returns
+        -------
+        str
+            The exported content.
+        """
+
+    def get_after_export(
+        self,
+    ) -> Optional[List[Tuple[str, Union[ExportPosition, AgentPosition]]]]:
+        """Generate the content after the main export.
+
+        Returns
+        -------
+        Optional[List[Tuple[str, Union[ExportPosition, AgentPosition]]]]
+            The exported content after the main export and its position.
+        """
+
+    @abc.abstractmethod
+    def export(self) -> ExporterReturnType:
+        """Export the content.
+
+        Returns
+        -------
+        ExporterReturnType
+            The exported content.
+        """

waldiez/exporting/base/export_position.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Export position enum."""
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class ExportPositions(Enum):
+    """Export position.
+
+    Attributes
+    ----------
+    TOP : int
+        The top of the export (name, comments etc.)
+    IMPORTS : int
+        The imports section.
+    MODELS : int
+        The models section (define the llm_configs).
+    SKILLS : int
+        The skills section (generate the skill files, and import them)
+    AGENTS : int
+        The agents section.
+    CHATS : int
+        The chats section (e.g. agent.initiate_chat, or initiate_chats)
+    BOTTOM : int
+        The bottom part of the export (like the main function and calling it).
+    """
+
+    TOP = 0
+    IMPORTS = 1
+    SKILLS = 2
+    MODELS = 3
+    AGENTS = 4
+    CHATS = 5
+    BOTTOM = 6
+
+
+@dataclass(order=True, frozen=True, slots=True)
+class ExportPosition:
+    """Export position.
+
+    Optionally, the order can be provided
+    to sort the exported content.
+    """
+
+    position: ExportPositions
+    order: int = 0

waldiez/exporting/base/import_position.py

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Import position enum."""
+
+from enum import Enum
+
+
+class ImportPosition(Enum):
+    """Import position.
+
+    Attributes
+    ----------
+    BUILTINS : int
+        The top of the import (builtins)
+    THIRD_PARTY : int
+        The third party imports.
+    LOCAL : int
+        The local imports.
+    """
+
+    BUILTINS = 0
+    THIRD_PARTY = 1
+    LOCAL = 2

waldiez/exporting/base/mixin.py

@@ -0,0 +1,134 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""The base exporter mixin."""
+
+from typing import Any, Dict, Tuple
+
+from .utils import (
+    CommentKey,
+    comment,
+    get_comment,
+    get_escaped_string,
+    get_item_string,
+    get_path_string,
+    get_valid_instance_name,
+)
+
+
+class ExporterMixin:
+    """Static methods to be used by the exporters."""
+
+    @staticmethod
+    def serializer(item: Any, tabs: int = 1) -> str:
+        """Get the string representation of an item.
+
+        Parameters
+        ----------
+        item : Any
+            The item.
+        tabs : int, optional
+            The number of tabs for indentation, by default 1.
+        Returns
+        -------
+        str
+            The string representation of the item.
+        """
+        return get_item_string(item=item, tabs=tabs)
+
+    @staticmethod
+    def path_resolver(path: str) -> str:
+        """Get the path string.
+
+        Parameters
+        ----------
+        path : str
+            The path.
+
+        Returns
+        -------
+        str
+            The path string.
+        """
+        return get_path_string(path)
+
+    @staticmethod
+    def string_escape(string: str) -> str:
+        """Get a string with escaped quotes and newlines.
+
+        Parameters
+        ----------
+        string : str
+            The original string.
+
+        Returns
+        -------
+        str
+            The escaped string.
+        """
+        return get_escaped_string(string)
+
+    @staticmethod
+    def get_comment(key: CommentKey, for_notebook: bool) -> str:
+        """Get the comment string.
+
+        Parameters
+        ----------
+        key : CommentKey
+            The comment key.
+        for_notebook : bool
+            Whether the comment is for a notebook or not.
+        Returns
+        -------
+        str
+            The comment string.
+        """
+        return get_comment(key=key, for_notebook=for_notebook)
+
+    @staticmethod
+    def comment(for_notebook: bool, hashtags: int = 1) -> str:
+        """Comment the text.
+
+        Parameters
+        ----------
+        for_notebook : bool
+            Whether the comment is for a notebook or not.
+        hashtags : int, optional
+            The number of hashtags (for notebooks), by default 1.
+
+        Returns
+        -------
+        str
+            The commented text.
+        """
+        return comment(for_notebook=for_notebook, hashtags=hashtags)
+
+    @staticmethod
+    def get_valid_instance_name(
+        instance: Tuple[str, str],
+        current_names: Dict[str, str],
+        prefix: str = "w",
+        max_length: int = 64,
+    ) -> Dict[str, str]:
+        """Get a valid instance name.
+
+        Parameters
+        ----------
+        instance : Tuple[str, str]
+            The instance id and possible name.
+        current_names : Dict[str, str]
+            The current names.
+        prefix : str, optional
+            The prefix for the instance name, by default "w".
+        max_length : int, optional
+            The maximum length of the variable name, by default 64
+        Returns
+        -------
+        Dict[str, str]
+            The updated dictionary of current names.
+        """
+        return get_valid_instance_name(
+            instance=instance,
+            current_names=current_names,
+            prefix=prefix,
+            max_length=max_length,
+        )

waldiez/exporting/base/utils/__init__.py

@@ -0,0 +1,18 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Generic utils to be used for exporting."""
+
+from .comments import CommentKey, comment, get_comment
+from .naming import get_escaped_string, get_valid_instance_name
+from .path_check import get_path_string
+from .to_string import get_item_string
+
+__all__ = [
+    "CommentKey",
+    "comment",
+    "get_comment",
+    "get_escaped_string",
+    "get_item_string",
+    "get_path_string",
+    "get_valid_instance_name",
+]

waldiez/exporting/{utils → base/utils}/comments.py

@@ -1,38 +1,26 @@
-"""Comment related string generation functions.
-Functions
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Utilities for comments.
 ---------
 comment
     Get a comment string.
 get_comment
     Get a comment string for some common keys (notebook headings).
-get_pylint_ignore_comment
-    Get the pylint ignore comment string.
 """
 
-from typing import List, Optional
-
 from typing_extensions import Literal
 
-PYLINT_RULES = [
-    "line-too-long",
-    "unknown-option-value",
-    "unused-argument",
-    "unused-import",
-    "invalid-name",
-    "import-error",
-    "inconsistent-quotes",
-    "missing-function-docstring",
-    "missing-param-doc",
-    "missing-return-doc",
+CommentKey = Literal[
+    "agents", "imports", "skills", "models", "nested", "run", "logging"
 ]
 
 
-def comment(notebook: bool, hashtags: int = 1) -> str:
+def comment(for_notebook: bool, hashtags: int = 1) -> str:
     """Get the comment string.
 
     Parameters
     ----------
-    notebook : bool
+    for_notebook : bool
         Whether the comment is for a notebook or not.
     hashtags : int, optional
         The number of hashtags (for notebooks), by default 1.
@@ -51,13 +39,13 @@ def comment(notebook: bool, hashtags: int = 1) -> str:
     ```
     """
     content = "# "
-    if notebook:
+    if for_notebook:
         content += "#" * hashtags + " "
     return content
 
 
 def get_comment(
-    key: Literal["agents", "skills", "models", "nested", "run", "logging"],
+    key: CommentKey,
     for_notebook: bool,
 ) -> str:
     """Get a comment string for some common keys.
@@ -66,7 +54,7 @@ def get_comment(
 
     Parameters
     ----------
-    key : Literal["agents", "skills", "models", "nested", "run", "logging"]
+    key : "agents"|"imports"|"skills"|"models"|"nested"|"run"|"logging"
         The key.
     for_notebook : bool
         Whether the comment is for a notebook.
@@ -90,6 +78,8 @@ def get_comment(
     # pylint: disable=too-many-return-statements
     if key == "agents":
         return "\n" + comment(for_notebook, 2) + "Agents\n"
+    if key == "imports":
+        return "\n" + comment(for_notebook, 2) + "Imports\n"
     if key == "skills":
         return "\n" + comment(for_notebook, 2) + "Skills\n"
     if key == "models":
@@ -101,36 +91,3 @@ def get_comment(
     if key == "logging":
         return "\n" + comment(for_notebook, 2) + "Start Logging\n"
     return comment(for_notebook)
-
-
-def get_pylint_ignore_comment(
-    notebook: bool, rules: Optional[List[str]] = None
-) -> str:
-    """Get the pylint ignore comment string.
-
-    Parameters
-    ----------
-    notebook : bool
-        Whether the comment is for a notebook.
-    rules : Optional[List[str]], optional
-        The pylint rules to ignore, by default None.
-
-    Returns
-    -------
-    str
-        The pylint ignore comment string.
-
-    Example
-    -------
-    ```python
-    >>> get_pylint_ignore_comment(True, ["invalid-name", "line-too-long"])
-
-    # pylint: disable=invalid-name, line-too-long
-    ```
-    """
-    if not rules:
-        rules = PYLINT_RULES
-    line = "# pylint: disable=" + ",".join(rules)
-    if notebook is True:
-        line = "\n" + line
-    return line + "\n"

waldiez/exporting/{utils → base/utils}/naming.py

@@ -1,4 +1,6 @@
-"""Naming related string generation functions.
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Utilities for naming.
 
 Functions
 ---------
@@ -17,6 +19,7 @@ from typing import Dict, Tuple
 def get_valid_python_variable_name(
     possible: str,
     prefix: str = "w",
+    max_length: int = 64,
 ) -> str:
     """Get a valid Python variable name from a possible name.
 
@@ -28,6 +31,9 @@ def get_valid_python_variable_name(
     prefix : str, optional
         The prefix to use if the name starts with a digit or special character
 
+    max_length : int, optional
+        The maximum length of the variable name.
+
     Returns
     -------
     str
@@ -56,7 +62,7 @@ def get_valid_python_variable_name(
         return match.group(0)
 
     possible = re.sub(r"->|=>|<-|<=|\W|^(?=\d)", replacement, possible)[
-        :64
+        :max_length
     ].lower()
 
     if not possible:
@@ -72,6 +78,7 @@ def get_valid_instance_name(
     instance: Tuple[str, str],
     current_names: Dict[str, str],
     prefix: str = "w",
+    max_length: int = 64,
 ) -> Dict[str, str]:
     """Get a valid instance name.
 
@@ -89,17 +96,20 @@ def get_valid_instance_name(
         The prefix to use if the name starts with a digit,
         if the name is already in the current names,
         or if the name is already in the current names with an index suffix.
+    max_length : int, optional
+        The maximum length of the variable name.
 
     Returns
     -------
     Dict[str, str]
         The updated names.
     """
-    instance_id, possible_name = instance
+    instance_id, possible_name = instance[0], instance[1][:max_length]
     if instance_id in current_names:
+        # already in the current names (it's id)
         return current_names
     new_names = current_names.copy()
-    name = get_valid_python_variable_name(possible_name, prefix)
+    name = get_valid_python_variable_name(possible_name, prefix=prefix)
     if name in current_names.values():
         name = f"{prefix}_{name}"
     if name in current_names.values():

waldiez/exporting/base/utils/path_check.py

@@ -0,0 +1,68 @@
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+# pylint: disable=broad-except
+"""Path check utility functions."""
+
+from pathlib import Path
+from typing import Optional, Union
+
+
+def _check_local_path(string: str) -> Optional[Path]:
+    """Check if a string is a local path.
+
+    Parameters
+    ----------
+    string : str
+        The string to check.
+
+    Returns
+    -------
+    bool
+        True if the path is a local path.
+    """
+    try:
+        path = Path(string).resolve()
+    except BaseException:  # pragma: no cover
+        return None
+    if path.exists():
+        return path
+    return None
+
+
+def _get_raw_path_string(path: Union[str, Path]) -> str:
+    """Get the raw path string.
+
+    Parameters
+    ----------
+    path : Union[str, Path]
+        The string to check.
+
+    Returns
+    -------
+    str
+        The raw path string.
+    """
+    if not isinstance(path, str):
+        path = str(path)
+    while path.startswith('r"') and path.endswith('"'):
+        path = path[2:-1]
+    return f'r"{path}"'
+
+
+def get_path_string(path: str) -> str:
+    """Get the path string.
+
+    Parameters
+    ----------
+    path : str
+        The string to check.
+
+    Returns
+    -------
+    str
+        The local path string.
+    """
+    resolved = _check_local_path(path)
+    if not resolved:
+        return _get_raw_path_string(path)
+    return _get_raw_path_string(resolved)

waldiez/exporting/{utils/object_string.py → base/utils/to_string.py}

@@ -1,4 +1,6 @@
-"""Function to convert an object to a formatted string with indentation.
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Utilities for converting items to strings.
 
 To be used with dicts and/or lists.
 """
@@ -6,13 +8,13 @@ To be used with dicts and/or lists.
 from typing import Any
 
 
-def get_object_string(obj: Any, tabs: int = 1) -> str:
-    """Convert an object to a formatted string with given indentation.
+def get_item_string(item: Any, tabs: int = 1) -> str:
+    """Convert an item to a formatted string with given indentation.
 
     Parameters
     ----------
-    obj : Any
-        The object to convert.
+    item : Any
+        The item to convert.
     tabs : int, optional
         The number of tabs, by default 1.
 
@@ -25,7 +27,7 @@ def get_object_string(obj: Any, tabs: int = 1) -> str:
     -------
     ```python
     >>> obj = {"a": 1, "b": [1, 2, 3]}
-    >>> get_object_string(obj)
+    >>> get_item_string(obj)
     {
         "a": 1,
         "b": [
@@ -35,7 +37,7 @@ def get_object_string(obj: Any, tabs: int = 1) -> str:
         ]
     }
     >>> obj = {"a": 1, "b": [1, 2, 3], "c": {"d": 4}}
-    >>> get_object_string(obj, 2)
+    >>> get_item_string(obj, 2)
     {
             "a": 1,
             "b": [
@@ -53,31 +55,30 @@ def get_object_string(obj: Any, tabs: int = 1) -> str:
     next_indent = (
         " " * 4 * (tabs + 1)
     )  # Number of spaces corresponding to the next tab level
-    if isinstance(obj, dict):
+    if isinstance(item, dict):
         items = []
-        for key, value in obj.items():
+        for key, value in item.items():
             items.append(
-                f'{next_indent}"{key}": {get_object_string(value, tabs + 1)}'
+                f'{next_indent}"{key}": {get_item_string(value, tabs + 1)}'
             )
         # python3.10? f-string expression part cannot include a backslash
         items_string = ",\n".join(items)
         to_return = "\n" + items_string + "\n" + indent
         return f"{{{to_return}}}"
-        # return f'{{\n{",\n".join(items)}\n{indent}}}'
-    if isinstance(obj, list):
+    if isinstance(item, list):
         items = []
-        for item in obj:
-            items.append(f"{next_indent}{get_object_string(item, tabs + 1)}")
+        for sub_item in item:
+            items.append(f"{next_indent}{get_item_string(sub_item, tabs + 1)}")
         # python3.10? f-string expression part cannot include a backslash
         items_string = ",\n".join(items)
         to_return = "\n" + items_string + "\n" + indent
         return f"[{to_return}]"
 
-    if isinstance(obj, str):
-        if obj.startswith("r'") or obj.startswith('r"'):
-            return obj
-        return f'"{obj}"'
+    if isinstance(item, str):
+        if item.startswith("r'") or item.startswith('r"'):
+            return item
+        return f'"{item}"'
 
-    if obj is None:
+    if item is None:
         return "None"
-    return str(obj)
+    return str(item)

waldiez/exporting/chats/__init__.py

@@ -1,14 +1,7 @@
-"""Chat related string generation functions.
+# SPDX-License-Identifier: Apache-2.0.
+# Copyright (c) 2024 - 2025 Waldiez and contributors.
+"""Export chats in a flow."""
 
-Functions
----------
-export_chats
-    Get the chats content.
-export_nested_chat
-    Get the 'register_nested_chats' content.
-"""
+from .chats_exporter import ChatsExporter
 
-from .chats import export_chats
-from .nested import export_nested_chat
-
-__all__ = ["export_chats", "export_nested_chat"]
+__all__ = ["ChatsExporter"]