Update V2 Documentation for Custom Fields / Custom Types

[ybressler]

Initial Checks

• I have searched Google & GitHub for similar requests and couldn't find anything
• I have read and followed the docs and still think this feature is missing

Description

Update the documentation for how to add / create a custom field.

I would want to do an overview of how to approach certain problems, it will span domains of annotated validators, custom classes, and core_schema stuff.

Details:

Should be an overview of the design philosophy Pydantic V2 for creating custom fields:

• When to use custom fields
• Annotated validators are easier – try to use them
  • Explain/demonstrate why they are easier
  • Explain philosophy why they are a better idea than a custom class
• How to override core schema etc
• How to write unit tests for custom types (TypeAdaptor)

Examples:

One example is, I have a date field which I want to create from either a string, date, datetime, timedelta (compute date from current timestamp), int/float (compute time delta from int). This is pretty advanced. Is possible to do with annotated field. Why would I want that vs. custom class. (There has to be a reason... I don't know why though.. Maybe customization, like, choose timedelta from int as days vs. hours).

Motivation:

There seems to be a gap between Pydantic V2's capabilities vs. what is documented.

Guidance Needed:

I can work on this ticket immediately, but need some guidance on where this info should live.

Related Stuff:

• A StackOverflow answer I wrote which dives deep into this stuff: https://stackoverflow.com/questions/77100890/pydantic-v2-custom-type-validators-with-info/77108459#77108459
• Issue raised due to gap in documented V2 philosophy for custom fields: Pydantic v2 custom types not receiving all fields in info #7448
• New functionality in validation info: Allow access to field_name and data in all validators if there is data and a field name #7542

Affected Components

• Compatibility between releases
• Data validation/parsing
• Data serialization - .model_dump() and .model_dump_json()
• JSON Schema
• Dataclasses
• Model Config
• Field Types - adding or changing a particular data type
• Function validation decorator
• Generic Models
• Other Model behaviour - model_construct(), pickling, private attributes, ORM mode
• Plugins and integration with other tools - mypy, FastAPI, python-devtools, Hypothesis, VS Code, PyCharm, etc.

[ybressler]

Please assign this issue to me.

[samuelcolvin]

See the changes coming in #7542, probably best to wait for that to land.

[ybressler]

Thoughts on addressing this now? @samuelcolvin