Add optional field argument to __modify_schema__

[jasujm]

Change Summary

Add optional field parameter to model.__modify_schema__() to opt in to receiving the ModelField object of the field. This makes it possible e.g. for the implementation of __modify_schema__() of generic type to know the runtime type of its subfields.

The concept is inspired by the optional parameters in validators, implemented in the pydantic.class_validators module. There are some differences:

• Only field is supported. values does not make sense in this context, since validation deals with concrete object, and this with the class itself. Model config might be supported, but is not included in this PR.
• field is Optional[ModelField] as opposed to ModelField, unlike validators. This is because the schema methods can be used on things that are not model fields, in which case None will be passed to as the field argument.
• Whereas class_validators does plenty of checks on the validator method signature before wrapping it, my implementation simply checks for the presence of field, and calls __modify_schema__() with or without the field parameter. This is because with validators there is separate prepare and execute steps, whereas __modify_schema__() is called directly when generating schema. If the signature doesn't match the expected, the error message and stack trace will be clear enough.

Related issue number

There are multiple requests for this:

• Exposing `ModelField` to `__modify_schema__()`? #2902
• FieldModel as arg to __modify_schema__ #3445
• My own hrefs project also uses generic types as model fields and needs to access the field spec to properly generate schema

Checklist

• Unit tests for the changes exist
• Tests pass on CI and coverage remains at 100% (expected to pass since actually running on CI is gate keeped)
• Documentation reflects the changes where applicable
• changes/<pull request or issue id>-<github username>.md file added describing change
  (see changes/README.md for details)
• My PR is ready to review, please add a comment including the phrase "please review" to assign reviewers

[jasujm]

The field should be Optional[ModelField] and not ModelField, since __modify_schema__() is not only called for fields. If it's called for entire model, there is no ModelField in this context.

[jasujm]

Fixed in newer revision ☝️

[jasujm]

please review

[samuelcolvin]

otherwise LGTM.

[samuelcolvin]

Suggested change

	You can also add any of the following arguments to the signature to use them in the implementation:
	* `field`: the field whose schema is customized. Type of object is `pydantic.fields.ModelField`.
	* `**kwargs`: if provided, the above argument will be provided in they `kwargs` dictionary
	`__modify_schema__` can also take a `field` argument which will have type `Optional[ModelField]`, pydantic will inspect the signature of `__modify_schema__` to determine
	whether the `field` argument should be included.

Or something. Explaining about **kwargs is overkill here I think.

Might also be worth adding an example.

[jasujm]

Simplified the documentation as suggested, and added an example

[samuelcolvin]

The test doesn't need to use a generic, so can remove the skipif

[samuelcolvin]

If there's a good reason to add a test for a generic here too, you can do that as a separate test.

[jasujm]

No there's no reason for it to be generic, so changed the test to work without them

[samuelcolvin]

Suggested change

	def __modify_schema__(cls, field_schema, field):
	def __modify_schema__(cls, field_schema, field):
	assert isinstance(field, ModelField)

[samuelcolvin]

please update

[jasujm]

Thank you for the suggestions. I updated and rebased the PR accordingly. please review

[samuelcolvin]

thanks so much.