[mypyc] Document more unsupported features & update supported features (#15524)

Towards mypyc/mypyc#978.

---------

Co-authored-by: Jukka Lehtosalo <jukka.lehtosalo@iki.fi>
Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

Author: 3 people

mypyc/doc/differences_from_python.rst

@@ -268,19 +268,27 @@ used in compiled code, or there are some limitations. You can
 partially work around some of these limitations by running your code
 in interpreted mode.
 
-Operator overloading
-********************
+Nested classes
+**************
 
-Native classes can only use these dunder methods to override operators:
+Nested classes are not supported.
 
-* ``__eq__``
-* ``__ne__``
-* ``__getitem__``
-* ``__setitem__``
+Conditional functions or classes
+********************************
 
-.. note::
+Function and class definitions guarded by an if-statement are not supported.
+
+Dunder methods
+**************
 
-    This limitation will be lifted in the future.
+Native classes **cannot** use these dunders. If defined, they will not
+work as expected.
+
+* ``__del__``
+* ``__index__``
+* ``__getattr__``, ``__getattribute__``
+* ``__setattr__``
+* ``__delattr__``
 
 Generator expressions
 *********************
@@ -299,10 +307,16 @@ Descriptors
 Native classes can't contain arbitrary descriptors. Properties, static
 methods and class methods are supported.
 
-Stack introspection
-*******************
+Introspection
+*************
+
+Various methods of introspection may break by using mypyc. Here's an
+non-exhaustive list of what won't work:
 
-Frames of compiled functions can't be inspected using ``inspect``.
+- Instance ``__annotations__`` is usually not kept
+- Frames of compiled functions can't be inspected using ``inspect``
+- Compiled methods aren't considered methods by ``inspect.ismethod``
+- ``inspect.signature`` chokes on compiled functions
 
 Profiling hooks and tracing
 ***************************

mypyc/doc/native_classes.rst

@@ -63,6 +63,8 @@ classes:
 * ``IndexError``
 * ``LookupError``
 * ``UserWarning``
+* ``typing.NamedTuple``
+* ``enum.Enum``
 
 By default, a non-native class can't inherit a native class, and you
 can't inherit from a native class outside the compilation unit that
@@ -104,6 +106,11 @@ through an instance. Example::
     print(o.cv)  # OK (2)
     o.cv = 3  # Error!
 
+.. tip::
+
+    Constant class variables can be declared using ``typing.Final`` or
+    ``typing.Final[<type>]``.
+
 Generic native classes
 ----------------------
 
@@ -150,9 +157,10 @@ decorators can be used with native classes, however:
 * ``mypy_extensions.trait`` (for defining :ref:`trait types <trait-types>`)
 * ``mypy_extensions.mypyc_attr`` (see :ref:`above <inheritance>`)
 * ``dataclasses.dataclass``
+* ``@attr.s(auto_attribs=True)``
 
-Dataclasses have partial native support, and they aren't as efficient
-as pure native classes.
+Dataclasses and attrs classes have partial native support, and they aren't as
+efficient as pure native classes.
 
 .. note::
 

mypyc/doc/using_type_annotations.rst

@@ -194,8 +194,8 @@ Traits have some special properties:
 * You shouldn't create instances of traits (though mypyc does not
   prevent it yet).
 
-* Traits can subclass other traits, but they can't subclass non-trait
-  classes (other than ``object``).
+* Traits can subclass other traits or native classes, but the MRO must be
+  linear (just like with native classes).
 
 * Accessing methods or attributes through a trait type is somewhat
   less efficient than through a native class type, but this is much