Merge pull request #12 from upsidetravel/issue11_updateREADME

Update README with caveats around Union types

Author: necaris

.gitignore

@@ -72,3 +72,6 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+# PyCharm / IntelliJ
+.idea/

README.md

@@ -106,6 +106,8 @@ Please see the [Contributing Guide](./CONTRIBUTING.md). Note that you must sign
 
 ### Caveats
 
+#### Mappings
+
 Note that even though Pydantic is perfectly happy with fields that hold mappings (e.g. dictionaries), because [GraphQL's type system doesn't have them](https://graphql.org/learn/schema/) those fields can't be exported to Graphene types. For instance, this will fail with an error `Don't know how to handle mappings in Graphene`: 
 
 ``` python
@@ -132,3 +134,79 @@ class GraphQLPerson(PydanticObjectType):
     model = Person
     exclude_fields = ("pets_by_name",)
 ```
+
+#### Union types
+
+There are some caveats when using Unions. Let's take the following pydantic models as an example for this section:
+
+```python
+class EmployeeModel(pydantic.BaseModel):
+    name: str
+
+
+class ManagerModel(EmployeeModel):
+    title: str
+
+
+class DepartmentModel(pydantic.BaseModel):
+    employees: T.List[T.Union[ManagerModel, EmployeeModel]]
+```
+
+##### You have to implement the class method `is_type_of` in the graphene models
+
+To get the Union between `ManagerModel` and `EmployeeModel` to successfully resolve
+in graphene, you need to implement `is_type_of` like this:
+
+```python
+class Employee(PydanticObjectType):
+    class Meta:
+        model = EmployeeModel
+
+    @classmethod
+    def is_type_of(cls, root, info):
+        return isinstance(root, (cls, EmployeeModel))
+
+
+class Manager(PydanticObjectType):
+    class Meta:
+        model = ManagerModel
+
+    @classmethod
+    def is_type_of(cls, root, info):
+        return isinstance(root, (cls, ManagerModel))
+
+
+class Department(PydanticObjectType):
+    class Meta:
+        model = DepartmentModel
+```
+
+Otherwise GraphQL will throw an error similar to `"[GraphQLError('Abstract type
+UnionOfManagerModelEmployeeModel must resolve to an Object type at runtime for
+field Department.employees ..."`
+
+##### For unions between subclasses, you need to put the subclass first in the type annotation
+
+Looking at the `employees` field above, if you write the type annotation with Employee first,
+`employees: T.List[T.Union[EmployeeModel, ManagerModel]]`, you will not be able to query
+manager-related fields (in this case `title`). In a query containing a spread like this:
+
+```
+...on Employee {
+  name
+}
+...on Manager {
+  name
+  title
+}
+```
+
+... the objects will always resolve to being an `Employee`. This can be avoided if you put
+the subclass first in the list of annotations: `employees: T.List[T.Union[ManagerModel, EmployeeModel]]`.
+
+##### Unions between subclasses don't work in Python 3.6
+
+If a field on a model is a Union between a class and a subclass (as in our example),
+Python 3.6's typing will not preserve the Union and throws away the annotation for the subclass.
+See [this issue](https://github.com/upsidetravel/graphene-pydantic/issues/11) for more details.
+The solution at present is to use Python 3.7.

examples/departments.py

@@ -32,6 +32,10 @@ class ManagerModel(EmployeeModel):
 class DepartmentModel(pydantic.BaseModel):
     id: uuid.UUID
     name: str
+    # This will not work properly in Python 3.6. Since
+    # ManagerModel is a subclass of EmployeeModel, 3.6's
+    # typing implementation throws away the ManagerModel
+    # annotation.
     employees: T.List[T.Union[ManagerModel, EmployeeModel]]