Update warnings parameter for serialization utilities to allow rais…

…ing a warning (#9166)

Signed-off-by: Lance-Drane <ldraneutk@gmail.com>
Co-authored-by: sydney-runkle <sydneymarierunkle@gmail.com>

pydantic/main.py

@@ -7,7 +7,7 @@
 import typing
 import warnings
 from copy import copy, deepcopy
-from typing import Any, ClassVar, Dict, Generator, Set, Tuple, TypeVar, Union
+from typing import Any, ClassVar, Dict, Generator, Literal, Set, Tuple, TypeVar, Union
 
 import pydantic_core
 import typing_extensions
@@ -299,7 +299,7 @@ def model_dump(
         exclude_defaults: bool = False,
         exclude_none: bool = False,
         round_trip: bool = False,
-        warnings: bool = True,
+        warnings: bool | Literal['none', 'warn', 'error'] = True,
         serialize_as_any: bool = False,
     ) -> dict[str, Any]:
         """Usage docs: https://docs.pydantic.dev/2.7/concepts/serialization/#modelmodel_dump
@@ -318,7 +318,8 @@ def model_dump(
             exclude_defaults: Whether to exclude fields that are set to their default value.
             exclude_none: Whether to exclude fields that have a value of `None`.
             round_trip: If True, dumped values should be valid as input for non-idempotent types such as Json[T].
-            warnings: Whether to log warnings when invalid fields are encountered.
+            warnings: How to handle serialization errors. False/"none" ignores them, True/"warn" logs errors,
+                "error" raises a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError].
             serialize_as_any: Whether to serialize fields with duck-typing serialization behavior.
 
         Returns:
@@ -351,7 +352,7 @@ def model_dump_json(
         exclude_defaults: bool = False,
         exclude_none: bool = False,
         round_trip: bool = False,
-        warnings: bool = True,
+        warnings: bool | Literal['none', 'warn', 'error'] = True,
         serialize_as_any: bool = False,
     ) -> str:
         """Usage docs: https://docs.pydantic.dev/2.7/concepts/serialization/#modelmodel_dump_json
@@ -368,7 +369,8 @@ def model_dump_json(
             exclude_defaults: Whether to exclude fields that are set to their default value.
             exclude_none: Whether to exclude fields that have a value of `None`.
             round_trip: If True, dumped values should be valid as input for non-idempotent types such as Json[T].
-            warnings: Whether to log warnings when invalid fields are encountered.
+            warnings: How to handle serialization errors. False/"none" ignores them, True/"warn" logs errors,
+                "error" raises a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError].
             serialize_as_any: Whether to serialize fields with duck-typing serialization behavior.
 
         Returns:

pydantic/root_model.py

@@ -130,7 +130,7 @@ def model_dump(  # type: ignore
             exclude_defaults: bool = False,
             exclude_none: bool = False,
             round_trip: bool = False,
-            warnings: bool = True,
+            warnings: bool | Literal['none', 'warn', 'error'] = True,
             serialize_as_any: bool = False,
         ) -> Any:
             """This method is included just to get a more accurate return type for type checkers.

pydantic/type_adapter.py

@@ -314,7 +314,7 @@ def dump_python(
         exclude_defaults: bool = False,
         exclude_none: bool = False,
         round_trip: bool = False,
-        warnings: bool = True,
+        warnings: bool | Literal['none', 'warn', 'error'] = True,
         serialize_as_any: bool = False,
     ) -> Any:
         """Dump an instance of the adapted type to a Python object.
@@ -329,7 +329,8 @@ def dump_python(
             exclude_defaults: Whether to exclude fields with default values.
             exclude_none: Whether to exclude fields with None values.
             round_trip: Whether to output the serialized data in a way that is compatible with deserialization.
-            warnings: Whether to display serialization warnings.
+            warnings: How to handle serialization errors. False/"none" ignores them, True/"warn" logs errors,
+                "error" raises a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError].
             serialize_as_any: Whether to serialize fields with duck-typing serialization behavior.
 
         Returns:
@@ -362,7 +363,7 @@ def dump_json(
         exclude_defaults: bool = False,
         exclude_none: bool = False,
         round_trip: bool = False,
-        warnings: bool = True,
+        warnings: bool | Literal['none', 'warn', 'error'] = True,
         serialize_as_any: bool = False,
     ) -> bytes:
         """Usage docs: https://docs.pydantic.dev/2.7/concepts/json/#json-serialization
@@ -379,7 +380,8 @@ def dump_json(
             exclude_defaults: Whether to exclude fields with default values.
             exclude_none: Whether to exclude fields with a value of `None`.
             round_trip: Whether to serialize and deserialize the instance to ensure round-tripping.
-            warnings: Whether to emit serialization warnings.
+            warnings: How to handle serialization errors. False/"none" ignores them, True/"warn" logs errors,
+                "error" raises a [`PydanticSerializationError`][pydantic_core.PydanticSerializationError].
             serialize_as_any: Whether to serialize fields with duck-typing serialization behavior.
 
         Returns: