Update PEP 575 (#622)

pep-0575.rst

@@ -140,8 +140,8 @@ These are the relevant C structures::
         PyCFunctionDef *m_ml;     /* Description of the C function to call */
         PyObject *m_self;         /* __self__: anything, can be NULL; readonly */
         PyObject *m_module;       /* __module__: anything */
-        PyObject *m_weakreflist;  /* List of weak references */
         PyTypeObject *m_objclass; /* __objclass__: type or NULL; readonly */
+        PyObject *m_weakreflist;  /* List of weak references */
     } PyBaseFunctionObject;
 
     typedef struct {
@@ -199,11 +199,11 @@ The layout of the C structure is as follows::
 
     typedef struct {
         PyBaseFunctionObject base;
+        PyObject *func_code;        /* __code__: code */
+        PyObject *func_globals;     /* __globals__: anything; readonly */
         PyObject *func_name;        /* __name__: string */
         PyObject *func_qualname;    /* __qualname__: string */
         PyObject *func_doc;         /* __doc__: can be anything or NULL */
-        PyObject *func_code;        /* __code__: code */
-        PyObject *func_globals;     /* __globals__: anything; readonly */
         PyObject *func_defaults;    /* __defaults__: tuple or NULL */
         PyObject *func_kwdefaults;  /* __kwdefaults__: dict or NULL */
         PyObject *func_closure;     /* __closure__: tuple of cell objects or NULL; readonly */
@@ -239,15 +239,15 @@ The layout of the C structure is almost the same as ``defined_function``::
 
     typedef struct {
         PyBaseFunctionObject base;
+        PyObject *func_code;        /* __code__: code */
+        PyObject *func_globals;     /* __globals__: dict; readonly */
         PyObject *func_name;        /* __name__: string */
         PyObject *func_qualname;    /* __qualname__: string */
         PyObject *func_doc;         /* __doc__: can be anything or NULL */
-        PyObject *func_code;        /* __code__: code */
         PyObject *func_defaults;    /* __defaults__: tuple or NULL */
         PyObject *func_kwdefaults;  /* __kwdefaults__: dict or NULL */
-        PyObject *func_annotations; /* __annotations__: dict or NULL */
-        PyObject *func_globals;     /* __globals__: anything; readonly */
         PyObject *func_closure;     /* __closure__: tuple of cell objects or NULL; readonly */
+        PyObject *func_annotations; /* __annotations__: dict or NULL */
         PyObject *func_dict;        /* __dict__: dict or NULL */
         PyCFunctionDef _ml;         /* Storage for base.m_ml */
     } PyFunctionObject;
@@ -534,8 +534,8 @@ we need to prevent the ``c_*`` events for Python functions.
 This is done by not generating those events if the
 ``METH_PYTHON`` flag in ``ml_flags`` is set.
 
-User flags in PyCFunctionDef.ml_flags
-----------------------------------------
+User flags in PyCFunctionDef.ml_flags: METH_USRx
+------------------------------------------------
 
 8 consecutive bits in ``ml_flags`` are reserved for the "user",
 meaning the person or program who implemented the function.
@@ -676,6 +676,21 @@ for the various function classes discussed in this PEP.
 It also makes it easy to support existing built-in functions
 which set ``__self__`` to the module (for example, ``sys.exit.__self__`` is ``sys``).
 
+Two implementations of __doc__
+------------------------------
+
+``base_function`` does not support function docstrings.
+Instead, the classes ``builtin_function`` and ``defined_function``
+each have their own way of dealing with docstrings
+(and ``bound_method`` just takes the ``__doc__`` from the wrapped function).
+
+For ``builtin_function``, the docstring is stored (together with the text signature)
+as C string in the read-only ``ml_doc`` field of a ``PyMethodDef``.
+For ``defined_function``, the docstring is stored as a writable Python object
+and it does not actually need to be a string.
+This is done like this for backwards compatibility and because
+it looks hard to unify these two very different ways of dealing with ``__doc__``.
+
 Subclassing
 -----------
 
@@ -714,16 +729,36 @@ The application is also free to use ``METH_USR0``, ..., ``METH_USR7``
 for its own purposes,
 for example to customize the creation of special function instances.
 
-There is no obvious concrete use case,
-but given that it costs essentially nothing to have these flags,
+There is no immediate concrete use case,
+but we expect that tools which auto-generate functions or extension types
+may want to define custom flags.
+Given that it costs essentially nothing to have these flags,
 it seems like a good idea to allow it.
 
 
-Backwards Compatibility
+Backwards compatibility
 =======================
 
 While designing this PEP, great care was taken to not break
 backwards compatibility too much.
+In particular, Python code not using ``inspect`` or type checks
+should not be affected by this PEP.
+For example, ``staticmethod``, ``functools.partial`` or ``operator.methodcaller``
+do not need to change at all.
+
+Changes to types and inspect
+----------------------------
+
+The proposed changes to ``types`` and ``inspect``
+are meant to minimize changes in behaviour.
+However, it is unavoidable that some things change
+and this can cause code which uses ``types`` or ``inspect`` to break.
+In the Python standard library for example,
+changes are needed in the ``doctest`` module because of this.
+
+Also, tools which take various kinds of functions as input will need to deal
+with the new function hieararchy and the possibility of custom
+function classes.
 
 Python functions
 ----------------
@@ -755,19 +790,6 @@ was specifically designed to be backwards compatible.
 All attributes which existed before (like ``__objclass__`` and ``__self__``)
 still exist.
 
-New and changed classes
------------------------
-
-Tools which take various kinds of functions as input will need to deal
-with the new function hieararchy and the possibility of custom
-function classes.
-The proposed changes to ``types`` and ``inspect``
-are meant to minimize changes in behaviour.
-However, it is unavoidable that some things change
-and this can cause code to break.
-In the Python standard library,
-changes are needed in the ``doctest`` module because of this.
-
 New attributes
 --------------
 
@@ -783,7 +805,7 @@ method_descriptor and PyDescr_NewMethod
 
 The classes ``method_descriptor`` and the constructor ``PyDescr_NewMethod``
 are deprecated and no longer used by CPython itself.
-They are kept for backwards compatibility though.
+For now, they are kept for backwards compatibility.
 
 
 Reference Implementation