diff options
| -rw-r--r-- | Doc/ACKS.txt | 1 | ||||
| -rw-r--r-- | Doc/c-api/slice.rst | 1 | ||||
| -rw-r--r-- | Doc/c-api/typeobj.rst | 8 | ||||
| -rw-r--r-- | Doc/extending/windows.rst | 6 | ||||
| -rw-r--r-- | Doc/glossary.rst | 26 | ||||
| -rw-r--r-- | Doc/library/collections.rst | 2 | ||||
| -rw-r--r-- | Doc/library/dbm.rst | 6 | ||||
| -rw-r--r-- | Doc/library/exceptions.rst | 18 | ||||
| -rw-r--r-- | Doc/library/socket.rst | 13 | ||||
| -rw-r--r-- | Doc/library/stdtypes.rst | 4 | ||||
| -rw-r--r-- | Doc/library/xml.dom.minidom.rst | 6 | ||||
| -rw-r--r-- | Doc/tutorial/interpreter.rst | 8 | ||||
| -rw-r--r-- | Lib/test/crashers/README | 24 | ||||
| -rwxr-xr-x | Lib/test/test_array.py | 2 | ||||
| -rw-r--r-- | Lib/tkinter/scrolledtext.py | 3 | ||||
| -rw-r--r-- | Misc/SpecialBuilds.txt | 314 |
16 files changed, 227 insertions, 215 deletions
diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt index 6154fb9..a2a10a0 100644 --- a/Doc/ACKS.txt +++ b/Doc/ACKS.txt @@ -112,6 +112,7 @@ docs@python.org), and we'll be glad to correct the problem. * Andrew M. Kuchling * Dave Kuhlman * Erno Kuusela + * Ross Lagerwall * Thomas Lamb * Detlef Lannert * Piers Lauder diff --git a/Doc/c-api/slice.rst b/Doc/c-api/slice.rst index f17915f..f33cd53 100644 --- a/Doc/c-api/slice.rst +++ b/Doc/c-api/slice.rst @@ -48,4 +48,3 @@ Slice Objects normal slices. Returns 0 on success and -1 on error with exception set. - diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst index ab55292..7aa827a 100644 --- a/Doc/c-api/typeobj.rst +++ b/Doc/c-api/typeobj.rst @@ -705,7 +705,9 @@ type objects) *must* have the :attr:`ob_size` field. This field is not inherited by subtypes (computed attributes are inherited through a different mechanism). - Docs for PyGetSetDef (XXX belong elsewhere):: + .. XXX belongs elsewhere + + Docs for PyGetSetDef:: typedef PyObject *(*getter)(PyObject *, void *); typedef int (*setter)(PyObject *, PyObject *, void *); @@ -752,7 +754,7 @@ type objects) *must* have the :attr:`ob_size` field. PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type); - XXX explain. + .. XXX explain. This field is inherited by subtypes. @@ -767,7 +769,7 @@ type objects) *must* have the :attr:`ob_size` field. This field is inherited by subtypes. - XXX explain. + .. XXX explain. .. cmember:: long PyTypeObject.tp_dictoffset diff --git a/Doc/extending/windows.rst b/Doc/extending/windows.rst index 6733666..d1d0cf7 100644 --- a/Doc/extending/windows.rst +++ b/Doc/extending/windows.rst @@ -110,7 +110,7 @@ described here are distributed with the Python sources in the Now your options are: #. Copy :file:`example.sln` and :file:`example.vcproj`, rename them to - :file:`spam.\*`, and edit them by hand, or + :file:`spam.\*`, and edit them by hand, or #. Create a brand new project; instructions are below. @@ -179,8 +179,8 @@ constant". This shows up when building DLL under MSVC. Change it to:: and add the following to the module initialization function:: - MyObject_Type.ob_type = &PyType_Type; - + if (PyType_Ready(&MyObject_Type) < 0) + return NULL; .. _dynamic-linking: diff --git a/Doc/glossary.rst b/Doc/glossary.rst index d7f2749..7431545 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -179,22 +179,22 @@ Glossary not expressions. extension module - A module written in C or C++, using Python's C API to interact with the core and - with user code. + A module written in C or C++, using Python's C API to interact with the + core and with user code. file object An object exposing a file-oriented API (with methods such as - :meth:`read()` or :meth:`write()`) to an underlying resource. - Depending on the way it was created, a file object can mediate access - to a real on-disk file or to another other type of storage or - communication device (for example standard input/output, in-memory - buffers, sockets, pipes, etc.). File objects are also called - :dfn:`file-like objects` or :dfn:`streams`. - - There are actually three categories of file objects: raw binary - files, buffered binary files and text files. Their interfaces are - defined in the :mod:`io` module. The canonical way to create a - file object is by using the :func:`open` function. + :meth:`read()` or :meth:`write()`) to an underlying resource. Depending + on the way it was created, a file object can mediate access to a real + on-disk file or to another other type of storage or communication device + (for example standard input/output, in-memory buffers, sockets, pipes, + etc.). File objects are also called :dfn:`file-like objects` or + :dfn:`streams`. + + There are actually three categories of file objects: raw binary files, + buffered binary files and text files. Their interfaces are defined in the + :mod:`io` module. The canonical way to create a file object is by using + the :func:`open` function. file-like object A synonym for :term:`file object`. diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst index e79f723..1ed96b9 100644 --- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -810,7 +810,7 @@ If a new entry overwrites an existing entry, the original insertion position is changed and moved to the end:: class LastUpdatedOrderedDict(OrderedDict): - 'Store items is the order the keys were last added' + 'Store items in the order the keys were last added' def __setitem__(self, key, value): if key in self: del self[key] diff --git a/Doc/library/dbm.rst b/Doc/library/dbm.rst index 6926ca6..c7c7347 100644 --- a/Doc/library/dbm.rst +++ b/Doc/library/dbm.rst @@ -86,10 +86,8 @@ then prints out the contents of the database:: # Notice how the value is now in bytes. assert db['www.cnn.com'] == b'Cable News Network' - # Loop through contents. Other dictionary methods - # such as .keys(), .values() also work. - for k, v in db.iteritems(): - print(k, '\t', v) + # Often-used methods of the dict interface work too. + print(db.get('python.org', b'not present')) # Storing a non-string key or value will raise an exception (most # likely a TypeError). diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst index 7ecfbca..4159287 100644 --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -77,6 +77,12 @@ The following exceptions are used mostly as base classes for other exceptions. :exc:`FloatingPointError`. +.. exception:: BufferError + + Raised when a :ref:`buffer <bufferobjects>` related operation cannot be + performed. + + .. exception:: LookupError The base class for the exceptions that are raised when a key or index used on @@ -271,6 +277,18 @@ The following exceptions are the exceptions that are usually raised. of the exception instance returns only the message. +.. exception:: IndentationError + + Base class for syntax errors related to incorrect indentation. This is a + subclass of :exc:`SyntaxError`. + + +.. exception:: TabError + + Raised when indentation contains an inconsistent use of tabs and spaces. + This is a subclass of :exc:`IndentationError`. + + .. exception:: SystemError Raised when the interpreter finds an internal error, but the situation does not diff --git a/Doc/library/socket.rst b/Doc/library/socket.rst index 1b7b1f7..d61398c 100644 --- a/Doc/library/socket.rst +++ b/Doc/library/socket.rst @@ -616,16 +616,21 @@ correspond to Unix system calls applicable to sockets. .. index:: single: I/O control; buffering - Return a :term:`file object` associated with the socket. The exact - returned type depends on the arguments given to :meth:`makefile`. These - arguments are interpreted the same way as by the built-in :func:`open` - function. + Return a :term:`file object` associated with the socket. The exact returned + type depends on the arguments given to :meth:`makefile`. These arguments are + interpreted the same way as by the built-in :func:`open` function. Closing the file object won't close the socket unless there are no remaining references to the socket. The socket must be in blocking mode; it can have a timeout, but the file object's internal buffer may end up in a inconsistent state if a timeout occurs. + .. note:: + + On Windows, the file-like object created by :meth:`makefile` cannot be + used where a file object with a file descriptor is expected, such as the + stream arguments of :meth:`subprocess.Popen`. + .. method:: socket.recv(bufsize[, flags]) diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst index 1fb736b..2e8b772 100644 --- a/Doc/library/stdtypes.rst +++ b/Doc/library/stdtypes.rst @@ -2203,6 +2203,10 @@ copying. Memory is generally interpreted as simple bytes. A tuple of integers the length of :attr:`ndim` giving the size in bytes to access each element for each dimension of the array. + .. attribute:: readonly + + A bool indicating whether the memory is read only. + .. memoryview.suboffsets isn't documented because it only seems useful for C diff --git a/Doc/library/xml.dom.minidom.rst b/Doc/library/xml.dom.minidom.rst index 98e7586..8364f35 100644 --- a/Doc/library/xml.dom.minidom.rst +++ b/Doc/library/xml.dom.minidom.rst @@ -125,7 +125,7 @@ module documentation. This section lists the differences between the API and to discard children of that node. -.. method:: Node.writexml(writer, indent="", addindent="", newl="", encoding="") +.. method:: Node.writexml(writer, indent="", addindent="", newl="") Write XML to the writer object. The writer should have a :meth:`write` method which matches that of the file object interface. The *indent* parameter is the @@ -133,8 +133,8 @@ module documentation. This section lists the differences between the API and indentation to use for subnodes of the current one. The *newl* parameter specifies the string to use to terminate newlines. - For the :class:`Document` node, an additional keyword argument *encoding* can be - used to specify the encoding field of the XML header. + For the :class:`Document` node, an additional keyword argument *encoding* can + be used to specify the encoding field of the XML header. .. method:: Node.toxml(encoding=None) diff --git a/Doc/tutorial/interpreter.rst b/Doc/tutorial/interpreter.rst index 9d376e6..94d7562 100644 --- a/Doc/tutorial/interpreter.rst +++ b/Doc/tutorial/interpreter.rst @@ -58,14 +58,6 @@ Some Python modules are also useful as scripts. These can be invoked using ``python -m module [arg] ...``, which executes the source file for *module* as if you had spelled out its full name on the command line. -Note that there is a difference between ``python file`` and ``python -<file``. In the latter case, input requests from the program, such as calling -``sys.stdin.read()``, are satisfied from *file*. Since this file has already -been read until the end by the parser before the program starts executing, the -program will encounter end-of-file immediately. In the former case (which is -usually what you want) they are satisfied from whatever file or device is -connected to standard input of the Python interpreter. - When a script file is used, it is sometimes useful to be able to run the script and enter interactive mode afterwards. This can be done by passing :option:`-i` before the script. (This does not work if the script is read from standard diff --git a/Lib/test/crashers/README b/Lib/test/crashers/README index 070c3f1..2a73e1b 100644 --- a/Lib/test/crashers/README +++ b/Lib/test/crashers/README @@ -1,20 +1,16 @@ -This directory only contains tests for outstanding bugs that cause -the interpreter to segfault. Ideally this directory should always -be empty. Sometimes it may not be easy to fix the underlying cause. +This directory only contains tests for outstanding bugs that cause the +interpreter to segfault. Ideally this directory should always be empty, but +sometimes it may not be easy to fix the underlying cause and the bug is deemed +too obscure to invest the effort. Each test should fail when run from the command line: ./python Lib/test/crashers/weakref_in_del.py -Each test should have a link to the bug report: +Put as much info into a docstring or comments to help determine the cause of the +failure, as well as a bugs.python.org issue number if it exists. Particularly +note if the cause is system or environment dependent and what the variables are. - # http://python.org/sf/BUG# - -Put as much info into a docstring or comments to help determine -the cause of the failure. Particularly note if the cause is -system or environment dependent and what the variables are. - -Once the crash is fixed, the test case should be moved into an appropriate -test (even if it was originally from the test suite). This ensures the -regression doesn't happen again. And if it does, it should be easier -to track down. +Once the crash is fixed, the test case should be moved into an appropriate test +(even if it was originally from the test suite). This ensures the regression +doesn't happen again. And if it does, it should be easier to track down. diff --git a/Lib/test/test_array.py b/Lib/test/test_array.py index 97cec11..62997d7 100755 --- a/Lib/test/test_array.py +++ b/Lib/test/test_array.py @@ -15,7 +15,7 @@ class ArraySubclass(array.array): class ArraySubclassWithKwargs(array.array): def __init__(self, typecode, newarg=None): - array.array.__init__(typecode) + array.array.__init__(self, typecode) tests = [] # list to accumulate all tests typecodes = "ubBhHiIlLfd" diff --git a/Lib/tkinter/scrolledtext.py b/Lib/tkinter/scrolledtext.py index d2a9987..d9af67c 100644 --- a/Lib/tkinter/scrolledtext.py +++ b/Lib/tkinter/scrolledtext.py @@ -39,11 +39,10 @@ class ScrolledText(Text): def example(): - import __main__ from tkinter.constants import END stext = ScrolledText(bg='white', height=10) - stext.insert(END, __main__.__doc__) + stext.insert(END, __doc__) stext.pack(fill=BOTH, side=LEFT, expand=True) stext.focus_set() stext.mainloop() diff --git a/Misc/SpecialBuilds.txt b/Misc/SpecialBuilds.txt index 25bb6d1..f869e7c 100644 --- a/Misc/SpecialBuilds.txt +++ b/Misc/SpecialBuilds.txt @@ -1,17 +1,20 @@ -This file describes some special Python build types enabled via -compile-time preprocessor defines. +This file describes some special Python build types enabled via compile-time +preprocessor defines. -It is best to define these options in the EXTRA_CFLAGS make variable; +IMPORTANT: if you want to build a debug-enabled Python, it is recommended that +you use ``./configure --with-pydebug``, rather than the options listed here. + +However, if you wish to define some of these options individually, it is best +to define them in the EXTRA_CFLAGS make variable; ``make EXTRA_CFLAGS="-DPy_REF_DEBUG"``. ---------------------------------------------------------------------------- -Py_REF_DEBUG introduced in 1.4 - named REF_DEBUG before 1.4 -Turn on aggregate reference counting. This arranges that extern -_Py_RefTotal hold a count of all references, the sum of ob_refcnt across -all objects. In a debug-mode build, this is where the "8288" comes from -in +Py_REF_DEBUG +------------ + +Turn on aggregate reference counting. This arranges that extern _Py_RefTotal +hold a count of all references, the sum of ob_refcnt across all objects. In a +debug-mode build, this is where the "8288" comes from in >>> 23 23 @@ -19,75 +22,72 @@ in >>> Note that if this count increases when you're not storing away new objects, -there's probably a leak. Remember, though, that in interactive mode the -special name "_" holds a reference to the last result displayed! +there's probably a leak. Remember, though, that in interactive mode the special +name "_" holds a reference to the last result displayed! -Py_REF_DEBUG also checks after every decref to verify that the refcount -hasn't gone negative, and causes an immediate fatal error if it has. +Py_REF_DEBUG also checks after every decref to verify that the refcount hasn't +gone negative, and causes an immediate fatal error if it has. Special gimmicks: sys.gettotalrefcount() Return current total of all refcounts. - Available under Py_REF_DEBUG in Python 2.3. - Before 2.3, Py_TRACE_REFS was required to enable this function. ---------------------------------------------------------------------------- -Py_TRACE_REFS introduced in 1.4 - named TRACE_REFS before 1.4 - -Turn on heavy reference debugging. This is major surgery. Every PyObject -grows two more pointers, to maintain a doubly-linked list of all live -heap-allocated objects. Most built-in type objects are not in this list, -as they're statically allocated. Starting in Python 2.3, if COUNT_ALLOCS -(see below) is also defined, a static type object T does appear in this -list if at least one object of type T has been created. + + +Py_TRACE_REFS +------------- + +Turn on heavy reference debugging. This is major surgery. Every PyObject grows +two more pointers, to maintain a doubly-linked list of all live heap-allocated +objects. Most built-in type objects are not in this list, as they're statically +allocated. Starting in Python 2.3, if COUNT_ALLOCS (see below) is also defined, +a static type object T does appear in this list if at least one object of type T +has been created. Note that because the fundamental PyObject layout changes, Python modules -compiled with Py_TRACE_REFS are incompatible with modules compiled without -it. +compiled with Py_TRACE_REFS are incompatible with modules compiled without it. Py_TRACE_REFS implies Py_REF_DEBUG. Special gimmicks: sys.getobjects(max[, type]) - Return list of the (no more than) max most-recently allocated objects, - most recently allocated first in the list, least-recently allocated - last in the list. max=0 means no limit on list length. - If an optional type object is passed, the list is also restricted to - objects of that type. - The return list itself, and some temp objects created just to call - sys.getobjects(), are excluded from the return list. Note that the - list returned is just another object, though, so may appear in the - return list the next time you call getobjects(); note that every - object in the list is kept alive too, simply by virtue of being in - the list. - -envar PYTHONDUMPREFS - If this envar exists, Py_Finalize() arranges to print a list of - all still-live heap objects. This is printed twice, in different - formats, before and after Py_Finalize has cleaned up everything it - can clean up. The first output block produces the repr() of each - object so is more informative; however, a lot of stuff destined to - die is still alive then. The second output block is much harder - to work with (repr() can't be invoked anymore -- the interpreter - has been torn down too far), but doesn't list any objects that will - die. The tool script combinerefs.py can be run over this to combine - the info from both output blocks. The second output block, and + Return list of the (no more than) max most-recently allocated objects, most + recently allocated first in the list, least-recently allocated last in the + list. max=0 means no limit on list length. If an optional type object is + passed, the list is also restricted to objects of that type. The return + list itself, and some temp objects created just to call sys.getobjects(), + are excluded from the return list. Note that the list returned is just + another object, though, so may appear in the return list the next time you + call getobjects(); note that every object in the list is kept alive too, + simply by virtue of being in the list. + +envvar PYTHONDUMPREFS + If this envvar exists, Py_Finalize() arranges to print a list of all + still-live heap objects. This is printed twice, in different formats, + before and after Py_Finalize has cleaned up everything it can clean up. The + first output block produces the repr() of each object so is more + informative; however, a lot of stuff destined to die is still alive then. + The second output block is much harder to work with (repr() can't be invoked + anymore -- the interpreter has been torn down too far), but doesn't list any + objects that will die. The tool script combinerefs.py can be run over this + to combine the info from both output blocks. The second output block, and combinerefs.py, were new in Python 2.3b1. ---------------------------------------------------------------------------- -PYMALLOC_DEBUG introduced in 2.3 + + +PYMALLOC_DEBUG +-------------- When pymalloc is enabled (WITH_PYMALLOC is defined), calls to the PyObject_ -memory routines are handled by Python's own small-object allocator, while -calls to the PyMem_ memory routines are directed to the system malloc/ -realloc/free. If PYMALLOC_DEBUG is also defined, calls to both PyObject_ -and PyMem_ memory routines are directed to a special debugging mode of -Python's small-object allocator. +memory routines are handled by Python's own small-object allocator, while calls +to the PyMem_ memory routines are directed to the system malloc/ realloc/free. +If PYMALLOC_DEBUG is also defined, calls to both PyObject_ and PyMem_ memory +routines are directed to a special debugging mode of Python's small-object +allocator. -This mode fills dynamically allocated memory blocks with special, -recognizable bit patterns, and adds debugging info on each end of -dynamically allocated memory blocks. The special bit patterns are: +This mode fills dynamically allocated memory blocks with special, recognizable +bit patterns, and adds debugging info on each end of dynamically allocated +memory blocks. The special bit patterns are: #define CLEANBYTE 0xCB /* clean (newly allocated) memory */ #define DEADBYTE 0xDB /* dead (newly freed) memory */ @@ -96,73 +96,70 @@ dynamically allocated memory blocks. The special bit patterns are: Strings of these bytes are unlikely to be valid addresses, floats, or 7-bit ASCII strings. -Let S = sizeof(size_t). 2*S bytes are added at each end of each block of N -bytes requested. The memory layout is like so, where p represents the -address returned by a malloc-like or realloc-like function (p[i:j] means -the slice of bytes from *(p+i) inclusive up to *(p+j) exclusive; note that -the treatment of negative indices differs from a Python slice): +Let S = sizeof(size_t). 2*S bytes are added at each end of each block of N bytes +requested. The memory layout is like so, where p represents the address +returned by a malloc-like or realloc-like function (p[i:j] means the slice of +bytes from *(p+i) inclusive up to *(p+j) exclusive; note that the treatment of +negative indices differs from a Python slice): p[-2*S:-S] - Number of bytes originally asked for. This is a size_t, big-endian - (easier to read in a memory dump). + Number of bytes originally asked for. This is a size_t, big-endian (easier + to read in a memory dump). p[-S:0] Copies of FORBIDDENBYTE. Used to catch under- writes and reads. p[0:N] The requested memory, filled with copies of CLEANBYTE, used to catch - reference to uninitialized memory. - When a realloc-like function is called requesting a larger memory - block, the new excess bytes are also filled with CLEANBYTE. - When a free-like function is called, these are overwritten with - DEADBYTE, to catch reference to freed memory. When a realloc- - like function is called requesting a smaller memory block, the excess - old bytes are also filled with DEADBYTE. + reference to uninitialized memory. When a realloc-like function is called + requesting a larger memory block, the new excess bytes are also filled with + CLEANBYTE. When a free-like function is called, these are overwritten with + DEADBYTE, to catch reference to freed memory. When a realloc- like function + is called requesting a smaller memory block, the excess old bytes are also + filled with DEADBYTE. p[N:N+S] Copies of FORBIDDENBYTE. Used to catch over- writes and reads. p[N+S:N+2*S] A serial number, incremented by 1 on each call to a malloc-like or - realloc-like function. - Big-endian size_t. - If "bad memory" is detected later, the serial number gives an - excellent way to set a breakpoint on the next run, to capture the - instant at which this block was passed out. The static function - bumpserialno() in obmalloc.c is the only place the serial number - is incremented, and exists so you can set such a breakpoint easily. - -A realloc-like or free-like function first checks that the FORBIDDENBYTEs -at each end are intact. If they've been altered, diagnostic output is -written to stderr, and the program is aborted via Py_FatalError(). The -other main failure mode is provoking a memory error when a program -reads up one of the special bit patterns and tries to use it as an address. -If you get in a debugger then and look at the object, you're likely -to see that it's entirely filled with 0xDB (meaning freed memory is -getting used) or 0xCB (meaning uninitialized memory is getting used). + realloc-like function. Big-endian size_t. If "bad memory" is detected + later, the serial number gives an excellent way to set a breakpoint on the + next run, to capture the instant at which this block was passed out. The + static function bumpserialno() in obmalloc.c is the only place the serial + number is incremented, and exists so you can set such a breakpoint easily. + +A realloc-like or free-like function first checks that the FORBIDDENBYTEs at +each end are intact. If they've been altered, diagnostic output is written to +stderr, and the program is aborted via Py_FatalError(). The other main failure +mode is provoking a memory error when a program reads up one of the special bit +patterns and tries to use it as an address. If you get in a debugger then and +look at the object, you're likely to see that it's entirely filled with 0xDB +(meaning freed memory is getting used) or 0xCB (meaning uninitialized memory is +getting used). Note that PYMALLOC_DEBUG requires WITH_PYMALLOC. Special gimmicks: -envar PYTHONMALLOCSTATS - If this envar exists, a report of pymalloc summary statistics is - printed to stderr whenever a new arena is allocated, and also - by Py_Finalize(). +envvar PYTHONMALLOCSTATS + If this envvar exists, a report of pymalloc summary statistics is printed to + stderr whenever a new arena is allocated, and also by Py_Finalize(). Changed in 2.5: The number of extra bytes allocated is 4*sizeof(size_t). Before it was 16 on all boxes, reflecting that Python couldn't make use of allocations >= 2**32 bytes even on 64-bit boxes before 2.5. ---------------------------------------------------------------------------- -Py_DEBUG introduced in 1.5 - named DEBUG before 1.5 + + +Py_DEBUG +-------- This is what is generally meant by "a debug build" of Python. -Py_DEBUG implies LLTRACE, Py_REF_DEBUG, Py_TRACE_REFS, and -PYMALLOC_DEBUG (if WITH_PYMALLOC is enabled). In addition, C -assert()s are enabled (via the C way: by not defining NDEBUG), and -some routines do additional sanity checks inside "#ifdef Py_DEBUG" -blocks. ---------------------------------------------------------------------------- -COUNT_ALLOCS introduced in 0.9.9 - partly broken in 2.2 and 2.2.1 +Py_DEBUG implies LLTRACE, Py_REF_DEBUG, Py_TRACE_REFS, and PYMALLOC_DEBUG (if +WITH_PYMALLOC is enabled). In addition, C assert()s are enabled (via the C way: +by not defining NDEBUG), and some routines do additional sanity checks inside +"#ifdef Py_DEBUG" blocks. + + +COUNT_ALLOCS +------------ Each type object grows three new members: @@ -178,84 +175,85 @@ Each type object grows three new members: */ int tp_maxalloc; -Allocation and deallocation code keeps these counts up to date. -Py_Finalize() displays a summary of the info returned by sys.getcounts() -(see below), along with assorted other special allocation counts (like -the number of tuple allocations satisfied by a tuple free-list, the number -of 1-character strings allocated, etc). +Allocation and deallocation code keeps these counts up to date. Py_Finalize() +displays a summary of the info returned by sys.getcounts() (see below), along +with assorted other special allocation counts (like the number of tuple +allocations satisfied by a tuple free-list, the number of 1-character strings +allocated, etc). Before Python 2.2, type objects were immortal, and the COUNT_ALLOCS -implementation relies on that. As of Python 2.2, heap-allocated type/ -class objects can go away. COUNT_ALLOCS can blow up in 2.2 and 2.2.1 -because of this; this was fixed in 2.2.2. Use of COUNT_ALLOCS makes -all heap-allocated type objects immortal, except for those for which no -object of that type is ever allocated. +implementation relies on that. As of Python 2.2, heap-allocated type/ class +objects can go away. COUNT_ALLOCS can blow up in 2.2 and 2.2.1 because of this; +this was fixed in 2.2.2. Use of COUNT_ALLOCS makes all heap-allocated type +objects immortal, except for those for which no object of that type is ever +allocated. Starting with Python 2.3, If Py_TRACE_REFS is also defined, COUNT_ALLOCS -arranges to ensure that the type object for each allocated object -appears in the doubly-linked list of all objects maintained by -Py_TRACE_REFS. +arranges to ensure that the type object for each allocated object appears in the +doubly-linked list of all objects maintained by Py_TRACE_REFS. Special gimmicks: sys.getcounts() - Return a list of 4-tuples, one entry for each type object for which - at least one object of that type was allocated. Each tuple is of - the form: + Return a list of 4-tuples, one entry for each type object for which at least + one object of that type was allocated. Each tuple is of the form: (tp_name, tp_allocs, tp_frees, tp_maxalloc) - Each distinct type object gets a distinct entry in this list, even - if two or more type objects have the same tp_name (in which case - there's no way to distinguish them by looking at this list). The - list is ordered by time of first object allocation: the type object - for which the first allocation of an object of that type occurred - most recently is at the front of the list. ---------------------------------------------------------------------------- -LLTRACE introduced well before 1.0 + Each distinct type object gets a distinct entry in this list, even if two or + more type objects have the same tp_name (in which case there's no way to + distinguish them by looking at this list). The list is ordered by time of + first object allocation: the type object for which the first allocation of + an object of that type occurred most recently is at the front of the list. + + +LLTRACE +------- Compile in support for Low Level TRACE-ing of the main interpreter loop. -When this preprocessor symbol is defined, before PyEval_EvalFrame -(eval_frame in 2.3 and 2.2, eval_code2 before that) executes a frame's code -it checks the frame's global namespace for a variable "__lltrace__". If -such a variable is found, mounds of information about what the interpreter -is doing are sprayed to stdout, such as every opcode and opcode argument -and values pushed onto and popped off the value stack. +When this preprocessor symbol is defined, before PyEval_EvalFrame (eval_frame in +2.3 and 2.2, eval_code2 before that) executes a frame's code it checks the +frame's global namespace for a variable "__lltrace__". If such a variable is +found, mounds of information about what the interpreter is doing are sprayed to +stdout, such as every opcode and opcode argument and values pushed onto and +popped off the value stack. Not useful very often, but very useful when needed. ---------------------------------------------------------------------------- -CALL_PROFILE introduced for Python 2.3 + +CALL_PROFILE +------------ Count the number of function calls executed. -When this symbol is defined, the ceval mainloop and helper functions -count the number of function calls made. It keeps detailed statistics -about what kind of object was called and whether the call hit any of -the special fast paths in the code. +When this symbol is defined, the ceval mainloop and helper functions count the +number of function calls made. It keeps detailed statistics about what kind of +object was called and whether the call hit any of the special fast paths in the +code. + ---------------------------------------------------------------------------- -WITH_TSC introduced for Python 2.4 +WITH_TSC +-------- -Super-lowlevel profiling of the interpreter. When enabled, the sys -module grows a new function: +Super-lowlevel profiling of the interpreter. When enabled, the sys module grows +a new function: settscdump(bool) - If true, tell the Python interpreter to dump VM measurements to - stderr. If false, turn off dump. The measurements are based on the - processor's time-stamp counter. + If true, tell the Python interpreter to dump VM measurements to stderr. If + false, turn off dump. The measurements are based on the processor's + time-stamp counter. -This build option requires a small amount of platform specific code. -Currently this code is present for linux/x86 and any PowerPC platform -that uses GCC (i.e. OS X and linux/ppc). +This build option requires a small amount of platform specific code. Currently +this code is present for linux/x86 and any PowerPC platform that uses GCC +(i.e. OS X and linux/ppc). -On the PowerPC the rate at which the time base register is incremented -is not defined by the architecture specification, so you'll need to -find the manual for your specific processor. For the 750CX, 750CXe -and 750FX (all sold as the G3) we find: +On the PowerPC the rate at which the time base register is incremented is not +defined by the architecture specification, so you'll need to find the manual for +your specific processor. For the 750CX, 750CXe and 750FX (all sold as the G3) +we find: - The time base counter is clocked at a frequency that is - one-fourth that of the bus clock. + The time base counter is clocked at a frequency that is one-fourth that of + the bus clock. This build is enabled by the --with-tsc flag to configure. |