Add __pydantic_on_complete__() hook that is called once model is fully ready to be used

[DouweM]

Change Summary

Builds on #11759, to be merged after that.

Related issue number

Part of #11453.

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: @sydney-runkle

[codspeed-hq]

CodSpeed Performance Report

Merging #11762 will not alter performance

_{Comparing DouweM:on-complete-hook (d15bdd2) with main (bf06866)}

Summary

✅ 46 untouched benchmarks

[github-actions]

Coverage report

Click to see where and how coverage changed

File	Statements	Missing	Coverage	Coverage (new stmts)	Lines missing
pydantic
main.py
pydantic/_internal
_model_construction.py
Project Total

This report was generated by python-coverage-comment-action

[DouweM]

@Viicos Please review!

[DouweM]

I just realized we have a model_post_init hook that's called on a model after initialization/construction:

pydantic/pydantic/main.py

Lines 586 to 588 in bce81ef

	def model_post_init(self, context: Any, /) -> None:
	"""Override this method to perform additional initialization after `__init__` and `model_construct`.
	This is useful if you want to do some validation that requires the entire model to be initialized.

That one’s name can be overridden through an attribute on BaseModel:

pydantic/pydantic/main.py

Lines 191 to 192 in bce81ef

	__pydantic_post_init__: ClassVar[None | Literal['model_post_init']]
	"""The name of the post-init method for the model, if defined."""

Maybe we should follow that pattern for the new hook?

Edit: If we were creating a model instance level hook, we should probably follow that pattern. But the new hook we're implementing here is more similar to the subclass hook and related to other dunder properties we already set, so I think the current approach is acceptable.