From 533120462df74f32f60894a4391d73b6b3da6ca2 Mon Sep 17 00:00:00 2001
From: William Schwartz <wkschwartz@gmail.com>
Date: Tue, 24 Jul 2018 13:41:08 -0500
Subject: [PATCH 1/3] Refs #5383: Document that aliasing dataclass fails

This documentation is a temporary solution. It should be altered or
removed when #5383 is fixed
---
 docs/source/additional_features.rst | 31 ++++++++++++++++++++++++++++-
 1 file changed, 30 insertions(+), 1 deletion(-)

diff --git a/docs/source/additional_features.rst b/docs/source/additional_features.rst
index f50416058089a..7cb2e5a385ea7 100644
--- a/docs/source/additional_features.rst
+++ b/docs/source/additional_features.rst
@@ -68,9 +68,38 @@ class can be used:
 For more information see `official docs <https://docs.python.org/3/library/dataclasses.html>`_
 and `PEP 557 <https://www.python.org/dev/peps/pep-0557/>`_.
 
-**Note:** Some functions in the ``dataclasses`` module, such as ``replace()`` and ``asdict()``,
+Caveats/Known Issues
+====================
+
+Some functions in the ``dataclasses`` module, such as ``replace()`` and ``asdict()``,
 have imprecise (too permissive) types. This will be fixed in future releases.
 
+Mypy does not yet recognize aliases of ``dataclasses.dataclass``, and will
+probably never recognize dynamically computed decorators. The following examples
+do **not** work:
+
+.. code-block:: python
+
+    from dataclasses import dataclass
+
+    dataclass_alias = dataclass
+    dataclass_alias2 = dataclass(order=False)
+    def dataclass_wrapper(cls):
+      return dataclass(cls)
+
+    @dataclass_alias
+    class BadlyDecoratedClass1: arg1: int
+
+    @dataclass_alias2
+    class BadlyDecoratedClass2: arg1: int
+
+    @dataclass_wrapper
+    class BadlyDecoratedClass3: arg1: int
+
+    BadlyDecoratedClass1(arg1=1) # error: Unexpected keyword argument
+    BadlyDecoratedClass2(arg1=1) # error: Unexpected keyword argument
+    BadlyDecoratedClass3(arg1=1) # error: Unexpected keyword argument
+
 .. _attrs_package:
 
 The attrs package

From dc742c89f262c4bec8dc6158b26265d74b409b76 Mon Sep 17 00:00:00 2001
From: William Schwartz <wkschwartz@gmail.com>
Date: Thu, 2 Aug 2018 09:42:36 -0500
Subject: [PATCH 2/3] Respond to code review

- Rename example classes
- Cut down on number of examples
- Add comment to each example to explain what's wrong
- Use more traditional code style
---
 docs/source/additional_features.rst | 25 +++++++++++++++----------
 1 file changed, 15 insertions(+), 10 deletions(-)

diff --git a/docs/source/additional_features.rst b/docs/source/additional_features.rst
index 7cb2e5a385ea7..940d144639c59 100644
--- a/docs/source/additional_features.rst
+++ b/docs/source/additional_features.rst
@@ -83,22 +83,27 @@ do **not** work:
     from dataclasses import dataclass
 
     dataclass_alias = dataclass
-    dataclass_alias2 = dataclass(order=False)
     def dataclass_wrapper(cls):
       return dataclass(cls)
 
     @dataclass_alias
-    class BadlyDecoratedClass1: arg1: int
-
-    @dataclass_alias2
-    class BadlyDecoratedClass2: arg1: int
+    class AliasDecorated:
+      """
+      Mypy doesn't recognize this as a dataclass because it is decorated by an
+      alias of `dataclass` rather than by `dataclass` itself.
+      """
+      arg1: int
 
     @dataclass_wrapper
-    class BadlyDecoratedClass3: arg1: int
-
-    BadlyDecoratedClass1(arg1=1) # error: Unexpected keyword argument
-    BadlyDecoratedClass2(arg1=1) # error: Unexpected keyword argument
-    BadlyDecoratedClass3(arg1=1) # error: Unexpected keyword argument
+    class DynamicallyDecoarted:
+      """
+      Mypy doesn't recognize this as a dataclass because it is decorated by a
+      function returning `dataclass` rather than by `dataclass` itself.
+      """
+      arg1: int
+
+    AliasDecorated(arg1=1) # error: Unexpected keyword argument
+    DynamicallyDecoarted(arg1=1) # error: Unexpected keyword argument
 
 .. _attrs_package:
 

From bbf7be52d0502fe7755dc2af881ae27301e691a7 Mon Sep 17 00:00:00 2001
From: William Schwartz <wkschwartz@gmail.com>
Date: Thu, 2 Aug 2018 10:41:11 -0500
Subject: [PATCH 3/3] Rename dataclass attribute for readability

---
 docs/source/additional_features.rst | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/docs/source/additional_features.rst b/docs/source/additional_features.rst
index 940d144639c59..ef4df743c3f28 100644
--- a/docs/source/additional_features.rst
+++ b/docs/source/additional_features.rst
@@ -92,7 +92,7 @@ do **not** work:
       Mypy doesn't recognize this as a dataclass because it is decorated by an
       alias of `dataclass` rather than by `dataclass` itself.
       """
-      arg1: int
+      attribute: int
 
     @dataclass_wrapper
     class DynamicallyDecoarted:
@@ -100,10 +100,10 @@ do **not** work:
       Mypy doesn't recognize this as a dataclass because it is decorated by a
       function returning `dataclass` rather than by `dataclass` itself.
       """
-      arg1: int
+      attribute: int
 
-    AliasDecorated(arg1=1) # error: Unexpected keyword argument
-    DynamicallyDecoarted(arg1=1) # error: Unexpected keyword argument
+    AliasDecorated(attribute=1) # error: Unexpected keyword argument
+    DynamicallyDecoarted(attribute=1) # error: Unexpected keyword argument
 
 .. _attrs_package: