Clarification around usage of Union #594

somada141 · 2019-06-14T07:57:08Z

Change Summary

Adds examples of the incorrect and correct usage of Union when defining type annotations with multiple types and updated documentation. This is discussed further under #514

Checklist

Unit tests for the changes exist
Tests pass on CI and coverage remains at 100%
Documentation reflects the changes where applicable
HISTORY.rst has been updated
- if this is the first change since a release, please add a new section
- include the issue number or this pull request number #<number>
- include your github username @<whomever>

… in type annotations.

codecov · 2019-06-14T14:12:11Z

Codecov Report

Merging #594 into master will decrease coverage by 2.71%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##           master     #594      +/-   ##
==========================================
- Coverage     100%   97.28%   -2.72%     
==========================================
  Files          15       15              
  Lines        2542     2542              
  Branches      504      504              
==========================================
- Hits         2542     2473      -69     
- Misses          0       58      +58     
- Partials        0       11      +11

somada141 · 2019-06-14T14:27:56Z

@samuelcolvin please have a look when you get a chance

samuelcolvin

Can you also add an entry to HISTORY.rst, I know this isn't a code change but it's still useful in the changelog and it gets your name into contributors.

samuelcolvin · 2019-06-14T15:50:26Z

docs/index.rst

+
+(This script is complete, it should run "as is")
+
+However, as can be seen above, *pydantic* will attempt to 'match' any of the models (classes) defined under ``Union`` and will use the first one that matches. In the above example the ``id`` of ``user_03`` was defined as a ``uuid.UUID`` class (which is defined under the attribute's ``Union`` annotation) but as the ``uuid.UUID`` can be marshalled into an ``int`` it chose to match against the ``int`` type and disregarded the other types.


please hard wrap this text.

Also models (classes) can changed to types.

samuelcolvin · 2019-06-14T15:50:31Z

docs/index.rst

+
+However, as can be seen above, *pydantic* will attempt to 'match' any of the models (classes) defined under ``Union`` and will use the first one that matches. In the above example the ``id`` of ``user_03`` was defined as a ``uuid.UUID`` class (which is defined under the attribute's ``Union`` annotation) but as the ``uuid.UUID`` can be marshalled into an ``int`` it chose to match against the ``int`` type and disregarded the other types.
+
+As such, it is recommended that when defining ``Union`` annotations that the most specific model (class) is defined first and followed by less specific models (classes). In the above example, the ``UUID`` class should precede the ``int`` and ``str`` classes to preclude the unexpected representation as such:


samuelcolvin · 2019-06-14T15:52:36Z

docs/index.rst

@@ -949,6 +949,24 @@ Benchmarks were run with python 3.7.2 and the following package versions:
 * **django-restful-framework** ``v3.9.4``


+Usage of ``Union`` in Annotations and Type Order


can you move this above benchmarks.

docs/examples/union_type_correct.py

docs/examples/union_type_incorrect.py

Co-Authored-By: Samuel Colvin <samcolvin@gmail.com>

…ada141/pydantic into fix/add_union_gotcha_to_doco

somada141 · 2019-06-14T22:44:41Z

@samuelcolvin I updated HISTORY.rst but didn't set a version for the release, does the way I added to it make sense?

Add support for InitVar (pydantic#591)

…a_to_doco # Conflicts: # HISTORY.rst

somada141 · 2019-06-14T22:50:00Z

nvm realised you pushed a new version on it. updated

samuelcolvin

otherwise fine.

HISTORY.rst

docs/index.rst

Co-Authored-By: Samuel Colvin <samcolvin@gmail.com>

somada141 · 2019-06-15T12:06:20Z

@samuelcolvin updated

samuelcolvin · 2019-06-15T13:06:14Z

merged, thanks so much.

Docs will be updated on the next release.

somada141 · 2019-06-15T13:24:43Z

beautiful thanks a lot for the help @samuelcolvin

somada141 added 3 commits June 14, 2019 17:23

Added two code examples on the correct and incorrect usage of Union…

dd84cf9

… in type annotations.

Updated documentation.

4403bee

reST fix.

bc8f95f

samuelcolvin reviewed Jun 14, 2019

View reviewed changes

somada141 and others added 7 commits June 15, 2019 08:06

Update docs/examples/union_type_incorrect.py

6266d51

Co-Authored-By: Samuel Colvin <samcolvin@gmail.com>

Update docs/examples/union_type_incorrect.py

ea65e4d

Co-Authored-By: Samuel Colvin <samcolvin@gmail.com>

Update docs/examples/union_type_incorrect.py

e72d4c7

Co-Authored-By: Samuel Colvin <samcolvin@gmail.com>

Update docs/examples/union_type_correct.py

8aecb68

Co-Authored-By: Samuel Colvin <samcolvin@gmail.com>

PR comments.

5c84ef8

Merge branch 'fix/add_union_gotcha_to_doco' of https://github.com/som…

7b45ac6

…ada141/pydantic into fix/add_union_gotcha_to_doco

Updated HISTORY.rst.

157e128

somada141 and others added 2 commits June 15, 2019 08:18

Merge pull request #1 from samuelcolvin/master

0f76f9d

Add support for InitVar (pydantic#591)

Merge remote-tracking branch 'origin/master' into fix/add_union_gotch…

db413d2

…a_to_doco # Conflicts: # HISTORY.rst

samuelcolvin reviewed Jun 15, 2019

View reviewed changes

HISTORY.rst Outdated Show resolved Hide resolved

docs/index.rst Outdated Show resolved Hide resolved

docs/index.rst Outdated Show resolved Hide resolved

docs/index.rst Show resolved Hide resolved

somada141 and others added 4 commits June 15, 2019 21:34

Update docs/index.rst

9211d6a

Co-Authored-By: Samuel Colvin <samcolvin@gmail.com>

Update HISTORY.rst

c69b062

Co-Authored-By: Samuel Colvin <samcolvin@gmail.com>

Update docs/index.rst

84ab94c

Co-Authored-By: Samuel Colvin <samcolvin@gmail.com>

Update docs/index.rst

30a5e54

Co-Authored-By: Samuel Colvin <samcolvin@gmail.com>

samuelcolvin merged commit 84820bd into pydantic:master Jun 15, 2019

alexdrydew pushed a commit to alexdrydew/pydantic that referenced this pull request Dec 23, 2023

Remove warning for mutable default (pydantic#594)

493643e

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Clarification around usage of Union #594

Clarification around usage of Union #594

somada141 commented Jun 14, 2019 •

edited

codecov bot commented Jun 14, 2019 •

edited

somada141 commented Jun 14, 2019

samuelcolvin left a comment

samuelcolvin Jun 14, 2019

somada141 Jun 14, 2019

samuelcolvin Jun 14, 2019

somada141 Jun 14, 2019

samuelcolvin Jun 14, 2019

somada141 Jun 14, 2019

somada141 commented Jun 14, 2019

somada141 commented Jun 14, 2019

samuelcolvin left a comment

somada141 commented Jun 15, 2019

samuelcolvin commented Jun 15, 2019

somada141 commented Jun 15, 2019


		(This script is complete, it should run "as is")

		However, as can be seen above, pydantic will attempt to 'match' any of the models (classes) defined under ``Union`` and will use the first one that matches. In the above example the ``id`` of ``user_03`` was defined as a ``uuid.UUID`` class (which is defined under the attribute's ``Union`` annotation) but as the ``uuid.UUID`` can be marshalled into an ``int`` it chose to match against the ``int`` type and disregarded the other types.


		However, as can be seen above, pydantic will attempt to 'match' any of the models (classes) defined under ``Union`` and will use the first one that matches. In the above example the ``id`` of ``user_03`` was defined as a ``uuid.UUID`` class (which is defined under the attribute's ``Union`` annotation) but as the ``uuid.UUID`` can be marshalled into an ``int`` it chose to match against the ``int`` type and disregarded the other types.

		As such, it is recommended that when defining ``Union`` annotations that the most specific model (class) is defined first and followed by less specific models (classes). In the above example, the ``UUID`` class should precede the ``int`` and ``str`` classes to preclude the unexpected representation as such:

		@@ -949,6 +949,24 @@ Benchmarks were run with python 3.7.2 and the following package versions:
		* django-restful-framework ``v3.9.4``


		Usage of ``Union`` in Annotations and Type Order

Clarification around usage of Union #594

Clarification around usage of Union #594

Conversation

somada141 commented Jun 14, 2019 • edited

Change Summary

Checklist

codecov bot commented Jun 14, 2019 • edited

Codecov Report

somada141 commented Jun 14, 2019

samuelcolvin left a comment

Choose a reason for hiding this comment

samuelcolvin Jun 14, 2019

Choose a reason for hiding this comment

somada141 Jun 14, 2019

Choose a reason for hiding this comment

samuelcolvin Jun 14, 2019

Choose a reason for hiding this comment

somada141 Jun 14, 2019

Choose a reason for hiding this comment

samuelcolvin Jun 14, 2019

Choose a reason for hiding this comment

somada141 Jun 14, 2019

Choose a reason for hiding this comment

somada141 commented Jun 14, 2019

somada141 commented Jun 14, 2019

samuelcolvin left a comment

Choose a reason for hiding this comment

somada141 commented Jun 15, 2019

samuelcolvin commented Jun 15, 2019

somada141 commented Jun 15, 2019

somada141 commented Jun 14, 2019 •

edited

codecov bot commented Jun 14, 2019 •

edited