QuerySet.annotate improvements (#398)

* QuerySet.annotate returns self-type. Attribute access falls back to Any.

- QuerySets that have an annotated model do not report errors during .filter() when called with invalid fields.
- QuerySets that have an annotated model return ordinary dict rather than TypedDict for .values()
- QuerySets that have an annotated model return Any rather than typed Tuple for .values_list()

* Fix .annotate so it reuses existing annotated types. Fixes error in typechecking Django testsuite.

* Fix self-typecheck error

* Fix flake8

* Fix case of .values/.values_list before .annotate.

* Extra ignores for Django 2.2 tests (false positives due to tests assuming QuerySet.first() won't return None)

Fix mypy self-check.

* More tests + more precise typing in case annotate called before values_list.

Cleanup tests.

* Test and fix annotate in combination with values/values_list with no params.

* Remove line that does nothing :)

* Formatting fixes

* Address code review

* Fix quoting in tests after mypy changed things

* Use Final

* Use typing_extensions.Final

* Fixes after ValuesQuerySet -> _ValuesQuerySet refactor. Still not passing tests yet.

* Fix inheritance of _ValuesQuerySet and remove unneeded type ignores.

This allows the test
"annotate_values_or_values_list_before_or_after_annotate_broadens_type"
to pass.

* Make it possible to annotate user code with "annotated models", using PEP 583 Annotated type.

* Add docs

* Make QuerySet[_T] an external alias to _QuerySet[_T, _T].

This currently has the drawback that error messages display the internal type _QuerySet, with both type arguments.

See also discussion on #661 and #608.

Fixes #635: QuerySet methods on Managers (like .all()) now return QuerySets rather than Managers.

Address code review by @sobolevn.

* Support passing TypedDicts to WithAnnotations

* Add an example of an error to README regarding WithAnnotations + TypedDict.

* Fix runtime behavior of ValuesQuerySet alias (you can't extend Any, for example).

Fix some edge case with from_queryset after QuerySet changed to be an
alias to _QuerySet. Can't make a minimal test case as this only occurred
on a large internal codebase.

* Fix issue when using from_queryset in some cases when having an argument with a type annotation on the QuerySet.

The mypy docstring on anal_type says not to call defer() after it.

README.md

@@ -179,6 +179,48 @@ def use_my_model():
   return foo.xyz # Gives an error
 ```
 
+### How do I annotate cases where I called QuerySet.annotate?
+
+Django-stubs provides a special type, `django_stubs_ext.WithAnnotations[Model]`, which indicates that the `Model` has
+been annotated, meaning it allows getting/setting extra attributes on the model instance.
+
+Optionally, you can provide a `TypedDict` of these attributes,
+e.g. `WithAnnotations[MyModel, MyTypedDict]`, to specify which annotated attributes are present.
+
+Currently, the mypy plugin can recognize that specific names were passed to `QuerySet.annotate` and
+include them in the type, but does not record the types of these attributes.
+
+The knowledge of the specific annotated fields is not yet used in creating more specific types for `QuerySet`'s
+`values`, `values_list`, or `filter` methods, however knowledge that the model was annotated _is_ used to create a
+broader type result type for `values`/`values_list`, and to allow `filter`ing on any field.
+
+```python
+from typing import TypedDict
+from django_stubs_ext import WithAnnotations
+from django.db import models
+from django.db.models.expressions import Value
+
+class MyModel(models.Model):
+    username = models.CharField(max_length=100)
+
+
+def func(m: WithAnnotations[MyModel]) -> str:
+    return m.asdf # OK, since the model is annotated as allowing any attribute
+
+func(MyModel.objects.annotate(foo=Value("")).get(id=1))  # OK
+func(MyModel.objects.get(id=1))  # Error, since this model will not allow access to any attribute
+
+
+class MyTypedDict(TypedDict):
+    foo: str
+
+def func2(m: WithAnnotations[MyModel, MyTypedDict]) -> str:
+    print(m.bar) # Error, since field "bar" is not in MyModel or MyTypedDict.
+    return m.foo # OK, since we said field "foo" was allowed
+
+func(MyModel.objects.annotate(foo=Value("")).get(id=1))  # OK
+func(MyModel.objects.annotate(bar=Value("")).get(id=1))  # Error
+```
 
 ## Related projects