docs: clarify partial update exclude_unset

[anilsg]

First Check

• I added a very descriptive title to this issue.
• I used the GitHub search to find a similar issue and didn't find it.
• I searched the FastAPI documentation, with the integrated search.
• I already searched in Google "How to X in FastAPI" and didn't find any information.
• I already read and followed all the tutorial in the docs and didn't find an answer.
• I already checked if it is not related to FastAPI but to Pydantic.
• I already checked if it is not related to FastAPI but to Swagger UI.
• I already checked if it is not related to FastAPI but to ReDoc.

Commit to Help

• I commit to help with one of those options 👆

Example Code

# This is the diff of the PR I propose

-That would generate a `dict` with only the data that was set when creating the `item` model, excluding default values.
+Normally, the `dict` generated from the model contains values that are both set explicitly from supplied values (when the model was created),
+as well as values that were *not* supplied, but have default values defined in the model.

-Then you can use this to generate a `dict` with only the data that was set (sent in the request), omitting default values:
+You can use the `exclude_unset` parameter to suppress generation of fields that were *not* explicitly set when creating the model.
+So you can generate a `dict` which contains *only* the data that was explicitly set (sent in the request), omitting default values:

Description

docs: clarify partial update exclude_unset label:docs label:problem

I have solved the following problem and can submit a pull request for it.

The "Using Pydantic's exclude_unset parameter" section under "Partial updates with PATCH" on the "Body - Updates" page had me confused for a while: https://fastapi.tiangolo.com/tutorial/body-updates/?h=partial#using-pydantics-exclude_unset-parameter

The language says "that would generate a dict" and "then you can use this ...

The "that/then/this" implies two steps, and the reference to "this" grammatically applies to the dict that has already been generated, and so actually implies you will be generating another dict from the first dict.

This was so bizarre that I dropped it for a while but now that I've solved my problem I can see the docs are misleading here.

Call me close-minded because I'm so pedantic (hah hah) but I think many devs are like me that basically I was trusting the accuracy so much that when it was slightly wrong my brain didn't let in any alternative interpretations. And anyway, the implication of the text is actually strictly wrong.

So I do have a (somewhat more verbose) correction for this, that I have applied to a clone I pulled, and can provide a little pull request to correct it. This will also help me get the hang of tiangolo GitHub PRs, which will potentially help down the track since I may have an authorization scheme for a particular bastard Azure approach that I can submit.

This is the proposed correction. On receiving approval I will submit a PR once I've figured out that process with respect to creating branches on CLI and clicking the "new PR" button on GitHub...

-That would generate a `dict` with only the data that was set when creating the `item` model, excluding default values.
+Normally, the `dict` generated from the model contains values that are both set explicitly from supplied values (when the model was created),
+as well as values that were *not* supplied, but have default values defined in the model.

-Then you can use this to generate a `dict` with only the data that was set (sent in the request), omitting default values:
+You can use the `exclude_unset` parameter to suppress generation of fields that were *not* explicitly set when creating the model.
+So you can generate a `dict` which contains *only* the data that was explicitly set (sent in the request), omitting default values:

Operating System

Linux, Windows

Operating System Details

Unfortunately currently forced to develop on Windows but deploy to Ubuntu Linux. Hopefully we'll fix this soon.

FastAPI Version

0.88.0

Python Version

3.9.13

Additional Context

No response

[YuriiMotov]

Agree that it's a bit confusing in the docs.

Current version:

That would generate a dict with only the data that was set when creating the item model, excluding default values.

Then you can use this to generate a dict with only the data that was set (sent in the request), omitting default values:

https://fastapi.tiangolo.com/tutorial/body-updates/?h=partial#using-pydantics-exclude_unset-parameter

My suggestion (slightly modified version of @anilsg):

Normally, the dict generated from the model contains values that are both set explicitly from supplied values (when the model was created), as well as values that were not supplied, but have default values defined in the model.

You can use the exclude_unset parameter to tell Pydantic not to include fields that were not explicitly set when creating the model.
So you can generate a dict which contains only the data that was explicitly set (sent in the request), omitting default values: