docs: add replacement for 'ENCODER_BY_TYPE' to migration guide

[bL34cHig0]

Change Summary

I appended a work around code for replacing ENCODERS_BY_TYPE in V2 to the docs Migration Guide

Related issue number

fix #8426

Checklist

• The pull request title is a good summary of the changes - it will be used in the changelog
• Unit tests for the changes exist
• Tests pass on CI
• Documentation reflects the changes where applicable
• My PR is ready to review, please add a comment including the phrase "please review" to assign reviewers

Selected Reviewer: @davidhewitt

[codspeed-hq]

CodSpeed Performance Report

Merging #8501 will not alter performance

_{Comparing bL34cHig0:update-migration-guide (8196195) with main (2213f3c)}

Summary

✅ 10 untouched benchmarks

[bL34cHig0]

@sydney-runkle

please review my pull request and I look forward to your feedback. Thanks :)

[sydney-runkle]

@bL34cHig0,

Thanks a ton for your contribution. We're looking forward to this docs update.

Alright, looking at this more closely, I think there are a few things we should change.

First, let's add pydantic.json.ENCODERS_BY_TYPE to the list of deprecated things in V2.

This section of the existing migration guide is relevant:

• We have significantly expanded Pydantic's capabilities related to customizing serialization. In particular, we have added the @field_serializer, @model_serializer, and @computed_field decorators, which each address various shortcomings from Pydantic V1.
  • See Custom serializers for the usage docs of these new decorators.
• Due to performance overhead and implementation complexity, we have now deprecated support for specifying json_encoders in the model config. This functionality was originally added for the purpose of achieving custom serialization logic, and we think the new serialization decorators are a better choice in most common scenarios.

Thus, I think instead of the current alternative we have listed, we can probably just make a note about how you can use a custom field serializer for the given type instead.

Let me know if this makes sense and if you have any follow up questions :).

[sydney-runkle]

Also see https://docs.pydantic.dev/latest/api/config/#pydantic.config.ConfigDict.json_encoders

[bL34cHig0]

@bL34cHig0,

Thanks a ton for your contribution. We're looking forward to this docs update.

Alright, looking at this more closely, I think there are a few things we should change.

First, let's add pydantic.json.ENCODERS_BY_TYPE to the list of deprecated things in V2.

This section of the existing migration guide is relevant:

* We have significantly expanded Pydantic's capabilities related to customizing serialization. In particular, we have added the [@field_serializer](https://docs.pydantic.dev/latest/api/functional_serializers/#pydantic.functional_serializers.field_serializer), [@model_serializer](https://docs.pydantic.dev/latest/api/functional_serializers/#pydantic.functional_serializers.model_serializer), and [@computed_field](https://docs.pydantic.dev/latest/api/fields/#pydantic.fields.computed_field) decorators, which each address various shortcomings from Pydantic V1.
  
  * See [Custom serializers](https://docs.pydantic.dev/latest/concepts/serialization/#custom-serializers) for the usage docs of these new decorators.

* Due to performance overhead and implementation complexity, we have now deprecated support for specifying json_encoders in the model config. This functionality was originally added for the purpose of achieving custom serialization logic, and we think the new serialization decorators are a better choice in most common scenarios.

Thus, I think instead of the current alternative we have listed, we can probably just make a note about how you can use a custom field serializer for the given type instead.

Let me know if this makes sense and if you have any follow up questions :).

@sydney-runkle

Thanks for the feedback and I apologize for the late response.

However, I have a couple of follow up questions I'd like you to address:

• You mentioned we should make a note about how one can use a custom field serializer for the given type instead. Are you referring to the field_serializer?
• If so, do I replace the work around code with an example of how to use a custom field serializer for the given type or do I add it instead?

Thanks again :)

[sydney-runkle]

@bL34cHig0,

Thanks for your work, no need to apologize!

You mentioned we should make a note about how one can use a custom field serializer for the given type instead. Are you referring to the field_serializer?

A field serializer would work here, but I think an annotated type with a plain serializer might work even better. Here's an example of something like that.

If so, do I replace the work around code with an example of how to use a custom field serializer for the given type or do I add it instead?

Right, I'd replace the workaround code. We don't want to suggest using json_encoders, as that'll be deprecated in the future. Thus, there's no perfect equivalent in V2, but we should at least mention that ENCODER_BY_TYPE is no longer available.

[bL34cHig0]

@sydney-runkle

Thanks for clearing things up. I'll work on it.

[sydney-runkle]

One quick change request, thanks!

[sydney-runkle]

Looks good overall, but no need to change the formatting. Should be a 1 line diff. Happy to accept once you change things back 👍

[bL34cHig0]

Oh my bad, it was inadvertent. Will correct it now.

[sydney-runkle]

Looks great, thanks for adding this :)

[bL34cHig0]

Looks great, thanks for adding this :)

Don't mention it :)

I'll add a note about how one can use a custom field serializer for the given type soon. Thanks 👍