style: more refs work (#33616)

Author: mdrxy

libs/core/langchain_core/documents/transformers.py

@@ -57,10 +57,10 @@ def transform_documents(
         """Transform a list of documents.
 
         Args:
-            documents: A sequence of Documents to be transformed.
+            documents: A sequence of `Document` objects to be transformed.
 
         Returns:
-            A sequence of transformed Documents.
+            A sequence of transformed `Document` objects.
         """
 
     async def atransform_documents(
@@ -69,10 +69,10 @@ async def atransform_documents(
         """Asynchronously transform a list of documents.
 
         Args:
-            documents: A sequence of Documents to be transformed.
+            documents: A sequence of `Document` objects to be transformed.
 
         Returns:
-            A sequence of transformed Documents.
+            A sequence of transformed `Document` objects.
         """
         return await run_in_executor(
             None, self.transform_documents, documents, **kwargs

libs/core/langchain_core/load/dump.py

@@ -38,7 +38,7 @@ def _dump_pydantic_models(obj: Any) -> Any:
 
 
 def dumps(obj: Any, *, pretty: bool = False, **kwargs: Any) -> str:
-    """Return a json string representation of an object.
+    """Return a JSON string representation of an object.
 
     Args:
         obj: The object to dump.
@@ -47,7 +47,7 @@ def dumps(obj: Any, *, pretty: bool = False, **kwargs: Any) -> str:
         **kwargs: Additional arguments to pass to `json.dumps`
 
     Returns:
-        A json string representation of the object.
+        A JSON string representation of the object.
 
     Raises:
         ValueError: If `default` is passed as a kwarg.
@@ -71,14 +71,12 @@ def dumps(obj: Any, *, pretty: bool = False, **kwargs: Any) -> str:
 def dumpd(obj: Any) -> Any:
     """Return a dict representation of an object.
 
-    !!! note
-        Unfortunately this function is not as efficient as it could be because it first
-        dumps the object to a json string and then loads it back into a dictionary.
-
     Args:
         obj: The object to dump.
 
     Returns:
-        dictionary that can be serialized to json using json.dumps
+        Dictionary that can be serialized to json using `json.dumps`.
     """
+    # Unfortunately this function is not as efficient as it could be because it first
+    # dumps the object to a json string and then loads it back into a dictionary.
     return json.loads(dumps(obj))

libs/core/langchain_core/messages/utils.py

@@ -439,8 +439,8 @@ def filter_messages(
         exclude_ids: Message IDs to exclude.
         exclude_tool_calls: Tool call IDs to exclude.
             Can be one of the following:
-            - `True`: all `AIMessage`s with tool calls and all
-                `ToolMessage` objects will be excluded.
+            - `True`: All `AIMessage` objects with tool calls and all `ToolMessage`
+                objects will be excluded.
             - a sequence of tool call IDs to exclude:
                 - `ToolMessage` objects with the corresponding tool call ID will be
                     excluded.

libs/core/langchain_core/runnables/branch.py

@@ -40,13 +40,13 @@
 class RunnableBranch(RunnableSerializable[Input, Output]):
     """Runnable that selects which branch to run based on a condition.
 
-    The Runnable is initialized with a list of (condition, Runnable) pairs and
+    The Runnable is initialized with a list of `(condition, Runnable)` pairs and
     a default branch.
 
     When operating on an input, the first condition that evaluates to True is
-    selected, and the corresponding Runnable is run on the input.
+    selected, and the corresponding `Runnable` is run on the input.
 
-    If no condition evaluates to True, the default branch is run on the input.
+    If no condition evaluates to `True`, the default branch is run on the input.
 
     Examples:
         ```python
@@ -65,9 +65,9 @@ class RunnableBranch(RunnableSerializable[Input, Output]):
     """
 
     branches: Sequence[tuple[Runnable[Input, bool], Runnable[Input, Output]]]
-    """A list of (condition, Runnable) pairs."""
+    """A list of `(condition, Runnable)` pairs."""
     default: Runnable[Input, Output]
-    """A Runnable to run if no condition is met."""
+    """A `Runnable` to run if no condition is met."""
 
     def __init__(
         self,
@@ -79,15 +79,15 @@ def __init__(
         ]
         | RunnableLike,
     ) -> None:
-        """A Runnable that runs one of two branches based on a condition.
+        """A `Runnable` that runs one of two branches based on a condition.
 
         Args:
-            *branches: A list of (condition, Runnable) pairs.
-                Defaults a Runnable to run if no condition is met.
+            *branches: A list of `(condition, Runnable)` pairs.
+                Defaults a `Runnable` to run if no condition is met.
 
         Raises:
             ValueError: If the number of branches is less than 2.
-            TypeError: If the default branch is not Runnable, Callable or Mapping.
+            TypeError: If the default branch is not `Runnable`, `Callable` or `Mapping`.
             TypeError: If a branch is not a tuple or list.
             ValueError: If a branch is not of length 2.
         """

libs/core/langchain_core/vectorstores/in_memory.py

@@ -260,7 +260,7 @@ def get_by_ids(self, ids: Sequence[str], /) -> list[Document]:
             ids: The ids of the documents to get.
 
         Returns:
-            A list of Document objects.
+            A list of `Document` objects.
         """
         documents = []
 
@@ -284,7 +284,7 @@ async def aget_by_ids(self, ids: Sequence[str], /) -> list[Document]:
             ids: The ids of the documents to get.
 
         Returns:
-            A list of Document objects.
+            A list of `Document` objects.
         """
         return self.get_by_ids(ids)
 

libs/partners/mistralai/langchain_mistralai/chat_models.py

@@ -446,7 +446,7 @@ def _convert_message_to_mistral_chat_message(
 
 
 class ChatMistralAI(BaseChatModel):
-    """A chat model that uses the MistralAI API."""
+    """A chat model that uses the Mistral AI API."""
 
     # The type for client and async_client is ignored because the type is not
     # an Optional after the model is initialized and the model_validator

libs/standard-tests/langchain_tests/__init__.py

@@ -1,6 +1,5 @@
-"""Base Test classes for standard testing.
+"""Base test classes for standard testing.
 
-To learn how to use these classes, see the
-[integration standard testing](https://python.langchain.com/docs/contributing/how_to/integrations/standard_tests/)
-guide.
+To learn how to use these, see the guide on
+[integrating standard tests](https://docs.langchain.com/oss/python/contributing/standard-tests-langchain).
 """

libs/standard-tests/langchain_tests/integration_tests/chat_models.py

@@ -182,23 +182,21 @@ def chat_model_params(self) -> dict:
 
     Test subclasses **must** implement the following two properties:
 
-    chat_model_class
-        The chat model class to test, e.g., `ChatParrotLink`.
+    `chat_model_class`: The chat model class to test, e.g., `ChatParrotLink`.
 
-        ```python
-        @property
-        def chat_model_class(self) -> Type[ChatParrotLink]:
-            return ChatParrotLink
-        ```
+    ```python
+    @property
+    def chat_model_class(self) -> Type[ChatParrotLink]:
+        return ChatParrotLink
+    ```
 
-    chat_model_params
-        Initialization parameters for the chat model.
+    `chat_model_params`: Initialization parameters for the chat model.
 
-        ```python
-        @property
-        def chat_model_params(self) -> dict:
-            return {"model": "bird-brain-001", "temperature": 0}
-        ```
+    ```python
+    @property
+    def chat_model_params(self) -> dict:
+        return {"model": "bird-brain-001", "temperature": 0}
+    ```
 
     In addition, test subclasses can control what features are tested (such as tool
     calling or multi-modality) by selectively overriding the following properties.
@@ -266,7 +264,7 @@ def has_tool_choice(self) -> bool:
         `with_structured_output` method is overridden. If the base implementation is
         intended to be used, this method should be overridden.
 
-        See: https://python.langchain.com/docs/concepts/structured_outputs/
+        See: https://docs.langchain.com/oss/python/langchain/structured-output
 
         ```python
         @property
@@ -290,7 +288,7 @@ def structured_output_kwargs(self) -> dict:
         Boolean property indicating whether the chat model supports JSON mode in
         `with_structured_output`.
 
-        See: https://python.langchain.com/docs/concepts/structured_outputs/#json-mode
+        See: https://docs.langchain.com/oss/python/langchain/structured-output
 
         ```python
         @property
@@ -324,7 +322,7 @@ def supports_json_mode(self) -> bool:
         }
         ```
 
-        See https://python.langchain.com/docs/concepts/multimodality/
+        See https://docs.langchain.com/oss/python/langchain/models#multimodal
 
         ```python
         @property
@@ -349,7 +347,7 @@ def supports_image_inputs(self) -> bool:
         }
         ```
 
-        See https://python.langchain.com/docs/concepts/multimodality/
+        See https://docs.langchain.com/oss/python/langchain/models#multimodal
 
         ```python
         @property
@@ -374,7 +372,7 @@ def supports_image_urls(self) -> bool:
         }
         ```
 
-        See https://python.langchain.com/docs/concepts/multimodality/
+        See https://docs.langchain.com/oss/python/langchain/models#multimodal
 
         ```python
         @property
@@ -399,7 +397,7 @@ def supports_pdf_inputs(self) -> bool:
         }
         ```
 
-        See https://python.langchain.com/docs/concepts/multimodality/
+        See https://docs.langchain.com/oss/python/langchain/models#multimodal
 
         ```python
         @property
@@ -420,8 +418,8 @@ def supports_audio_inputs(self) -> bool:
 
         Defaults to `True`.
 
-        `usage_metadata` is an optional dict attribute on `AIMessage`s that track input
-        and output tokens.
+        `usage_metadata` is an optional dict attribute on `AIMessage` objects that track
+        input and output tokens.
         [See more](https://python.langchain.com/api_reference/core/messages/langchain_core.messages.ai.UsageMetadata.html).
 
         ```python
@@ -537,8 +535,8 @@ def supports_pdf_tool_message(self) -> bool:
         Property controlling what usage metadata details are emitted in both invoke
         and stream.
 
-        `usage_metadata` is an optional dict attribute on `AIMessage`s that track input
-        and output tokens.
+        `usage_metadata` is an optional dict attribute on `AIMessage` objects that track
+        input and output tokens.
         [See more](https://python.langchain.com/api_reference/core/messages/langchain_core.messages.ai.UsageMetadata.html).
 
         It includes optional keys `input_token_details` and `output_token_details`
@@ -580,9 +578,7 @@ def enable_vcr_tests(self) -> bool:
             also exclude additional headers, override the default exclusions, or apply
             other customizations to the VCR configuration. See example below:
 
-            ```python
-            :caption: tests/conftest.py
-
+            ```python title="tests/conftest.py"
             import pytest
             from langchain_tests.conftest import (
                 _base_vcr_config as _base_vcr_config,
@@ -617,9 +613,7 @@ def vcr_config(_base_vcr_config: dict) -> dict:  # noqa: F811
                 to your VCR fixture and enable this serializer in the config. See
                 example below:
 
-                ```python
-                :caption: tests/conftest.py
-
+                ```python title="tests/conftest.py"
                 import pytest
                 from langchain_tests.conftest import (
                     CustomPersister,
@@ -658,7 +652,6 @@ def vcr_config(_base_vcr_config: dict) -> dict:  # noqa: F811
                 def pytest_recording_configure(config: dict, vcr: VCR) -> None:
                     vcr.register_persister(CustomPersister())
                     vcr.register_serializer("yaml.gz", CustomSerializer())
-
                 ```
 
                 You can inspect the contents of the compressed cassettes (e.g., to

libs/standard-tests/langchain_tests/integration_tests/tools.py

@@ -12,7 +12,8 @@ class ToolsIntegrationTests(ToolsTests):
     def test_invoke_matches_output_schema(self, tool: BaseTool) -> None:
         """Test invoke matches output schema.
 
-        If invoked with a ToolCall, the tool should return a valid ToolMessage content.
+        If invoked with a `ToolCall`, the tool should return a valid `ToolMessage`
+        content.
 
         If you have followed the [custom tool guide](https://python.langchain.com/docs/how_to/custom_tools/),
         this test should always pass because ToolCall inputs are handled by the
@@ -44,7 +45,8 @@ def test_invoke_matches_output_schema(self, tool: BaseTool) -> None:
     async def test_async_invoke_matches_output_schema(self, tool: BaseTool) -> None:
         """Test async invoke matches output schema.
 
-        If ainvoked with a ToolCall, the tool should return a valid ToolMessage content.
+        If ainvoked with a `ToolCall`, the tool should return a valid `ToolMessage`
+        content.
 
         For debugging tips, see `test_invoke_matches_output_schema`.
         """
@@ -68,9 +70,9 @@ async def test_async_invoke_matches_output_schema(self, tool: BaseTool) -> None:
             assert all(isinstance(c, str | dict) for c in tool_message.content)
 
     def test_invoke_no_tool_call(self, tool: BaseTool) -> None:
-        """Test invoke without ToolCall.
+        """Test invoke without `ToolCall`.
 
-        If invoked without a ToolCall, the tool can return anything
+        If invoked without a `ToolCall`, the tool can return anything
         but it shouldn't throw an error.
 
         If this test fails, your tool may not be handling the input you defined
@@ -82,9 +84,9 @@ def test_invoke_no_tool_call(self, tool: BaseTool) -> None:
         tool.invoke(self.tool_invoke_params_example)
 
     async def test_async_invoke_no_tool_call(self, tool: BaseTool) -> None:
-        """Test async invoke without ToolCall.
+        """Test async invoke without `ToolCall`.
 
-        If ainvoked without a ToolCall, the tool can return anything
+        If ainvoked without a `ToolCall`, the tool can return anything
         but it shouldn't throw an error.
 
         For debugging tips, see `test_invoke_no_tool_call`.

libs/standard-tests/langchain_tests/integration_tests/vectorstores.py

@@ -103,7 +103,7 @@ def has_async(self) -> bool:
     def vectorstore(self) -> VectorStore:
         """Get the vectorstore class to test.
 
-        The returned vectorstore should be EMPTY.
+        The returned vectorstore should be empty.
         """
 
     @property
@@ -398,7 +398,7 @@ def has_get_by_ids(self) -> bool:
         assert documents == []
 
     def test_add_documents_documents(self, vectorstore: VectorStore) -> None:
-        """Run add_documents tests.
+        """Run `add_documents` tests.
 
         ??? note "Troubleshooting"
 
@@ -439,7 +439,7 @@ def has_get_by_ids(self) -> bool:
         )
 
     def test_add_documents_with_existing_ids(self, vectorstore: VectorStore) -> None:
-        """Test that add_documents with existing IDs is idempotent.
+        """Test that `add_documents` with existing IDs is idempotent.
 
         ??? note "Troubleshooting"
 
@@ -754,7 +754,7 @@ def has_get_by_ids(self) -> bool:
     async def test_add_documents_documents_async(
         self, vectorstore: VectorStore
     ) -> None:
-        """Run add_documents tests.
+        """Run `add_documents` tests.
 
         ??? note "Troubleshooting"
 
@@ -797,7 +797,7 @@ def has_get_by_ids(self) -> bool:
     async def test_add_documents_with_existing_ids_async(
         self, vectorstore: VectorStore
     ) -> None:
-        """Test that add_documents with existing IDs is idempotent.
+        """Test that `add_documents` with existing IDs is idempotent.
 
         ??? note "Troubleshooting"