Ability to pass context to serialization (fix #7143)

docs/concepts/serialization.md

@@ -702,6 +702,40 @@ print(person.model_dump(exclude_defaults=True))  # (3)!
 2. `age` excluded from the output because `exclude_unset` was set to `True`, and `age` was not set in the Person constructor.
 3. `age` excluded from the output because `exclude_defaults` was set to `True`, and `age` takes the default value of `None`.
 
+## Serialization Context
+
+You can pass a context object to the serialization methods which can be accessed from the `info`
+argument to decorated serializer functions. This is useful when you need to dynamically update the
+serialization behavior during runtime. For example, if you wanted a field to be dumped depending on
+a dynamically controllable set of allowed values, this could be done by passing the allowed values
+by context:
+
+```python
+from pydantic import BaseModel, SerializationInfo, field_serializer
+
+
+class Model(BaseModel):
+    text: str
+
+    @field_serializer('text')
+    def remove_stopwords(self, v: str, info: SerializationInfo):
+        context = info.context
+        if context:
+            stopwords = context.get('stopwords', set())
+            v = ' '.join(w for w in v.split() if w.lower() not in stopwords)
+        return v
+
+
+model = Model.model_construct(**{'text': 'This is an example document'})
+print(model.model_dump())  # no context
+#> {'text': 'This is an example document'}
+print(model.model_dump(context={'stopwords': ['this', 'is', 'an']}))
+#> {'text': 'example document'}
+print(model.model_dump(context={'stopwords': ['document']}))
+#> {'text': 'This is an example'}
+```
+
+
 
 ## `model_copy(...)`
 

pydantic/main.py

@@ -292,6 +292,7 @@ def model_dump(
         mode: typing_extensions.Literal['json', 'python'] | str = 'python',
         include: IncEx = None,
         exclude: IncEx = None,
+        context: dict[str, Any] | None = None,
         by_alias: bool = False,
         exclude_unset: bool = False,
         exclude_defaults: bool = False,
@@ -309,6 +310,7 @@ def model_dump(
                 If mode is 'python', the output may contain non-JSON-serializable Python objects.
             include: A set of fields to include in the output.
             exclude: A set of fields to exclude from the output.
+            context: Additional context to pass to the serializer.
             by_alias: Whether to use the field's alias in the dictionary key if defined.
             exclude_unset: Whether to exclude fields that have not been explicitly set.
             exclude_defaults: Whether to exclude fields that are set to their default value.
@@ -325,6 +327,7 @@ def model_dump(
             by_alias=by_alias,
             include=include,
             exclude=exclude,
+            context=context,
             exclude_unset=exclude_unset,
             exclude_defaults=exclude_defaults,
             exclude_none=exclude_none,
@@ -338,6 +341,7 @@ def model_dump_json(
         indent: int | None = None,
         include: IncEx = None,
         exclude: IncEx = None,
+        context: dict[str, Any] | None = None,
         by_alias: bool = False,
         exclude_unset: bool = False,
         exclude_defaults: bool = False,
@@ -353,6 +357,7 @@ def model_dump_json(
             indent: Indentation to use in the JSON output. If None is passed, the output will be compact.
             include: Field(s) to include in the JSON output.
             exclude: Field(s) to exclude from the JSON output.
+            context: Additional context to pass to the serializer.
             by_alias: Whether to serialize using field aliases.
             exclude_unset: Whether to exclude fields that have not been explicitly set.
             exclude_defaults: Whether to exclude fields that are set to their default value.
@@ -368,6 +373,7 @@ def model_dump_json(
             indent=indent,
             include=include,
             exclude=exclude,
+            context=context,
             by_alias=by_alias,
             exclude_unset=exclude_unset,
             exclude_defaults=exclude_defaults,

tests/test_serialize.py

@@ -1159,3 +1159,39 @@ class Foo(BaseModel):
 
     foo_recursive = Foo(items=[Foo(items=[Baz(bar_id=42, baz_id=99)])])
     assert foo_recursive.model_dump() == {'items': [{'items': [{'bar_id': 42}]}]}
+
+
+def test_serialize_python_context() -> None:
+    contexts: List[Any] = [None, None, {'foo': 'bar'}]
+
+    class Model(BaseModel):
+        x: int
+
+        @field_serializer('x')
+        def serialize_x(self, v: int, info: SerializationInfo) -> int:
+            assert info.context == contexts.pop(0)
+            return v
+
+    m = Model.model_construct(**{'x': 1})
+    m.model_dump()
+    m.model_dump(context=None)
+    m.model_dump(context={'foo': 'bar'})
+    assert contexts == []
+
+
+def test_serialize_json_context() -> None:
+    contexts: List[Any] = [None, None, {'foo': 'bar'}]
+
+    class Model(BaseModel):
+        x: int
+
+        @field_serializer('x')
+        def serialize_x(self, v: int, info: SerializationInfo) -> int:
+            assert info.context == contexts.pop(0)
+            return v
+
+    m = Model.model_construct(**{'x': 1})
+    m.model_dump_json()
+    m.model_dump_json(context=None)
+    m.model_dump_json(context={'foo': 'bar'})
+    assert contexts == []