docs: improve docstring for get_serializer to clarify behavior #9870
Conversation
| Give explicit errors when users attempt to pass writable nested data. | ||
| If we don't do this explicitly they'd get a less helpful error when | ||
| calling `.save()` on the serializer. | ||
| Enforce explicit handling of writable nested and dotted-source fields. | ||
| We don't *automatically* support these sorts of nested writes because | ||
| there are too many ambiguities to define a default behavior. | ||
| This helper raises clear and actionable errors when a serializer attempts | ||
| to perform writable nested updates or creates using the default | ||
| `ModelSerializer` behavior. | ||
| Eg. Suppose we have a `UserSerializer` with a nested profile. How should | ||
| we handle the case of an update, where the `profile` relationship does | ||
| not exist? Any of the following might be valid: | ||
| Writable nested relationships and dotted-source fields are intentionally | ||
| unsupported by default due to ambiguous persistence semantics. Developers | ||
| must either: | ||
| - Override the `.create()` / `.update()` methods explicitly, or | ||
| - Mark nested serializers as `read_only=True` | ||
| * Raise an application error. | ||
| * Silently ignore the nested part of the update. | ||
| * Automatically create a profile instance. | ||
| This check is invoked internally by default `ModelSerializer.create()` | ||
| and `ModelSerializer.update()` implementations. |
There was a problem hiding this comment.
I'm not sure about this one... The previous version seemed simpler and clearer to me. The updated versions is more abstract and lacks the concrete example that was present before, which illustrates the "why" pretty well.
Not sure what other maintainers think, but I'd be in favour of reverting this part. Thoughts?
There was a problem hiding this comment.
@browniebroke Thanks for the feedback — that’s fair.
My intent with the rewrite was to make the docstring more explicit about what guarantees the helper provides and why writable nested writes are intentionally unsupported, especially for readers coming to this code without prior DRF context. That said, I agree the earlier concrete example does a very good job of illustrating the ambiguity in a way that’s immediately intuitive.
I’m happy to revert this section, or alternatively reintroduce the concrete example alongside the more structured explanation if that feels like a better balance. I don’t have a strong preference either way and would defer to what maintainers feel best fits the project’s documentation style.
Let me know what you’d prefer and I’ll update the PR accordingly.
There was a problem hiding this comment.
Good suggestion. Let's re-introduce the concrete example to illustrate, and then I'm hppy to accept it.
There was a problem hiding this comment.
Thanks for your insight, could you please verify this?
Re-introduced old example mentioned
2 participants
Note: Before submitting a code change, please review our contributing guidelines.
Description
Summary
This PR adds missing docstrings to two internal helper functions in serializers.py that are central to serializer validation and error handling.
The changes are documentation-only and do not alter runtime behavior.
Details
The following docstrings were added:
as_serializer_error
Documents the function’s role in normalizing Django and DRF ValidationError instances into the serializer .errors format.
Clarifies the expected structure of field and non-field errors returned by the function.
raise_errors_on_nested_writes
Replaces inline explanatory comments with a formal docstring.
Explains why writable nested and dotted-source fields are intentionally unsupported by default.
Documents when the helper is invoked and what is expected of developers when overriding create() / update().
These helpers are frequently encountered when extending or debugging serializers, but previously lacked API-level documentation.
Motivation
Serializer error handling and nested write behavior are common sources of confusion for contributors and advanced users. Providing clear docstrings improves:
Code readability and maintainability
IDE introspection and contributor onboarding
Alignment between implementation and documented behavior
Scope
Documentation-only change
No functional or behavioral modifications
No test changes required
Checklist