Wrote down the invariants of some common objects whose structure is

exposed in header files.  Fixed a few comments in these headers.

As we might have expected, writing down invariants systematically exposed a
(minor) bug.  In this case, function objects have a writeable func_code
attribute, which could be set to code objects with the wrong number of
free variables.  Calling the resulting function segfaulted the interpreter.
Added a corresponding test.

1 files changed, 3 insertions, 0 deletions

diff --git a/Include/listobject.h b/Include/listobject.h
index e4867a5ed0..0999a82187 100644
--- a/Include/listobject.h
+++ b/Include/listobject.h
@@ -31,6 +31,9 @@ typedef struct {
      *     len(list) == ob_size
      *     ob_item == NULL implies ob_size == allocated == 0
      * list.sort() temporarily sets allocated to -1 to detect mutations.
+     *
+     * Items must normally not be NULL, except during construction when
+     * the list is not yet visible outside the function that builds it.
      */
     int allocated;
 } PyListObject;