Better management of the automatic "_cls" field (#2112)

* Rename BaseQuerySet._initial_query to BaseQuerySet._cls_query

This new name more accurately reflects the purpose of the dict. It is either
empty for documents that don't use inheritance or it contains a `{"_cls": ...}`
shape query. There was nothing "initial" about it per se.

* Drop read_preference as a kwarg on BaseQuerySet.__call__/filter

It was a poor design choice to offer two different ways to do the same thing:
1. `SomeDoc.objects(foo=bar, bar=baz).read_preference(...)`
2. `SomeDoc.objects(foo=bar, bar=baz, read_preference=...)`

Option 1 is good because it's immediately obvious which part defines the query
to be used and which part defines the read preference.

Option 2 is bad because you don't immediately know whether `read_preference`
is a query kwarg or a reserved keyword with some special behavior. If you
wanted to be particularly cruel, you could even write
`SomeDoc.objects(foo=bar, read_preference=..., bar=baz)`.

THIS IS A BREAKING CHANGE. From now on you have to use the
`BaseQuerySet.read_preference(...)` method.

* Add a BaseQuerySet.clear_cls_query method + get rid of the class_check kwarg

This is similar to what the previous commit did to read preference except that
in this case we were still missing a `BaseQuerySet` method for clearing the
`_cls` query.

Now, instead of the undocumented, untested, and confusing interface:
    `ParentDoc.objects(foo=bar, bar=baz, class_check=False)`
We do:
    `ParentDoc.objects(foo=bar, bar=baz).clear_cls_query()`
This commit is contained in:
Stefan Wójcik
2019-07-03 11:07:55 +02:00
committed by GitHub
parent bbed312bdd
commit 50555ec73e
3 changed files with 80 additions and 44 deletions

View File

@@ -6,6 +6,10 @@ Changelog
Development
===========
- (Fill this out as you fix issues and develop your features).
- BREAKING CHANGE: `class_check` and `read_preference` keyword arguments are no longer available when filtering a `QuerySet`. #2112
- Instead of `Doc.objects(foo=bar, read_preference=...)` use `Doc.objects(foo=bar).read_preference(...)`.
- Instead of `Doc.objects(foo=bar, class_check=False)` use `Doc.objects(foo=bar).clear_cls_query(...)`.
- This change also renames the private `QuerySet._initial_query` attribute to `_cls_query`.
- BREAKING CHANGE: Removed the deprecated `format` param from `QuerySet.explain` #2113
- BREAKING CHANGE: Renamed `MongoEngineConnectionError` to `ConnectionFailure` #2111
- If you catch/use `MongoEngineConnectionError` in your code, you'll have to rename it.