x

libs/core/langchain_core/_api/__init__.py

@@ -16,6 +16,7 @@ from .beta_decorator import (
 )
 from .deprecation import (
     LangChainDeprecationWarning,
+    caller_aware_warn,
     deprecated,
     suppress_langchain_deprecation_warning,
     surface_langchain_deprecation_warnings,
@@ -35,4 +36,5 @@ __all__ = [
     "suppress_langchain_deprecation_warning",
     "surface_langchain_deprecation_warnings",
     "warn_deprecated",
+    "caller_aware_warn",
 ]

libs/core/langchain_core/_api/deprecation.py

@@ -13,6 +13,7 @@ https://github.com/matplotlib/matplotlib/blob/main/lib/matplotlib/_api/deprecati
 import contextlib
 import functools
 import inspect
+import os
 import warnings
 from typing import Any, Callable, Generator, Type, TypeVar
 
@@ -26,6 +27,15 @@ class LangChainDeprecationWarning(DeprecationWarning):
 class LangChainPendingDeprecationWarning(PendingDeprecationWarning):
     """A class for issuing deprecation warnings for LangChain users."""
 
+SURFACE_INTERNAL_WARNINGS = (
+    os.environ.get("SURFACE_INTERNAL_WARNINGS", "false").lower() == "true"
+)
+
+
+def _get_surface_internal_warnings() -> bool:
+    """Mocked for testing."""
+    return SURFACE_INTERNAL_WARNINGS
+
 
 # PUBLIC API
 
@@ -379,8 +389,11 @@ def warn_deprecated(
     warning_cls = (
         LangChainPendingDeprecationWarning if pending else LangChainDeprecationWarning
     )
-    warning = warning_cls(message)
+    caller_aware_warn(
-    warnings.warn(warning, category=LangChainDeprecationWarning, stacklevel=2)
+        message,
+        category=warning_cls,
+        surface_internal_warnings=_get_surface_internal_warnings(),
+    )
 
 
 def surface_langchain_deprecation_warnings() -> None:
@@ -394,3 +407,18 @@ def surface_langchain_deprecation_warnings() -> None:
         "default",
         category=LangChainDeprecationWarning,
     )
+
+
+def caller_aware_warn(
+    message: str,
+    *,
+    category: Type[Warning] = LangChainDeprecationWarning,
+    surface_internal_warnings: bool = False,
+) -> None:
+    """Warn deprecated"""
+    if surface_internal_warnings:
+        warnings.warn(message, category=category, stacklevel=2)
+    else:
+        if is_caller_internal(depth=2):
+            return
+        warnings.warn(message, category=category, stacklevel=2)

libs/core/tests/unit_tests/_api/test_deprecation.py

@@ -1,13 +1,24 @@
 import inspect
 import warnings
+from contextlib import contextmanager
 from typing import Any, Dict
+from unittest.mock import patch
 
 import pytest
 
+from langchain_core._api import deprecation
 from langchain_core._api.deprecation import deprecated, warn_deprecated
 from langchain_core.pydantic_v1 import BaseModel
 
 
+@contextmanager
+def surface_internal_warnings() -> None:
+    """Mock surface_langchain_deprecation_warnings."""
+    with patch.object(deprecation, "_get_surface_internal_warnings") as func:
+        func.return_value = True
+        yield func
+
+
 @pytest.mark.parametrize(
     "kwargs, expected_message",
     [
@@ -53,6 +64,7 @@ from langchain_core.pydantic_v1 import BaseModel
 )
 def test_warn_deprecated(kwargs: Dict[str, Any], expected_message: str) -> None:
     """Test warn deprecated."""
+    with surface_internal_warnings():
         with warnings.catch_warnings(record=True) as warning_list:
             warnings.simplefilter("always")
 
@@ -63,6 +75,17 @@ def test_warn_deprecated(kwargs: Dict[str, Any], expected_message: str) -> None:
             assert str(warning) == expected_message
 
 
+def test_internal_warnings_disabled() -> None:
+    """Test that internal warnings are disabled properly"""
+    with patch.object(deprecation, "_get_surface_internal_warnings") as func:
+        func.return_value = False
+        with warnings.catch_warnings(record=True) as warning_list:
+            warnings.simplefilter("always")
+            warn_deprecated("1.0.0", pending=True)
+            assert len(warning_list) == 0
+
+
+
 def test_undefined_deprecation_schedule() -> None:
     """This test is expected to fail until we defined a deprecation schedule."""
     with pytest.raises(NotImplementedError):
@@ -117,6 +140,7 @@ class ClassWithDeprecatedMethods:
 
 def test_deprecated_function() -> None:
     """Test deprecated function."""
+    with surface_internal_warnings():
         with warnings.catch_warnings(record=True) as warning_list:
             warnings.simplefilter("always")
             assert deprecated_function() == "This is a deprecated function."
@@ -137,10 +161,12 @@ def test_deprecated_function() -> None:
 @pytest.mark.asyncio
 async def test_deprecated_async_function() -> None:
     """Test deprecated async function."""
+    with surface_internal_warnings():
         with warnings.catch_warnings(record=True) as warning_list:
             warnings.simplefilter("always")
             assert (
-            await deprecated_async_function() == "This is a deprecated async function."
+                await deprecated_async_function()
+                == "This is a deprecated async function."
             )
             assert len(warning_list) == 1
             warning = warning_list[0].message
@@ -158,6 +184,7 @@ async def test_deprecated_async_function() -> None:
 
 def test_deprecated_method() -> None:
     """Test deprecated method."""
+    with surface_internal_warnings():
         with warnings.catch_warnings(record=True) as warning_list:
             warnings.simplefilter("always")
             obj = ClassWithDeprecatedMethods()
@@ -179,11 +206,13 @@ def test_deprecated_method() -> None:
 @pytest.mark.asyncio
 async def test_deprecated_async_method() -> None:
     """Test deprecated async method."""
+    with surface_internal_warnings():
         with warnings.catch_warnings(record=True) as warning_list:
             warnings.simplefilter("always")
             obj = ClassWithDeprecatedMethods()
             assert (
-            await obj.deprecated_async_method() == "This is a deprecated async method."
+                await obj.deprecated_async_method()
+                == "This is a deprecated async method."
             )
             assert len(warning_list) == 1
             warning = warning_list[0].message
@@ -201,6 +230,7 @@ async def test_deprecated_async_method() -> None:
 
 def test_deprecated_classmethod() -> None:
     """Test deprecated classmethod."""
+    with surface_internal_warnings():
         with warnings.catch_warnings(record=True) as warning_list:
             warnings.simplefilter("always")
             ClassWithDeprecatedMethods.deprecated_classmethod()
@@ -218,6 +248,7 @@ def test_deprecated_classmethod() -> None:
 
 def test_deprecated_staticmethod() -> None:
     """Test deprecated staticmethod."""
+    with surface_internal_warnings():
         with warnings.catch_warnings(record=True) as warning_list:
             warnings.simplefilter("always")
             assert (
@@ -238,6 +269,7 @@ def test_deprecated_staticmethod() -> None:
 
 def test_deprecated_property() -> None:
     """Test deprecated staticmethod."""
+    with surface_internal_warnings():
         with warnings.catch_warnings(record=True) as warning_list:
             warnings.simplefilter("always")
 
@@ -271,6 +303,7 @@ def test_whole_class_deprecation() -> None:
             """original doc"""
             return "This is a deprecated method."
 
+    with surface_internal_warnings():
         with warnings.catch_warnings(record=True) as warning_list:
             warnings.simplefilter("always")
 
@@ -326,6 +359,7 @@ def test_whole_class_inherited_deprecation() -> None:
             """original doc"""
             return "This is a deprecated method."
 
+    with surface_internal_warnings():
         with warnings.catch_warnings(record=True) as warning_list:
             warnings.simplefilter("always")
 
@@ -383,6 +417,7 @@ class MyModel(BaseModel):
 
 def test_deprecated_method_pydantic() -> None:
     """Test deprecated method."""
+    with surface_internal_warnings():
         with warnings.catch_warnings(record=True) as warning_list:
             warnings.simplefilter("always")
             obj = MyModel()

libs/core/tests/unit_tests/_api/test_imports.py

@@ -12,6 +12,7 @@ EXPECTED_ALL = [
     "warn_deprecated",
     "as_import_path",
     "get_relative_path",
+    "caller_aware_warn",
 ]
 
 

libs/core/tests/unit_tests/prompts/test_chat.py

@@ -246,7 +246,6 @@ def test_chat_valid_infer_variables() -> None:
 
 def test_chat_from_role_strings() -> None:
     """Test instantiation of chat template from role strings."""
-    with pytest.warns(LangChainPendingDeprecationWarning):
     template = ChatPromptTemplate.from_role_strings(
         [
             ("system", "You are a bot."),

libs/langchain/langchain/__init__.py

@@ -1,10 +1,12 @@
 # ruff: noqa: E402
 """Main entrypoint into package."""
-import warnings
 from importlib import metadata
 from typing import Any, Optional
 
-from langchain_core._api.deprecation import surface_langchain_deprecation_warnings
+from langchain_core._api.deprecation import (
+    caller_aware_warn,
+    surface_langchain_deprecation_warnings,
+)
 
 try:
     __version__ = metadata.version(__package__)
@@ -26,13 +28,13 @@ def _warn_on_import(name: str, replacement: Optional[str] = None) -> None:
         return
 
     if replacement:
-        warnings.warn(
+        caller_aware_warn(
             f"Importing {name} from langchain root module is no longer supported. "
-            f"Please use {replacement} instead."
+            f"Please use {replacement} instead.",
         )
     else:
-        warnings.warn(
+        caller_aware_warn(
-            f"Importing {name} from langchain root module is no longer supported."
+            f"Importing {name} from langchain root module is no longer supported.",
         )
 
 

libs/langchain/langchain/agents/agent_toolkits/__init__.py

@@ -13,11 +13,10 @@ whether permissions of the given toolkit are appropriate for the application.
 
 See [Security](https://python.langchain.com/docs/security) for more information.
 """
-import warnings
 from pathlib import Path
 from typing import Any
 
-from langchain_core._api import LangChainDeprecationWarning
+from langchain_core._api import caller_aware_warn
 from langchain_core._api.path import as_import_path
 
 from langchain.agents.agent_toolkits.conversational_retrieval.openai_functions import (
@@ -61,13 +60,12 @@ def __getattr__(name: str) -> Any:
 
     # If not in interactive env, raise warning.
     if not is_interactive_env():
-        warnings.warn(
+        caller_aware_warn(
             "Importing this agent toolkit from langchain is deprecated. Importing it "
             "from langchain will no longer be supported as of langchain==0.2.0. "
             "Please import from langchain-community instead:\n\n"
             f"`from langchain_community.agent_toolkits import {name}`.\n\n"
             "To install langchain-community run `pip install -U langchain-community`.",
-            category=LangChainDeprecationWarning,
         )
 
     return getattr(agent_toolkits, name)

libs/langchain/langchain/callbacks/__init__.py

@@ -6,10 +6,9 @@
 
     BaseCallbackHandler --> <name>CallbackHandler  # Example: AimCallbackHandler
 """
-import warnings
 from typing import Any
 
-from langchain_core._api import LangChainDeprecationWarning
+from langchain_core._api import caller_aware_warn
 from langchain_core.callbacks import (
     StdOutCallbackHandler,
     StreamingStdOutCallbackHandler,
@@ -34,15 +33,13 @@ def __getattr__(name: str) -> Any:
 
     # If not in interactive env, raise warning.
     if not is_interactive_env():
-        warnings.warn(
+        caller_aware_warn(
             "Importing this callback from langchain is deprecated. Importing it from "
             "langchain will no longer be supported as of langchain==0.2.0. "
             "Please import from langchain-community instead:\n\n"
             f"`from langchain_community.callbacks import {name}`.\n\n"
             "To install langchain-community run `pip install -U langchain-community`.",
-            category=LangChainDeprecationWarning,
         )
-
     return getattr(callbacks, name)
 
 

libs/langchain/langchain/chat_models/__init__.py

@@ -16,9 +16,8 @@ an interface where "chat messages" are the inputs and outputs.
 
     AIMessage, BaseMessage, HumanMessage
 """  # noqa: E501
-import warnings
 
-from langchain_core._api import LangChainDeprecationWarning
+from langchain_core._api import caller_aware_warn
 
 from langchain.utils.interactive_env import is_interactive_env
 
@@ -28,13 +27,12 @@ def __getattr__(name: str) -> None:
 
     # If not in interactive env, raise warning.
     if not is_interactive_env():
-        warnings.warn(
+        caller_aware_warn(
             "Importing chat models from langchain is deprecated. Importing from "
             "langchain will no longer be supported as of langchain==0.2.0. "
             "Please import from langchain-community instead:\n\n"
             f"`from langchain_community.chat_models import {name}`.\n\n"
             "To install langchain-community run `pip install -U langchain-community`.",
-            category=LangChainDeprecationWarning,
         )
 
     return getattr(chat_models, name)

libs/langchain/langchain/docstore/__init__.py

@@ -14,10 +14,9 @@ The **Docstore** is a simplified version of the Document Loader.
 
     Document, AddableMixin
 """
-import warnings
 from typing import Any
 
-from langchain_core._api import LangChainDeprecationWarning
+from langchain_core._api import caller_aware_warn
 
 from langchain.utils.interactive_env import is_interactive_env
 
@@ -27,13 +26,12 @@ def __getattr__(name: str) -> Any:
 
     # If not in interactive env, raise warning.
     if not is_interactive_env():
-        warnings.warn(
+        caller_aware_warn(
             "Importing docstores from langchain is deprecated. Importing from "
             "langchain will no longer be supported as of langchain==0.2.0. "
             "Please import from langchain-community instead:\n\n"
             f"`from langchain_community.docstore import {name}`.\n\n"
             "To install langchain-community run `pip install -U langchain-community`.",
-            category=LangChainDeprecationWarning,
         )
 
     return getattr(docstore, name)

libs/langchain/langchain/document_loaders/__init__.py

@@ -14,10 +14,9 @@
 
     Document, <name>TextSplitter
 """
-import warnings
 from typing import Any
 
-from langchain_core._api import LangChainDeprecationWarning
+from langchain_core._api import caller_aware_warn
 
 from langchain.utils.interactive_env import is_interactive_env
 
@@ -33,17 +32,16 @@ def __getattr__(name: str) -> Any:
 
     # If not in interactive env, raise warning.
     if not is_interactive_env():
-        warnings.warn(
+        caller_aware_warn(
             "Importing document loaders from langchain is deprecated. Importing from "
             "langchain will no longer be supported as of langchain==0.2.0. "
             "Please import from langchain-community instead:\n\n"
             f"`from langchain_community.document_loaders import {name}`.\n\n"
             "To install langchain-community run `pip install -U langchain-community`.",
-            category=LangChainDeprecationWarning,
         )
 
     if name in _old_to_new_name:
-        warnings.warn(
+        caller_aware_warn(
             f"Using legacy class name {name}, use {_old_to_new_name[name]} instead."
         )
         name = _old_to_new_name[name]

libs/langchain/langchain/document_transformers/__init__.py

@@ -14,10 +14,9 @@
 
     Document
 """  # noqa: E501
-import warnings
 from typing import Any
 
-from langchain_core._api import LangChainDeprecationWarning
+from langchain_core._api import caller_aware_warn
 
 from langchain.utils.interactive_env import is_interactive_env
 
@@ -27,13 +26,12 @@ def __getattr__(name: str) -> Any:
 
     # If not in interactive env, raise warning.
     if not is_interactive_env():
-        warnings.warn(
+        caller_aware_warn(
             "Importing document transformers from langchain is deprecated. Importing "
             "from langchain will no longer be supported as of langchain==0.2.0. "
             "Please import from langchain-community instead:\n\n"
             f"`from langchain_community.document_transformers import {name}`.\n\n"
             "To install langchain-community run `pip install -U langchain-community`.",
-            category=LangChainDeprecationWarning,
         )
 
     return getattr(document_transformers, name)

libs/langchain/langchain/embeddings/__init__.py

@@ -12,10 +12,9 @@ from different APIs and services.
 
 
 import logging
-import warnings
 from typing import Any
 
-from langchain_core._api import LangChainDeprecationWarning
+from langchain_core._api import caller_aware_warn
 
 from langchain.embeddings.cache import CacheBackedEmbeddings
 from langchain.utils.interactive_env import is_interactive_env
@@ -26,13 +25,12 @@ def __getattr__(name: str) -> Any:
 
     # If not in interactive env, raise warning.
     if not is_interactive_env():
-        warnings.warn(
+        caller_aware_warn(
             "Importing embeddings from langchain is deprecated. Importing from "
             "langchain will no longer be supported as of langchain==0.2.0. "
             "Please import from langchain-community instead:\n\n"
             f"`from langchain_community.embeddings import {name}`.\n\n"
             "To install langchain-community run `pip install -U langchain-community`.",
-            category=LangChainDeprecationWarning,
         )
 
     return getattr(embeddings, name)

libs/langchain/langchain/llms/__init__.py

@@ -17,10 +17,9 @@ access to the large language model (**LLM**) APIs and services.
     CallbackManager, AsyncCallbackManager,
     AIMessage, BaseMessage
 """  # noqa: E501
-import warnings
 from typing import Any, Callable, Dict, Type
 
-from langchain_core._api import LangChainDeprecationWarning
+from langchain_core._api import caller_aware_warn
 from langchain_core.language_models.llms import BaseLLM
 
 from langchain.utils.interactive_env import is_interactive_env
@@ -545,13 +544,12 @@ def __getattr__(name: str) -> Any:
 
     # If not in interactive env, raise warning.
     if not is_interactive_env():
-        warnings.warn(
+        caller_aware_warn(
             "Importing LLMs from langchain is deprecated. Importing from "
             "langchain will no longer be supported as of langchain==0.2.0. "
             "Please import from langchain-community instead:\n\n"
             f"`from langchain_community.llms import {name}`.\n\n"
             "To install langchain-community run `pip install -U langchain-community`.",
-            category=LangChainDeprecationWarning,
         )
 
     if name == "type_to_cls_dict":

libs/langchain/langchain/memory/chat_message_histories/__init__.py

@@ -1,7 +1,6 @@
-import warnings
 from typing import Any
 
-from langchain_core._api import LangChainDeprecationWarning
+from langchain_core._api import caller_aware_warn
 
 from langchain.utils.interactive_env import is_interactive_env
 
@@ -11,15 +10,13 @@ def __getattr__(name: str) -> Any:
 
     # If not in interactive env, raise warning.
     if not is_interactive_env():
-        warnings.warn(
+        caller_aware_warn(
             "Importing chat message histories from langchain is deprecated. Importing "
             "from langchain will no longer be supported as of langchain==0.2.0. "
             "Please import from langchain-community instead:\n\n"
             f"`from langchain_community.chat_message_histories import {name}`.\n\n"
             "To install langchain-community run `pip install -U langchain-community`.",
-            category=LangChainDeprecationWarning,
         )
-
     return getattr(chat_message_histories, name)
 
 

libs/langchain/langchain/retrievers/__init__.py

@@ -17,10 +17,9 @@ the backbone of a retriever, but there are other types of retrievers as well.
     Document, Serializable, Callbacks,
     CallbackManagerForRetrieverRun, AsyncCallbackManagerForRetrieverRun
 """
-import warnings
 from typing import Any
 
-from langchain_core._api import LangChainDeprecationWarning
+from langchain_core._api import caller_aware_warn
 
 from langchain.retrievers.contextual_compression import ContextualCompressionRetriever
 from langchain.retrievers.ensemble import EnsembleRetriever
@@ -43,13 +42,12 @@ def __getattr__(name: str) -> Any:
 
     # If not in interactive env, raise warning.
     if not is_interactive_env():
-        warnings.warn(
+        caller_aware_warn(
             "Importing this retriever from langchain is deprecated. Importing it from "
             "langchain will no longer be supported as of langchain==0.2.0. "
             "Please import from langchain-community instead:\n\n"
             f"`from langchain_community.retrievers import {name}`.\n\n"
             "To install langchain-community run `pip install -U langchain-community`.",
-            category=LangChainDeprecationWarning,
         )
 
     return getattr(retrievers, name)

libs/langchain/langchain/storage/__init__.py

@@ -5,10 +5,9 @@ to a simple key-value interface.
 
 The primary goal of these storages is to support implementation of caching.
 """
-import warnings
 from typing import Any
 
-from langchain_core._api import LangChainDeprecationWarning
+from langchain_core._api import caller_aware_warn
 
 from langchain.storage._lc_store import create_kv_docstore, create_lc_store
 from langchain.storage.encoder_backed import EncoderBackedStore
@@ -22,13 +21,12 @@ def __getattr__(name: str) -> Any:
 
     # If not in interactive env, raise warning.
     if not is_interactive_env():
-        warnings.warn(
+        caller_aware_warn(
             "Importing stores from langchain is deprecated. Importing from "
             "langchain will no longer be supported as of langchain==0.2.0. "
             "Please import from langchain-community instead:\n\n"
             f"`from langchain_community.storage import {name}`.\n\n"
             "To install langchain-community run `pip install -U langchain-community`.",
-            category=LangChainDeprecationWarning,
         )
 
     return getattr(storage, name)

libs/langchain/langchain/tools/__init__.py

@@ -16,10 +16,9 @@ tool for the job.
 
     CallbackManagerForToolRun, AsyncCallbackManagerForToolRun
 """
-import warnings
 from typing import Any
 
-from langchain_core._api import LangChainDeprecationWarning
+from langchain_core._api import caller_aware_warn
 from langchain_core.tools import BaseTool, StructuredTool, Tool, tool
 
 from langchain.utils.interactive_env import is_interactive_env
@@ -60,14 +59,13 @@ def __getattr__(name: str) -> Any:
 
         # If not in interactive env, raise warning.
         if not is_interactive_env():
-            warnings.warn(
+            caller_aware_warn(
                 "Importing tools from langchain is deprecated. Importing from "
                 "langchain will no longer be supported as of langchain==0.2.0. "
                 "Please import from langchain-community instead:\n\n"
                 f"`from langchain_community.tools import {name}`.\n\n"
                 "To install langchain-community run "
                 "`pip install -U langchain-community`.",
-                category=LangChainDeprecationWarning,
             )
 
         return getattr(tools, name)

libs/langchain/langchain/utilities/__init__.py

@@ -3,7 +3,6 @@
 Other LangChain classes use **Utilities** to interact with third-part systems
 and packages.
 """
-import warnings
 from typing import Any
 
 from langchain_community.utilities.requests import (
@@ -11,7 +10,7 @@ from langchain_community.utilities.requests import (
     RequestsWrapper,
     TextRequestsWrapper,
 )
-from langchain_core._api import LangChainDeprecationWarning
+from langchain_core._api import caller_aware_warn
 
 from langchain.utils.interactive_env import is_interactive_env
 
@@ -21,13 +20,12 @@ def __getattr__(name: str) -> Any:
 
     # If not in interactive env, raise warning.
     if not is_interactive_env():
-        warnings.warn(
+        caller_aware_warn(
             "Importing this utility from langchain is deprecated. Importing it from "
             "langchain will no longer be supported as of langchain==0.2.0. "
             "Please import from langchain-community instead:\n\n"
             f"`from langchain_community.utilities import {name}`.\n\n"
             "To install langchain-community run `pip install -U langchain-community`.",
-            category=LangChainDeprecationWarning,
         )
 
     return getattr(utilities, name)

libs/langchain/langchain/vectorstores/__init__.py

@@ -18,10 +18,9 @@ and retrieve the data that are 'most similar' to the embedded query.
 
     Embeddings, Document
 """  # noqa: E501
-import warnings
 from typing import Any
 
-from langchain_core._api import LangChainDeprecationWarning
+from langchain_core._api import caller_aware_warn
 from langchain_core.vectorstores import VectorStore
 
 from langchain.utils.interactive_env import is_interactive_env
@@ -32,13 +31,12 @@ def __getattr__(name: str) -> Any:
 
     # If not in interactive env, raise warning.
     if not is_interactive_env():
-        warnings.warn(
+        caller_aware_warn(
             "Importing vector stores from langchain is deprecated. Importing from "
             "langchain will no longer be supported as of langchain==0.2.0. "
             "Please import from langchain-community instead:\n\n"
             f"`from langchain_community.vectorstores import {name}`.\n\n"
             "To install langchain-community run `pip install -U langchain-community`.",
-            category=LangChainDeprecationWarning,
         )
 
     return getattr(vectorstores, name)