docs: More specific model_post_init explanation

[santibreo]

I want to make a small but specific change to the documentation. I find the library great, but I feel a little confused when I use field validators, model validators, and model_post_init all at once. To illustrate this, I created this gist.

Because there are so many ways to hook into model instantiation, I would like to clarify their order of precedence.

[codspeed-hq]

CodSpeed Performance Report

Merging #10453 will not alter performance

_{Comparing santibreo:patch-1 (5c253e0) with main (e301d4a)}

Summary

✅ 38 untouched benchmarks

[github-actions]

Coverage report

This PR does not seem to contain any modification to coverable code.

[sydney-runkle]

Hi! Thanks for the contribution.

I believe this takes place after all validation, so perhaps it'd be better to specify that instead? Not narrow down to just field validators?

[santibreo]

Hi, thanks for your comment. As far as I discovered (you can check in the gist) the model_validator(..., mode='after')takes place after model_post_init. That was causing my confusion. I think it is a natural guess: __init__ ➡️ model validation before ➡️ field validation before ➡️ field validation after ➡️ model validation after ➡️ model post init. But the end is: ... ➡️ model_post_init ➡️ model validation after.

[sydney-runkle]

@santibreo,

Thanks for following up! Ah yes, now I recall, we inject different functional validators at different points in the core schema.

Perhaps it's best to document this pattern somewhere explicitly (in concepts/validators) maybe, rather than just a docstring update here?

[sydney-runkle]

Also, happy to accept this PR and I can work on that docs PR. Lmk if you're still interested in more docs updates here!

[santibreo]

Hi!. I agree it would be better to include a more in-depth explanation in concepts/validators. I think you can keep using this PR or you can close it linked to the new one. Either case works for me.
Thank you!

[sydney-runkle]

Going to go ahead and merge as is, I think my lingering concerns can be addressed with #8277