Should ModelState.field_cache be documented?

[Jaap Roes]

While writing a model method that relies on data of a related object I decided that it would be nice if this method could log a warning when it is called without the related object having been prefetched.

I came across this StackOverflow question ​https://stackoverflow.com/questions/36402129/is-there-a-way-to-check-whether-a-related-object-is-already-fetched and based on that I implemented something like the following:

def my_method(self):
    if 'related_object' not in self._state.fields_cache:
        warnings.warn(
            'Calling MyModel.my_method without prefetching the related object can inefficient '
            'Consider adding prefetch_related/select_related to the originating queryset.',
            category=RuntimeWarning,
            stacklevel=3
        )
    ...

This seems to work as intended.

Checking the docs I see that Model._state is documented (​https://docs.djangoproject.com/en/3.0/ref/models/instances/#state), but the fields_cache attribute isn't.

Can I rely on fields_cache? Should I consider it to be public but undocumented, or private with the possibility of disappearing without notice?

[Mariusz Felisiak]

IMO ModelState.field_cache is an implementation detail and shouldn't be documented. There is an internal API FieldCacheMixin with field.is_cached(instance) (see #16043) for working with the model's fields value cache which I would use for your use case, but I don't think we should document it.