refactor: change pydantic dataclass decorator

changes/2557-PrettyWood.md

@@ -0,0 +1,3 @@
+Refactor the whole _pydantic_ `dataclass` decorator to really act like its standard lib equivalent.
+It hence keeps `__eq__`, `__hash__`, ... and makes comparison with its non-validated version possible.
+It also fixes usage of `frozen` dataclasses in fields and usage of `default_factory` in nested dataclasses.

docs/examples/dataclasses_stdlib_run_validation.py

@@ -0,0 +1,30 @@
+import dataclasses
+
+from pydantic import ValidationError
+from pydantic.dataclasses import dataclass as pydantic_dataclass, set_validation
+
+
+@dataclasses.dataclass
+class User:
+    id: int
+    name: str
+
+
+# Enhance stdlib dataclass
+pydantic_dataclass(User)
+
+
+user1 = User(id='whatever', name='I want')
+
+# validate data of `user1`
+try:
+    user1.__pydantic_validate_values__()
+except ValidationError as e:
+    print(e)
+
+# Enforce validation
+try:
+    with set_validation(User, True):
+        User(id='whatever', name='I want')
+except ValidationError as e:
+    print(e)

docs/examples/dataclasses_stdlib_to_pydantic.py

@@ -16,20 +16,32 @@ class File(Meta):
     filename: str
 
 
-File = pydantic.dataclasses.dataclass(File)
+# `ValidatedFile` will be a proxy around `File`
+ValidatedFile = pydantic.dataclasses.dataclass(File)
 
-file = File(
+# the original dataclass is the `__dataclass__` attribute
+assert ValidatedFile.__dataclass__ is File
+
+
+validated_file = ValidatedFile(
     filename=b'thefilename',
     modified_date='2020-01-01T00:00',
     seen_count='7',
 )
-print(file)
+print(validated_file)
 
 try:
-    File(
+    ValidatedFile(
         filename=['not', 'a', 'string'],
         modified_date=None,
         seen_count=3,
     )
 except pydantic.ValidationError as e:
     print(e)
+
+# `File` is not altered and still does no validation by default
+print(File(
+    filename=['not', 'a', 'string'],
+    modified_date=None,
+    seen_count=3,
+))

docs/usage/dataclasses.md

@@ -20,7 +20,7 @@ You can use all the standard _pydantic_ field types, and the resulting dataclass
 created by the standard library `dataclass` decorator.
 
 The underlying model and its schema can be accessed through `__pydantic_model__`.
-Also, fields that require a `default_factory` can be specified by a `dataclasses.field`.
+Also, fields that require a `default_factory` can be specified by either a `pydantic.Field` or a `dataclasses.field`.
 
 ```py
 {!.tmp_examples/dataclasses_default_schema.py!}
@@ -53,12 +53,25 @@ Dataclasses attributes can be populated by tuples, dictionaries or instances of
 
 Stdlib dataclasses (nested or not) can be easily converted into _pydantic_ dataclasses by just decorating
 them with `pydantic.dataclasses.dataclass`.
+_Pydantic_ will enhance the given stdlib dataclass but won't alter the default behaviour (i.e. without validation).
+It will instead create a wrapper around it to trigger validation that will act like a plain proxy.
+The stdlib dataclass can still be accessed via the `__dataclass__` attribute (see example below).
 
 ```py
 {!.tmp_examples/dataclasses_stdlib_to_pydantic.py!}
 ```
 _(This script is complete, it should run "as is")_
 
+### Choose when to trigger validation
+
+As soon as your stdlib dataclass has been decorated with _pydantic_ dataclass decorator, magic methods have been
+added to validate input data. If you want, you can still keep using your dataclass and choose when to trigger it.
+
+```py
+{!.tmp_examples/dataclasses_stdlib_run_validation.py!}
+```
+_(This script is complete, it should run "as is")_
+
 ### Inherit from stdlib dataclasses
 
 Stdlib dataclasses (nested or not) can also be inherited and _pydantic_ will automatically validate