Add literal docs (#651)

* Add literal docs

* Update history

* Incorporate feedback

* fix history

HISTORY.rst

@@ -6,6 +6,7 @@ History
 v0.31 (unreleased)
 ..................
 * fix schema generation for ``NewType`` and ``Literal``, #649 by @dmontagu
+* add documentation for Literal type, #651 by @dmontagu
 
 v0.30.1 (2019-07-15)
 ....................

docs/examples/literal1.py

@@ -0,0 +1,18 @@
+from typing_extensions import Literal
+
+from pydantic import BaseModel, ValidationError
+
+class Pie(BaseModel):
+    flavor: Literal['apple', 'pumpkin']
+
+Pie(flavor='apple')
+Pie(flavor='pumpkin')
+try:
+    Pie(flavor='cherry')
+except ValidationError as e:
+    print(str(e))
+"""
+1 validation error
+flavor
+  unexpected value; permitted: 'apple', 'pumpkin' (type=value_error.const; given=cherry; permitted=('apple', 'pumpkin'))
+"""

docs/examples/literal2.py

@@ -0,0 +1,32 @@
+from typing import ClassVar, List, Union
+
+from typing_extensions import Literal
+
+from pydantic import BaseModel, ValidationError
+
+class Cake(BaseModel):
+    kind: Literal['cake']
+    required_utensils: ClassVar[List[str]] = ['fork', 'knife']
+
+class IceCream(BaseModel):
+    kind: Literal['icecream']
+    required_utensils: ClassVar[List[str]] = ['spoon']
+
+class Meal(BaseModel):
+    dessert: Union[Cake, IceCream]
+
+print(type(Meal(dessert={'kind': 'cake'}).dessert).__name__)
+# Cake
+print(type(Meal(dessert={'kind': 'icecream'}).dessert).__name__)
+# IceCream
+try:
+    Meal(dessert={'kind': 'pie'})
+except ValidationError as e:
+    print(str(e))
+"""
+2 validation errors
+dessert -> kind
+  unexpected value; permitted: 'cake' (type=value_error.const; given=pie; permitted=('cake',))
+dessert -> kind
+  unexpected value; permitted: 'icecream' (type=value_error.const; given=pie; permitted=('icecream',))
+"""

docs/examples/literal3.py

@@ -0,0 +1,30 @@
+from typing import Optional, Union
+
+from typing_extensions import Literal
+
+from pydantic import BaseModel
+
+class Dessert(BaseModel):
+    kind: str
+
+class Pie(Dessert):
+    kind: Literal['pie']
+    flavor: Optional[str]
+
+class ApplePie(Pie):
+    flavor: Literal['apple']
+
+class PumpkinPie(Pie):
+    flavor: Literal['pumpkin']
+
+class Meal(BaseModel):
+    dessert: Union[ApplePie, PumpkinPie, Pie, Dessert]
+
+print(type(Meal(dessert={'kind': 'pie', 'flavor': 'apple'}).dessert).__name__)
+# ApplePie
+print(type(Meal(dessert={'kind': 'pie', 'flavor': 'pumpkin'}).dessert).__name__)
+# PumpkinPie
+print(type(Meal(dessert={'kind': 'pie'}).dessert).__name__)
+# Pie
+print(type(Meal(dessert={'kind': 'cake'}).dessert).__name__)
+# Dessert

docs/index.rst

@@ -654,6 +654,29 @@ against defined Json structure if it's provided.
 
 (This script is complete, it should run "as is")
 
+Literal Type
+............
+
+Pydantic supports the use of ``typing_extensions.Literal`` as a lightweight way to specify that a field
+may accept only specific literal values:
+
+.. literalinclude:: examples/literal1.py
+
+(This script is complete, it should run "as is")
+
+One benefit of this field type is that it can be used to check for equality with one or more specific values
+without needing to declare custom validators:
+
+.. literalinclude:: examples/literal2.py
+
+(This script is complete, it should run "as is")
+
+With proper ordering in an annotated ``Union``, you can use this to parse types of decreasing specificity:
+
+.. literalinclude:: examples/literal3.py
+
+(This script is complete, it should run "as is")
+
 Custom Data Types
 .................