Add gc header size to returned sizeof information

Doc/library/sys.rst

 
 :mod:`sys` --- System-specific parameters and functions
 =======================================================
 
 .. module:: sys
    :synopsis: Access system-specific parameters and functions.
 
 
 This module provides access to some variables used or maintained by the
 interpreter and to functions that interact strongly with the interpreter. It is
@@ skipping 391 matching lines @@
 
 
 .. function:: getrecursionlimit()
 
    Return the current value of the recursion limit, the maximum depth of the Python
    interpreter stack.  This limit prevents infinite recursion from causing an
    overflow of the C stack and crashing Python.  It can be set by
    :func:`setrecursionlimit`.
 
 
-.. function:: getsizeof(object)
+.. function:: getsizeof(object[, default][, gc_head=True])

[Martin v. Löwis, 2008/07/07 05:24:06]

I would like to reconsider the addition of the gc_head parameter. I still can't
understand why anybody would like to omit this memory usage from the size of the
object. If there is a real need for such a parameter, it can always be added
later; taking it back if not needed is more difficult.

 
    Return the size of an object in bytes. The object can be any type of
    object. All built-in objects will return correct results, but this
    does not have to hold true for third-party extensions as it is implementation
    specific.
 
-   func:`getsizeof` calls the object's __sizeof__ method and add's an additional
+   The *default* argument allows to define a value which will be returned
+   if the object type does not provide means to retrieve the size and would
+   cause a `TypeError`. 
+
+   func:`getsizeof` calls the object's __sizeof__ method and adds an additional
    garbage collector overhead if the object is managed by the garbage collector.
+   The *gc_head* argument allows to turn off the inclusion of this overhead
+   in the returned result. 
 
    .. versionadded:: 2.6
 
 
 .. function:: _getframe([depth])
 
    Return a frame object from the call stack.  If optional integer *depth* is
    given, return the frame object that many calls below the top of the stack.  If
    that is deeper than the call stack, :exc:`ValueError` is raised.  The default
    for *depth* is zero, returning the frame at the top of the call stack.
@@ skipping 401 matching lines @@
    first three characters of :const:`version`.  It is provided in the :mod:`sys`
    module for informational purposes; modifying this value has no effect on the
    registry keys used by Python. Availability: Windows.
 
 
 .. seealso::
 
    Module :mod:`site`
       This describes how to use .pth files to extend ``sys.path``.