Warnings for optional required, fix #1047

HISTORY.md

@@ -1,5 +1,8 @@
 ## v1.2 (2019-11-28)
 
+* **Possible Breaking Change:** Add support for required `Optional` with `name: Optional[AnyType] = Field(...)` 
+  and refactor `ModelField` creation to preserve `required` parameter value, #1031 by @tiangolo;
+  see [here](https://pydantic-docs.helpmanual.io/usage/models/#required-optional-fields) for details
 * Add benchmarks for `cattrs`, #513 by @sebastianmika
 * Add `exclude_none` option to `dict()` and friends, #587 by @niknetniko
 * Add benchmarks for `valideer`, #670 by @gsakkis
@@ -15,7 +18,6 @@
 * Fix `__str__` and `__repr__` inheritance for models, #1022 by @samuelcolvin
 * add testimonials section to docs, #1025 by @sullivancolin
 * Add support for `typing.Literal` for Python 3.8, #1026 by @dmontagu
-* Add support for required `Optional` with `name: Optional[AnyType] = Field(...)` and refactor `ModelField` creation to preserve `required` parameter value, #1031 by @tiangolo
 
 ## v1.1.1 (2019-11-20)
 

docs/examples/models_required_fields.py

@@ -0,0 +1,6 @@
+from pydantic import BaseModel, Field
+
+class Model(BaseModel):
+    a: int
+    b: int = ...
+    c: int = Field(...)

docs/usage/models.md

@@ -314,6 +314,11 @@ the `create_model` method to allow models to be created on the fly.
 
 Here `StaticFoobarModel` and `DynamicFoobarModel` are identical.
 
+!!! warning
+    See the note in [Required Optional Fields](#required-optional-fields) for the distinct between an ellipsis as a
+    field default and annotation only fields. 
+    See [samuelcolvin/pydantic#1047](https://github.com/samuelcolvin/pydantic/issues/1047) for more details.
+
 Fields are defined by either a tuple of the form `(<type>, <default value>)` or just a default value. The
 special key word arguments `__config__` and `__base__` can be used to customise the new model. This includes
 extending a base model with extra fields.
@@ -410,12 +415,7 @@ To declare a field as required, you may declare it using just an annotation, or
 as the value:
 
 ```py
-from pydantic import BaseModel, Field
-
-class Model(BaseModel):
-    a: int
-    b: int = ...
-    c: int = Field(...)
+{!.tmp_examples/models_required_fields.py!}
 ```
 _(This script is complete, it should run "as is")_
 
@@ -424,14 +424,24 @@ Where `Field` refers to the [field function](schema.md#field-customisation).
 Here `a`, `b` and `c` are all required. However, use of the ellipses in `b` will not work well
 with [mypy](mypy.md), and as of **v1.0** should be avoided in most cases.
 
-If you want to specify a field that can take a `None` value while still being required, you can use `Optional` with `...`:
+### Required Optional fields
+
+!!! warning
+    Since version **v1.2** annotation only nullable (`Optional[...]`, `Union[None, ...]` and `Any`) fields and nullable
+    fields with an ellipsis (`...`) as the default value, no longer mean the same thing.
+
+    In some situations this may cause **v1.2** to not be entirely backwards compatible with earlier **v1.*** releases.
+
+If you want to specify a field that can take a `None` value while still being required,
+you can use `Optional` with `...`:
 
 ```py
 {!.tmp_examples/models_required_field_optional.py!}
 ```
 _(This script is complete, it should run "as is")_
 
-In this model, `a`, `b`, and `c` can take `None` as a value. But `a` is optional, while `b` and `c` are required. `b` and `c` require a value, even if the value is `None`.
+In this model, `a`, `b`, and `c` can take `None` as a value. But `a` is optional, while `b` and `c` are required.
+`b` and `c` require a value, even if the value is `None`.
 
 ## Parsing data into a specified type