The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
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.pyindex 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.pyindex 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 Anyclass 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.pynew file mode 100644index 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.pyindex 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_objfrom langchain_core.utils.utils import secret_from_envif 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 + chunk2assert 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))