langchain-core 0.4.0.dev0__py3-none-any.whl → 1.0.0__py3-none-any.whl

langchain_core/callbacks/file.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Optional, TextIO, cast
+from typing import TYPE_CHECKING, Any, TextIO, cast
 
 from typing_extensions import Self, override
 
@@ -27,44 +27,45 @@ class FileCallbackHandler(BaseCallbackHandler):
     Examples:
         Using as a context manager (recommended):
 
-        .. code-block:: python
-
-            with FileCallbackHandler("output.txt") as handler:
-                # Use handler with your chain/agent
-                chain.invoke(inputs, config={"callbacks": [handler]})
+        ```python
+        with FileCallbackHandler("output.txt") as handler:
+            # Use handler with your chain/agent
+            chain.invoke(inputs, config={"callbacks": [handler]})
+        ```
 
         Direct instantiation (deprecated):
 
-        .. code-block:: python
-
-            handler = FileCallbackHandler("output.txt")
-            # File remains open until handler is garbage collected
-            try:
-                chain.invoke(inputs, config={"callbacks": [handler]})
-            finally:
-                handler.close()  # Explicit cleanup recommended
+        ```python
+        handler = FileCallbackHandler("output.txt")
+        # File remains open until handler is garbage collected
+        try:
+            chain.invoke(inputs, config={"callbacks": [handler]})
+        finally:
+            handler.close()  # Explicit cleanup recommended
+        ```
 
     Args:
         filename: The file path to write to.
-        mode: The file open mode. Defaults to ``'a'`` (append).
-        color: Default color for text output. Defaults to ``None``.
+        mode: The file open mode. Defaults to `'a'` (append).
+        color: Default color for text output.
 
-    Note:
+    !!! note
         When not used as a context manager, a deprecation warning will be issued
-        on first use. The file will be opened immediately in ``__init__`` and closed
-        in ``__del__`` or when ``close()`` is called explicitly.
+        on first use. The file will be opened immediately in `__init__` and closed
+        in `__del__` or when `close()` is called explicitly.
 
     """
 
     def __init__(
-        self, filename: str, mode: str = "a", color: Optional[str] = None
+        self, filename: str, mode: str = "a", color: str | None = None
     ) -> None:
         """Initialize the file callback handler.
 
         Args:
             filename: Path to the output file.
-            mode: File open mode (e.g., ``'w'``, ``'a'``, ``'x'``). Defaults to ``'a'``.
-            color: Default text color for output. Defaults to ``None``.
+            mode: File open mode (e.g., `'w'`, `'a'`, `'x'`). Defaults to `'a'`.
+            color: Default text color for output.
+
         """
         self.filename = filename
         self.mode = mode
@@ -82,9 +83,10 @@ class FileCallbackHandler(BaseCallbackHandler):
         Returns:
             The FileCallbackHandler instance.
 
-        Note:
-            The file is already opened in ``__init__``, so this just marks that
+        !!! note
+            The file is already opened in `__init__`, so this just marks that
             the handler is being used as a context manager.
+
         """
         self._file_opened_in_context = True
         return self
@@ -101,6 +103,7 @@ class FileCallbackHandler(BaseCallbackHandler):
             exc_type: Exception type if an exception occurred.
             exc_val: Exception value if an exception occurred.
             exc_tb: Exception traceback if an exception occurred.
+
         """
         self.close()
 
@@ -113,6 +116,7 @@ class FileCallbackHandler(BaseCallbackHandler):
 
         This method is safe to call multiple times and will only close
         the file if it's currently open.
+
         """
         if hasattr(self, "file") and self.file and not self.file.closed:
             self.file.close()
@@ -120,19 +124,20 @@ class FileCallbackHandler(BaseCallbackHandler):
     def _write(
         self,
         text: str,
-        color: Optional[str] = None,
+        color: str | None = None,
         end: str = "",
     ) -> None:
         """Write text to the file with deprecation warning if needed.
 
         Args:
             text: The text to write to the file.
-            color: Optional color for the text. Defaults to ``self.color``.
-            end: String appended after the text. Defaults to ``""``.
-            file: Optional file to write to. Defaults to ``self.file``.
+            color: Optional color for the text. Defaults to `self.color`.
+            end: String appended after the text.
+            file: Optional file to write to. Defaults to `self.file`.
 
         Raises:
             RuntimeError: If the file is closed or not available.
+
         """
         global _GLOBAL_DEPRECATION_WARNED  # noqa: PLW0603
         if not self._file_opened_in_context and not _GLOBAL_DEPRECATION_WARNED:
@@ -162,7 +167,8 @@ class FileCallbackHandler(BaseCallbackHandler):
         Args:
             serialized: The serialized chain information.
             inputs: The inputs to the chain.
-            **kwargs: Additional keyword arguments that may contain ``'name'``.
+            **kwargs: Additional keyword arguments that may contain `'name'`.
+
         """
         name = (
             kwargs.get("name")
@@ -178,20 +184,22 @@ class FileCallbackHandler(BaseCallbackHandler):
         Args:
             outputs: The outputs of the chain.
             **kwargs: Additional keyword arguments.
+
         """
         self._write("\n> Finished chain.", end="\n")
 
     @override
     def on_agent_action(
-        self, action: AgentAction, color: Optional[str] = None, **kwargs: Any
+        self, action: AgentAction, color: str | None = None, **kwargs: Any
     ) -> Any:
         """Handle agent action by writing the action log.
 
         Args:
             action: The agent action containing the log to write.
-            color: Color override for this specific output. If ``None``, uses
-                ``self.color``.
+            color: Color override for this specific output. If `None`, uses
+                `self.color`.
             **kwargs: Additional keyword arguments.
+
         """
         self._write(action.log, color=color or self.color)
 
@@ -199,20 +207,21 @@ class FileCallbackHandler(BaseCallbackHandler):
     def on_tool_end(
         self,
         output: str,
-        color: Optional[str] = None,
-        observation_prefix: Optional[str] = None,
-        llm_prefix: Optional[str] = None,
+        color: str | None = None,
+        observation_prefix: str | None = None,
+        llm_prefix: str | None = None,
         **kwargs: Any,
     ) -> None:
         """Handle tool end by writing the output with optional prefixes.
 
         Args:
             output: The tool output to write.
-            color: Color override for this specific output. If ``None``, uses
-                ``self.color``.
+            color: Color override for this specific output. If `None`, uses
+                `self.color`.
             observation_prefix: Optional prefix to write before the output.
             llm_prefix: Optional prefix to write after the output.
             **kwargs: Additional keyword arguments.
+
         """
         if observation_prefix is not None:
             self._write(f"\n{observation_prefix}")
@@ -222,29 +231,31 @@ class FileCallbackHandler(BaseCallbackHandler):
 
     @override
     def on_text(
-        self, text: str, color: Optional[str] = None, end: str = "", **kwargs: Any
+        self, text: str, color: str | None = None, end: str = "", **kwargs: Any
     ) -> None:
         """Handle text output.
 
         Args:
             text: The text to write.
-            color: Color override for this specific output. If ``None``, uses
-                ``self.color``.
-            end: String appended after the text. Defaults to ``""``.
+            color: Color override for this specific output. If `None`, uses
+                `self.color`.
+            end: String appended after the text.
             **kwargs: Additional keyword arguments.
+
         """
         self._write(text, color=color or self.color, end=end)
 
     @override
     def on_agent_finish(
-        self, finish: AgentFinish, color: Optional[str] = None, **kwargs: Any
+        self, finish: AgentFinish, color: str | None = None, **kwargs: Any
     ) -> None:
         """Handle agent finish by writing the finish log.
 
         Args:
             finish: The agent finish object containing the log to write.
-            color: Color override for this specific output. If ``None``, uses
-                ``self.color``.
+            color: Color override for this specific output. If `None`, uses
+                `self.color`.
             **kwargs: Additional keyword arguments.
+
         """
         self._write(finish.log, color=color or self.color, end="\n")