PEP-0447: Start documenting the impact on introspection

pep-0447.txt

@@ -283,6 +283,43 @@ The attribute lookup cache in ``Objects/typeobject.c`` is disabled for classes
 that have a metaclass that overrides ``__getdescriptor__``, because using the
 cache might not be valid for such classes.
 
+Impact of this PEP on introspection
+-----------------------------------
+
+Use of the method introduced in this PEP can affect introspection of classes
+with a metaclass that uses a custom ``__getdescriptor__`` method. This section
+lists those changes.
+
+* ``dir`` might not show all attributes
+
+  As with a custom ``__getattribute__`` method ``dir()`` might not see all
+  (instance) attributes when using the ``__getdescriptor__()`` method to
+  dynamicly resolve attributes.
+
+  The solution for that is quite simple: classes using ``__getdescriptor__``
+  should also implement ``__dir__`` if they want full support for the builtin
+  ``dir`` function.
+
+
+* ``inspect.getattr_static`` might not show all attributes
+
+  The function ``inspect.getattr_static`` intentionally does not invoke
+  ``__getattribute__`` and descriptors to avoid invoking user code during
+  introspection with this function. The ``__getdescriptor__`` method will also
+  be ignored and is another way in which the result of ``inspect.getattr_static``
+  can be different from that of ``builtin.getattr``.
+
+* ``inspect.getmembers`` and ``inspect.get_class_attrs``
+
+  Both of these functions directly access the class __dict__ of classes along
+  the MRO, and hence can be affected by a custom ``__getdescriptor__`` method.
+
+  **TODO**: I haven't fully worked out what the impact of this is, and if there
+  are mitigations for those using either updates to these functions, or
+  additional methods that users should implement to be fully compatible with these
+  functions.
+
+
 Performance impact
 ------------------