From 92602c523975495af544bd493d0bd59d15334440 Mon Sep 17 00:00:00 2001 From: Richard Si Date: Fri, 30 Jun 2023 11:47:00 -0400 Subject: [PATCH] [mypyc] Document more unsupported features & update supported features (#15524) Towards mypyc/mypyc#978. --------- Co-authored-by: Jukka Lehtosalo Co-authored-by: Alex Waygood --- mypyc/doc/differences_from_python.rst | 38 ++++++++++++++++++--------- mypyc/doc/native_classes.rst | 12 +++++++-- mypyc/doc/using_type_annotations.rst | 4 +-- 3 files changed, 38 insertions(+), 16 deletions(-) diff --git a/mypyc/doc/differences_from_python.rst b/mypyc/doc/differences_from_python.rst index 16faae60303f..f1d4d05a3a87 100644 --- a/mypyc/doc/differences_from_python.rst +++ b/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 *************************** diff --git a/mypyc/doc/native_classes.rst b/mypyc/doc/native_classes.rst index 2b4a0892b790..b2935a6f7185 100644 --- a/mypyc/doc/native_classes.rst +++ b/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[]``. + Generic native classes ---------------------- @@ -150,9 +157,10 @@ decorators can be used with native classes, however: * ``mypy_extensions.trait`` (for defining :ref:`trait types `) * ``mypy_extensions.mypyc_attr`` (see :ref:`above `) * ``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:: diff --git a/mypyc/doc/using_type_annotations.rst b/mypyc/doc/using_type_annotations.rst index f095a6717271..5bfff388e433 100644 --- a/mypyc/doc/using_type_annotations.rst +++ b/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