Skip to content

The agent engineering platform.

test(core): add tests for formatting utils and merge functions (#34511)

ゆりbe2c7f1aa897
diff --git a/libs/core/langchain_core/utils/_merge.py b/libs/core/langchain_core/utils/_merge.py
index d37f8fd48a..9a39ecea80 100644
--- a/libs/core/langchain_core/utils/_merge.py
+++ b/libs/core/langchain_core/utils/_merge.py
@@ -7,8 +7,8 @@ def merge_dicts(left: dict[str, Any], *others: dict[str, Any]) -> dict[str, Any]
r"""Merge dictionaries.
Merge many dicts, handling specific scenarios where a key exists in both
- dictionaries but has a value of None in 'left'. In such cases, the method uses the
- value from 'right' for that key in the merged dictionary.
+ dictionaries but has a value of `None` in `'left'`. In such cases, the method uses
+ the value from `'right'` for that key in the merged dictionary.
Args:
left: The first dictionary to merge.
@@ -22,11 +22,10 @@ def merge_dicts(left: dict[str, Any], *others: dict[str, Any]) -> dict[str, Any]
TypeError: If the value has an unsupported type.
Example:
- If left = {"function_call": {"arguments": None}} and
- right = {"function_call": {"arguments": "{\n"}}
- then, after merging, for the key "function_call",
- the value from 'right' is used,
- resulting in merged = {"function_call": {"arguments": "{\n"}}.
+ If `left = {"function_call": {"arguments": None}}` and
+ `right = {"function_call": {"arguments": "{\n"}}`, then, after merging, for the
+ key `'function_call'`, the value from `'right'` is used, resulting in
+ `merged = {"function_call": {"arguments": "{\n"}}`.
"""
merged = left.copy()
for right in others:
@@ -81,7 +80,7 @@ def merge_dicts(left: dict[str, Any], *others: dict[str, Any]) -> dict[str, Any]
def merge_lists(left: list | None, *others: list | None) -> list | None:
- """Add many lists, handling None.
+ """Add many lists, handling `None`.
Args:
left: The first list to merge.
@@ -156,9 +155,9 @@ def merge_lists(left: list | None, *others: list | None) -> list | None:
def merge_obj(left: Any, right: Any) -> Any:
"""Merge two objects.
- It handles specific scenarios where a key exists in both
- dictionaries but has a value of None in 'left'. In such cases, the method uses the
- value from 'right' for that key in the merged dictionary.
+ It handles specific scenarios where a key exists in both dictionaries but has a
+ value of `None` in `'left'`. In such cases, the method uses the value from `'right'`
+ for that key in the merged dictionary.
Args:
left: The first object to merge.
diff --git a/libs/core/langchain_core/utils/formatting.py b/libs/core/langchain_core/utils/formatting.py
index d2313c5ca4..48905a4cc0 100644
--- a/libs/core/langchain_core/utils/formatting.py
+++ b/libs/core/langchain_core/utils/formatting.py
@@ -6,23 +6,38 @@ from typing import Any
class StrictFormatter(Formatter):
- """Formatter that checks for extra keys."""
+ """A string formatter that enforces keyword-only argument substitution.
+
+ This formatter extends Python's built-in `string.Formatter` to provide stricter
+ validation for prompt template formatting. It ensures that all variable
+ substitutions use keyword arguments rather than positional arguments, which improves
+ clarity and reduces errors when formatting prompt templates.
+
+ Example:
+ >>> fmt = StrictFormatter()
+ >>> fmt.format("Hello, {name}!", name="World")
+ 'Hello, World!'
+ >>> fmt.format("Hello, {}!", "World") # Raises ValueError
+ """
def vformat(
self, format_string: str, args: Sequence, kwargs: Mapping[str, Any]
) -> str:
- """Check that no arguments are provided.
+ """Format a string using only keyword arguments.
+
+ Overrides the base `vformat` to reject positional arguments, ensuring all
+ substitutions are explicit and named.
Args:
- format_string: The format string.
- args: The arguments.
- kwargs: The keyword arguments.
+ format_string: A string containing replacement fields (e.g., `'{name}'`).
+ args: Positional arguments (must be empty).
+ kwargs: Keyword arguments for substitution into the format string.
Returns:
- The formatted string.
+ The formatted string with all replacement fields substituted.
Raises:
- ValueError: If any arguments are provided.
+ ValueError: If any positional arguments are provided.
"""
if len(args) > 0:
msg = (
@@ -35,17 +50,31 @@ class StrictFormatter(Formatter):
def validate_input_variables(
self, format_string: str, input_variables: list[str]
) -> None:
- """Check that all input variables are used in the format string.
+ """Validate that input variables match the placeholders in a format string.
+
+ Checks that the provided input variables can be used to format the given string
+ without missing or extra keys. This is useful for validating prompt templates
+ before runtime.
Args:
- format_string: The format string.
- input_variables: The input variables.
+ format_string: A string containing replacement fields to validate
+ against (e.g., `'Hello, {name}!'`).
+ input_variables: List of variable names expected to fill the
+ replacement fields.
Raises:
- ValueError: If any input variables are not used in the format string.
+ KeyError: If the format string contains placeholders not present
+ in input_variables.
+
+ Example:
+ >>> fmt = StrictFormatter()
+ >>> fmt.validate_input_variables("Hello, {name}!", ["name"]) # OK
+ >>> fmt.validate_input_variables("Hello, {name}!", ["other"]) # Raises
"""
dummy_inputs = dict.fromkeys(input_variables, "foo")
super().format(format_string, **dummy_inputs)
+#: Default StrictFormatter instance for use throughout LangChain.
+#: Used internally for formatting prompt templates with named variables.
formatter = StrictFormatter()
diff --git a/libs/core/tests/unit_tests/utils/test_formatting.py b/libs/core/tests/unit_tests/utils/test_formatting.py
new file mode 100644
index 0000000000..9ae725abc8
--- /dev/null
+++ b/libs/core/tests/unit_tests/utils/test_formatting.py
@@ -0,0 +1,127 @@
+"""Tests for langchain_core.utils.formatting."""
+
+import pytest
+
+from langchain_core.utils.formatting import StrictFormatter, formatter
+
+
+class TestStrictFormatter:
+ """Tests for the `StrictFormatter` class."""
+
+ def test_vformat_with_keyword_args(self) -> None:
+ """Test that `vformat` works with keyword arguments."""
+ fmt = StrictFormatter()
+ result = fmt.vformat("Hello, {name}!", [], {"name": "World"})
+ assert result == "Hello, World!"
+
+ def test_vformat_with_multiple_keyword_args(self) -> None:
+ """Test `vformat` with multiple keyword arguments."""
+ fmt = StrictFormatter()
+ result = fmt.vformat(
+ "{greeting}, {name}! You have {count} messages.",
+ [],
+ {"greeting": "Hello", "name": "Alice", "count": 5},
+ )
+ assert result == "Hello, Alice! You have 5 messages."
+
+ def test_vformat_with_empty_string(self) -> None:
+ """Test `vformat` with empty format string."""
+ fmt = StrictFormatter()
+ result = fmt.vformat("", [], {})
+ assert result == ""
+
+ def test_vformat_with_no_placeholders(self) -> None:
+ """Test `vformat` with no placeholders in format string."""
+ fmt = StrictFormatter()
+ result = fmt.vformat("Hello, World!", [], {})
+ assert result == "Hello, World!"
+
+ def test_vformat_raises_on_positional_args(self) -> None:
+ """Test that `vformat` raises `ValueError` when positional args are provided."""
+ fmt = StrictFormatter()
+ with pytest.raises(
+ ValueError,
+ match=r"No arguments should be provided, "
+ r"everything should be passed as keyword arguments\.",
+ ):
+ fmt.vformat("{}", ["arg"], {})
+
+ def test_vformat_raises_on_multiple_positional_args(self) -> None:
+ """Test that `vformat` raises `ValueError` with multiple positional args."""
+ fmt = StrictFormatter()
+ with pytest.raises(ValueError, match=r"No arguments should be provided"):
+ fmt.vformat("{} {}", ["arg1", "arg2"], {})
+
+ def test_vformat_with_special_characters(self) -> None:
+ """Test `vformat` with special characters in values."""
+ fmt = StrictFormatter()
+ result = fmt.vformat("{text}", [], {"text": "Hello\nWorld\t!"})
+ assert result == "Hello\nWorld\t!"
+
+ def test_vformat_with_unicode(self) -> None:
+ """Test `vformat` with unicode characters."""
+ fmt = StrictFormatter()
+ result = fmt.vformat(
+ "{emoji} {text}", [], {"emoji": "🎉", "text": "こんにちは"}
+ )
+ assert result == "🎉 こんにちは"
+
+ def test_vformat_with_format_spec(self) -> None:
+ """Test `vformat` with format specifications."""
+ fmt = StrictFormatter()
+ result = fmt.vformat("{num:.2f}", [], {"num": 3.14159})
+ assert result == "3.14"
+
+ def test_vformat_with_nested_braces(self) -> None:
+ """Test `vformat` with escaped braces."""
+ fmt = StrictFormatter()
+ result = fmt.vformat("{{literal}} {var}", [], {"var": "value"})
+ assert result == "{literal} value"
+
+ def test_validate_input_variables_success(self) -> None:
+ """Test that `validate_input_variables` succeeds with valid input."""
+ fmt = StrictFormatter()
+ # Should not raise
+ fmt.validate_input_variables("{name} {age}", ["name", "age"])
+
+ def test_validate_input_variables_with_extra_variables(self) -> None:
+ """Test `validate_input_variables` with extra variables (should succeed)."""
+ fmt = StrictFormatter()
+ # Extra variables are allowed
+ fmt.validate_input_variables("{name}", ["name", "extra"])
+
+ def test_validate_input_variables_with_missing_variable(self) -> None:
+ """Test `validate_input_variables` raises with missing variable."""
+ fmt = StrictFormatter()
+ with pytest.raises(KeyError):
+ fmt.validate_input_variables("{name} {missing}", ["name"])
+
+ def test_validate_input_variables_empty_format(self) -> None:
+ """Test `validate_input_variables` with empty format string."""
+ fmt = StrictFormatter()
+ # Should not raise
+ fmt.validate_input_variables("", [])
+
+ def test_validate_input_variables_no_placeholders(self) -> None:
+ """Test `validate_input_variables` with no placeholders."""
+ fmt = StrictFormatter()
+ # Should not raise
+ fmt.validate_input_variables("Hello, World!", [])
+
+
+class TestFormatterSingleton:
+ """Tests for the formatter singleton instance."""
+
+ def test_formatter_is_strict_formatter(self) -> None:
+ """Test that the formatter singleton is a `StrictFormatter` instance."""
+ assert isinstance(formatter, StrictFormatter)
+
+ def test_formatter_format_works(self) -> None:
+ """Test that the formatter singleton can format strings."""
+ result = formatter.format("{greeting}, {name}!", greeting="Hello", name="World")
+ assert result == "Hello, World!"
+
+ def test_formatter_rejects_positional_args(self) -> None:
+ """Test that the formatter singleton rejects positional arguments."""
+ with pytest.raises(ValueError, match=r"No arguments should be provided"):
+ formatter.format("{}", "arg")
diff --git a/libs/core/tests/unit_tests/utils/test_utils.py b/libs/core/tests/unit_tests/utils/test_utils.py
index c492980047..78988b71fd 100644
--- a/libs/core/tests/unit_tests/utils/test_utils.py
+++ b/libs/core/tests/unit_tests/utils/test_utils.py
@@ -19,7 +19,7 @@ from langchain_core.utils import (
get_pydantic_field_names,
guard_import,
)
-from langchain_core.utils._merge import merge_dicts
+from langchain_core.utils._merge import merge_dicts, merge_lists, merge_obj
from langchain_core.utils.utils import secret_from_env
if TYPE_CHECKING:
@@ -386,3 +386,106 @@ def test_generation_chunk_addition_type_error() -> None:
chunk2 = GenerationChunk(text="Non-empty text", generation_info={"len": 14})
result = chunk1 + chunk2
assert result == GenerationChunk(text="Non-empty text", generation_info={"len": 14})
+
+
+ ("left", "right", "expected"),
+ [
+ # Both None
+ (None, None, None),
+ # Left None
+ (None, [1, 2], [1, 2]),
+ # Right None
+ ([1, 2], None, [1, 2]),
+ # Simple merge
+ ([1, 2], [3, 4], [1, 2, 3, 4]),
+ # Empty lists
+ ([], [], []),
+ ([], [1], [1]),
+ ([1], [], [1]),
+ # Merge with index handling
+ (
+ [{"index": 0, "text": "hello"}],
+ [{"index": 0, "text": " world"}],
+ [{"index": 0, "text": "hello world"}],
+ ),
+ # Multiple elements with different indexes
+ (
+ [{"index": 0, "a": "x"}],
+ [{"index": 1, "b": "y"}],
+ [{"index": 0, "a": "x"}, {"index": 1, "b": "y"}],
+ ),
+ # Elements without index key
+ (
+ [{"no_index": "a"}],
+ [{"no_index": "b"}],
+ [{"no_index": "a"}, {"no_index": "b"}],
+ ),
+ ],
+)
+def test_merge_lists(
+ left: list | None, right: list | None, expected: list | None
+) -> None:
+ left_copy = deepcopy(left)
+ right_copy = deepcopy(right)
+ actual = merge_lists(left, right)
+ assert actual == expected
+ # Verify no mutation
+ assert left == left_copy
+ assert right == right_copy
+
+
+def test_merge_lists_multiple_others() -> None:
+ """Test `merge_lists` with multiple lists."""
+ result = merge_lists([1], [2], [3])
+ assert result == [1, 2, 3]
+
+
+def test_merge_lists_all_none() -> None:
+ """Test `merge_lists` with all `None` arguments."""
+ result = merge_lists(None, None, None)
+ assert result is None
+
+
+ ("left", "right", "expected"),
+ [
+ # Both None
+ (None, None, None),
+ # Left None
+ (None, "hello", "hello"),
+ # Right None
+ ("hello", None, "hello"),
+ # String merge
+ ("hello", " world", "hello world"),
+ # Dict merge
+ ({"a": 1}, {"b": 2}, {"a": 1, "b": 2}),
+ # List merge
+ ([1, 2], [3], [1, 2, 3]),
+ # Equal values
+ (42, 42, 42),
+ (3.14, 3.14, 3.14),
+ (True, True, True),
+ ],
+)
+def test_merge_obj(left: Any, right: Any, expected: Any) -> None:
+ actual = merge_obj(left, right)
+ assert actual == expected
+
+
+def test_merge_obj_type_mismatch() -> None:
+ """Test `merge_obj` raises `TypeError` on type mismatch."""
+ with pytest.raises(TypeError, match="left and right are of different types"):
+ merge_obj("string", 123)
+
+
+def test_merge_obj_unmergeable_values() -> None:
+ """Test `merge_obj` raises `ValueError` on unmergeable values."""
+ with pytest.raises(ValueError, match="Unable to merge"):
+ merge_obj(1, 2) # Different integers
+
+
+def test_merge_obj_tuple_raises() -> None:
+ """Test `merge_obj` raises `ValueError` for tuples."""
+ with pytest.raises(ValueError, match="Unable to merge"):
+ merge_obj((1, 2), (3, 4))