Base

def comment(for_notebook: bool, hashtags: int = 1) -> str:
    """Get the comment string.

    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 comment string.
    Example
    -------
    ```python
    >>> comment(True, 2)
    '## '
    >>> comment(False)
    '# '
    ```
    """
    content = "# "
    if for_notebook:
        content += "#" * hashtags + " "
    return content

def get_comment(
    key: CommentKey,
    for_notebook: bool,
) -> str:
    """Get a comment string for some common keys.

    The key is a heading (in a notebook) or just a comment (in a script).

    Parameters
    ----------
    key : "agents"|"imports"|"skills"|"models"|"nested"|"run"|"logging"
        The key.
    for_notebook : bool
        Whether the comment is for a notebook.

    Returns
    -------
    str
        The comment string.

    Example
    -------
    ```python
    >>> get_comment("agents", True)

    '## Agents'
    >>> get_comment("skills", False)

    '# Skills'
    ```
    """
    # 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":
        return "\n" + comment(for_notebook, 2) + "Models\n"
    if key == "nested":
        return "\n" + comment(for_notebook, 2) + "Nested Chats\n"
    if key == "run":
        return "\n" + comment(for_notebook, 2) + "Run the flow\n"
    if key == "logging":
        return "\n" + comment(for_notebook, 2) + "Start Logging\n"
    return comment(for_notebook)

def get_escaped_string(string: str) -> str:
    """Get a string with escaped quotes and newlines.

    Parameters
    ----------
    string : str
        The original string.

    Returns
    -------
    str
        The escaped string.
    """
    return string.replace('"', '\\"').replace("\n", "\\n")

def get_valid_instance_name(
    instance: Tuple[str, str],
    current_names: Dict[str, str],
    prefix: str = "w",
    max_length: int = MAX_VARIABLE_LENGTH,
) -> Dict[str, str]:
    """Get a valid instance name.

    If the instance id is already in the current names nothing is done.
    If the name already exists in the current names,
        the name is updated (with an index suffix).

    Parameters
    ----------
    instance : Tuple[str, str]
        The instance id and possible name.
    current_names : Dict[str, str]
        The current names.
    prefix : str, optional
        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[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=prefix, max_length=max_length
    )
    if name in current_names.values():
        name = f"{prefix}_{name}"
    if name in current_names.values():
        index = 1
        while f"{name}_{index}" in current_names.values():
            index += 1
        name = f"{name}_{index}"
    new_names[instance_id] = name
    return new_names

def get_valid_python_variable_name(
    possible: str,
    prefix: str = "w",
    max_length: int = MAX_VARIABLE_LENGTH,
) -> str:
    """Get a valid Python variable name from a possible name.

    Parameters
    ----------
    possible : str
        The possible 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
        The valid Python variable name.
    """

    def replacement(match: re.Match[str]) -> str:
        """Get the replacement for the match.

        Parameters
        ----------
        match : re.Match[str]
            The match.

        Returns
        -------
        str
            The replacement
        """
        if match.group(0) in ["->", "=>"]:
            return "to"
        if match.group(0) in ["<-", "<="]:
            return "from"
        if re.match(r"\W|^(?=\d)", match.group(0)):
            return "_"
        return match.group(0)

    possible = re.sub(r"->|=>|<-|<=|\W|^(?=\d)", replacement, possible)[
        :max_length
    ].lower()

    if not possible:
        return prefix + "_"
    if possible.startswith("_"):
        return f"{prefix}{possible}"
    if possible[0].isdigit():
        return f"{prefix}_{possible}"
    return possible

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)

def get_item_string(item: Any, tabs: int = 1) -> str:
    """Convert an item to a formatted string with given indentation.

    Parameters
    ----------
    item : Any
        The item to convert.
    tabs : int, optional
        The number of tabs, by default 1.

    Returns
    -------
    str
        The formatted string.

    Example
    -------
    ```python
    >>> obj = {"a": 1, "b": [1, 2, 3]}
    >>> get_item_string(obj)
    {
        "a": 1,
        "b": [
            1,
            2,
            3
        ]
    }
    >>> obj = {"a": 1, "b": [1, 2, 3], "c": {"d": 4}}
    >>> get_item_string(obj, 2)
    {
            "a": 1,
            "b": [
                1,
                2,
                3
            ],
            "c": {
                "d": 4
            }
    }
    ```
    """
    indent = " " * 4 * tabs  # Number of spaces corresponding to the tabs
    next_indent = (
        " " * 4 * (tabs + 1)
    )  # Number of spaces corresponding to the next tab level
    if isinstance(item, dict):
        items = []
        for key, value in item.items():
            items.append(
                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}}}"
    if isinstance(item, list):
        items = []
        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(item, str):
        if item.startswith("r'") or item.startswith('r"'):
            return item
        return f'"{item}"'

    if item is None:
        return "None"
    return str(item)