update docs, fix for ellipsis for whole model, some more tests

docs/index.md

@@ -163,8 +163,8 @@ assert len(tracks) == 1
 *  `offset(offset: int) -> QuerySet`
 *  `count() -> int`
 *  `exists() -> bool`
-*  `fields(columns: Union[List, str]) -> QuerySet`
-*  `exclude_fields(columns: Union[List, str]) -> QuerySet`
+*  `fields(columns: Union[List, str, set, dict]) -> QuerySet`
+*  `exclude_fields(columns: Union[List, str, set, dict]) -> QuerySet`
 *  `order_by(columns:Union[List, str]) -> QuerySet`
 
 

docs/queries.md

@@ -348,20 +348,73 @@ has_sample = await Book.objects.filter(title='Sample').exists()
 
 ### fields
 
-`fields(columns: Union[List, str]) -> QuerySet`
+`fields(columns: Union[List, str, set, dict]) -> QuerySet`
 
 With `fields()` you can select subset of model columns to limit the data load.
 
-```python hl_lines="47 59 60 66"
+Given a sample data like following:
+
+```python
 --8<-- "../docs_src/queries/docs006.py"
 ```
 
+You can select specified fields by passing a `str, List[str], Set[str] or dict` with nested definition.
+
+To include related models use notation `{related_name}__{column}[__{optional_next} etc.]`.
+
+```python hl_lines="1"
+all_cars = await Car.objects.select_related('manufacturer').fields(['id', 'name', 'manufacturer__name']).all()
+for car in all_cars:
+    # excluded columns will yield None
+    assert all(getattr(car, x) is None for x in ['year', 'gearbox_type', 'gears', 'aircon_type'])
+    # included column on related models will be available, pk column is always included
+    # even if you do not include it in fields list
+    assert car.manufacturer.name == 'Toyota'
+    # also in the nested related models - you cannot exclude pk - it's always auto added
+    assert car.manufacturer.founded is None
+```
+
+`fields()` can be called several times, building up the columns to select.
+
+If you include related models into `select_related()` call but you won't specify columns for those models in fields 
+- implies a list of all fields for those nested models.
+
+```python hl_lines="1"
+all_cars = await Car.objects.select_related('manufacturer').fields('id').fields(
+    ['name']).all()
+# all fiels from company model are selected
+assert all_cars[0].manufacturer.name == 'Toyota'
+assert all_cars[0].manufacturer.founded == 1937
+```
+
 !!!warning
     Mandatory fields cannot be excluded as it will raise `ValidationError`, to exclude a field it has to be nullable.
 
+You cannot exclude mandatory model columns - `manufacturer__name` in this example.
+
+```python
+await Car.objects.select_related('manufacturer').fields(['id', 'name', 'manufacturer__founded']).all()
+# will raise pydantic ValidationError as company.name is required
+```
+
 !!!tip
     Pk column cannot be excluded - it's always auto added even if not explicitly included.
 
+You can also pass fields to include as dictionary or set.
+
+To mark a field as included in a dictionary use it's name as key and ellipsis as value.
+
+To traverse nested models use nested dictionaries.
+
+To include fields at last level instead of nested dictionary a set can be used.
+
+To include whole nested model specify model related field name and ellipsis.
+
+Below you can see examples that are equivalent:
+
+```python
+--8<-- "../docs_src/queries/docs009.py"
+```
 
 !!!note
     All methods that do not return the rows explicitly returns a QueySet instance so you can chain them together
@@ -372,11 +425,15 @@ With `fields()` you can select subset of model columns to limit the data load.
 
 ### exclude_fields
 
-`fields(columns: Union[List, str]) -> QuerySet`
+`exclude_fields(columns: Union[List, str, set, dict]) -> QuerySet`
 
 With `exclude_fields()` you can select subset of model columns that will be excluded to limit the data load.
 
-It's the oposite of `fields()` method.
+It's the opposite of `fields()` method so check documentation above to see what options are available.
+
+Especially check above how you can pass also nested dictionaries and sets as a mask to exclude fields from whole hierarchy.
+
+Below you can find few simple examples:
 
 ```python hl_lines="47 48 60 61 67"
 --8<-- "../docs_src/queries/docs008.py"