FileCallbackHandler Class — langchain Architecture

Architecture documentation for the FileCallbackHandler class in file.py from the langchain codebase.

Class python

Entity Profile

Dependency Diagram

graph TD
  52737fd4_dd58_4289_8b70_0131f09b23a5["FileCallbackHandler"]
  af283d05_75a6_5813_267b_f03a32501460["BaseCallbackHandler"]
  52737fd4_dd58_4289_8b70_0131f09b23a5 -->|extends| af283d05_75a6_5813_267b_f03a32501460
  d3b29d48_53fd_5b73_a122_25135e8518f8["file.py"]
  52737fd4_dd58_4289_8b70_0131f09b23a5 -->|defined in| d3b29d48_53fd_5b73_a122_25135e8518f8
  2ea2042b_775c_4bd9_cf6b_c76b82d9b660["__init__()"]
  52737fd4_dd58_4289_8b70_0131f09b23a5 -->|method| 2ea2042b_775c_4bd9_cf6b_c76b82d9b660
  5355e9e2_55b4_17cb_fa3e_a4bcf08a62a3["__enter__()"]
  52737fd4_dd58_4289_8b70_0131f09b23a5 -->|method| 5355e9e2_55b4_17cb_fa3e_a4bcf08a62a3
  e685f441_7119_0c6f_379f_99e5eb8810e4["__exit__()"]
  52737fd4_dd58_4289_8b70_0131f09b23a5 -->|method| e685f441_7119_0c6f_379f_99e5eb8810e4
  937c0be3_e5b8_a966_b552_24b8e135a89f["__del__()"]
  52737fd4_dd58_4289_8b70_0131f09b23a5 -->|method| 937c0be3_e5b8_a966_b552_24b8e135a89f
  058233c7_477a_615d_9e9f_5e460cb44480["close()"]
  52737fd4_dd58_4289_8b70_0131f09b23a5 -->|method| 058233c7_477a_615d_9e9f_5e460cb44480
  efeb47b6_76c6_8f45_76b9_d26fbc90c538["_write()"]
  52737fd4_dd58_4289_8b70_0131f09b23a5 -->|method| efeb47b6_76c6_8f45_76b9_d26fbc90c538
  b49e271b_5ffb_4c0a_2546_acb41b8cc221["on_chain_start()"]
  52737fd4_dd58_4289_8b70_0131f09b23a5 -->|method| b49e271b_5ffb_4c0a_2546_acb41b8cc221
  17a93548_4682_35ae_257b_0ee3ff7cc79c["on_chain_end()"]
  52737fd4_dd58_4289_8b70_0131f09b23a5 -->|method| 17a93548_4682_35ae_257b_0ee3ff7cc79c
  694d98ac_5a0f_25aa_d1a6_80fa50ec1695["on_agent_action()"]
  52737fd4_dd58_4289_8b70_0131f09b23a5 -->|method| 694d98ac_5a0f_25aa_d1a6_80fa50ec1695
  a96ffe4a_3f3f_2b4a_c2b4_e81de4567692["on_tool_end()"]
  52737fd4_dd58_4289_8b70_0131f09b23a5 -->|method| a96ffe4a_3f3f_2b4a_c2b4_e81de4567692
  6c2ae145_cb3b_ae6a_bc0c_183417224ea7["on_text()"]
  52737fd4_dd58_4289_8b70_0131f09b23a5 -->|method| 6c2ae145_cb3b_ae6a_bc0c_183417224ea7
  9aa2ee65_fa9b_42ce_4436_cde09233724e["on_agent_finish()"]
  52737fd4_dd58_4289_8b70_0131f09b23a5 -->|method| 9aa2ee65_fa9b_42ce_4436_cde09233724e

Relationship Graph

Source Code

libs/core/langchain_core/callbacks/file.py lines 21–267

class FileCallbackHandler(BaseCallbackHandler):
    """Callback handler that writes to a file.

    This handler supports both context manager usage (recommended) and direct
    instantiation (deprecated) for backwards compatibility.

    Examples:
        Using as a context manager (recommended):

        ```python
        with FileCallbackHandler("output.txt") as handler:
            # Use handler with your chain/agent
            chain.invoke(inputs, config={"callbacks": [handler]})
        ```

        Direct instantiation (deprecated):

        ```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.

    !!! 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.

    """

    def __init__(
        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.

        """
        self.filename = filename
        self.mode = mode
        self.color = color
        self._file_opened_in_context = False
        self.file: TextIO = cast(
            "TextIO",
            # Open the file in the specified mode with UTF-8 encoding.
            Path(self.filename).open(self.mode, encoding="utf-8"),  # noqa: SIM115
        )

    def __enter__(self) -> Self:
        """Enter the context manager.

        Returns:
            The `FileCallbackHandler` instance.

        !!! 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

    def __exit__(
        self,
        exc_type: type[BaseException] | None,
        exc_val: BaseException | None,
        exc_tb: object,
    ) -> None: