PEP 454

pep-0454.txt

@@ -20,14 +20,15 @@ Add a new ``tracemalloc`` module to trace Python memory allocations.
 Rationale
 =========
 
-This PEP proposes to a new ``tracemalloc`` module, a debug tool to trace
-memory allocations made by Python. The module provides the following
-information:
+This PEP proposes to a new ``tracemalloc`` module. It is a debug tool to
+trace memory allocations made by Python based on API added by the PEP
+445. The module provides the following information:
 
-* Statistics on allocations per Python line number (file and line):
-  size, number, and average size of allocations
-* Compute delta between two "snapshots"
-* Location of a memory allocation: Python filename and line number
+* Statistics on Python memory allocations per Python filename and line
+  number: size, number, and average size of allocations
+* Compute differences between two snapshots of Python memory allocations
+* Location of a Python memory allocation: size in bytes, Python filename
+  and line number
 
 The ``tracemalloc`` module is different than other third-party modules
 like ``Heapy`` or ``PySizer``, because it is focused on the location of
@@ -47,32 +48,35 @@ line option.
 Functions
 ---------
 
-enable():
+``enable()`` function:
 
     Start tracing Python memory allocations.
 
-disable():
+``disable()`` function:
 
     Stop tracing Python memory allocations and stop the timer started by
     ``start_timer()``.
 
-is_enabled():
+``is_enabled()`` function:
 
     Get the status of the module: ``True`` if it is enabled, ``False``
     otherwise.
 
-get_object_trace(obj):
+``get_object_trace(obj)`` function:
 
-    Get the trace of a Python object *obj* as a namedtuple with 3 attributes:
+    Get the trace of the memory allocation of the Python object *obj*.
+    Return a namedtuple with 3 attributes if the memory allocation was
+    traced:
 
     - ``size``: size in bytes of the object
     - ``filename``: name of the Python script where the object was allocated
     - ``lineno``: line number where the object was allocated
 
-    Return ``None`` if tracemalloc did not save the location where the object
-    was allocated, for example if tracemalloc was disabled.
+    Return ``None`` if ``tracemalloc`` did not trace the memory
+    allocation, for example if ``tracemalloc`` was disabled when the
+    object was created.
 
-get_process_memory():
+``get_process_memory()`` function:
 
     Get the memory usage of the current process as a meminfo namedtuple
     with two attributes:
@@ -84,7 +88,7 @@ get_process_memory():
 
     Use the ``psutil`` module if available.
 
-start_timer(delay: int, func: callable, args: tuple=(), kwargs: dict={}):
+``start_timer(delay: int, func: callable, args: tuple=(), kwargs: dict={})`` function:
 
     Start a timer calling ``func(*args, **kwargs)`` every *delay*
     seconds.
@@ -97,10 +101,10 @@ start_timer(delay: int, func: callable, args: tuple=(), kwargs: dict={}):
     If ``start_timer()`` is called twice, previous parameters are
     replaced.  The timer has a resolution of 1 second.
 
-    `start_timer()`` is used by ``DisplayTop`` and ``TakeSnapshot`` to
+    ``start_timer()`` is used by ``DisplayTop`` and ``TakeSnapshot`` to
     run regulary a task.
 
-stop_timer():
+``stop_timer()`` function:
 
     Stop the timer started by ``start_timer()``.
 
@@ -110,15 +114,17 @@ DisplayTop class
 
 ``DisplayTop(count: int, file=sys.stdout)`` class:
 
-    Display the list of the N biggest memory allocations.
+    Display the list of the *count* biggest memory allocations into
+    *file*.
 
 ``display()`` method:
 
-    Display the top
+    Display the top once.
 
 ``start(delay: int)`` method:
 
-    Start a task using tracemalloc timer to display the top every delay seconds.
+    Start a task using ``tracemalloc`` timer to display the top every
+    *delay* seconds.
 
 ``stop()`` method:
 
@@ -132,8 +138,8 @@ DisplayTop class
 ``compare_with_previous`` attribute:
 
     If ``True``, ``display()`` compares with the previous top if
-    ``True``. If ``False``, compare with the first one (bool, default:
-    ``True``): .
+    ``True``. If ``False``, compare with the first top (bool, default:
+    ``True``).
 
 ``filename_parts`` attribute:
 
@@ -146,7 +152,8 @@ DisplayTop class
 
 ``show_count`` attribute:
 
-    If ``True``, ``display()`` shows the number of allocations (bool, default: ``True``).
+    If ``True``, ``display()`` shows the number of allocations (bool,
+    default: ``True``).
 
 ``show_lineno`` attribute:
 
@@ -169,24 +176,27 @@ Snapshot class
 
 ``Snapshot()`` class:
 
-    Snapshot of Python memory allocations. Use ``TakeSnapshot`` to
-    regulary take snapshots.
+    Snapshot of Python memory allocations.
+
+    Use ``TakeSnapshot`` to take regulary snapshots.
 
 ``create(user_data_callback=None)`` method:
 
-    Take a snapshot. If user_data_callback is specified, it must be a
+    Take a snapshot. If *user_data_callback* is specified, it must be a
     callable object returning a list of (title: str, format: str, value:
-    int). format must be "size". The list must always have the same
+    int). format must be ``'size'``. The list must always have the same
     length and the same order to be able to compute differences between
     values.
 
     Example: ``[('Video memory', 'size', 234902)]``.
 
-``filter_filenames(patterns: str|list, include: bool)`` method:
+``filter_filenames(patterns: list, include: bool)`` method:
 
-    Remove filenames not matching any pattern if include is True, or
-    remove filenames matching a pattern if include is False (exclude).
-    See fnmatch.fnmatch() for the syntax of patterns.
+    Remove filenames not matching any pattern of *patterns* if *include*
+    is ``True``, or remove filenames matching a pattern of *patterns* if
+    *include* is ``False`` (exclude).
+
+    See ``fnmatch.fnmatch()`` for the syntax of a pattern.
 
 ``write(filename)`` method:
 
@@ -224,7 +234,8 @@ TakeSnapshot class
 
 ``TakeSnapshot`` class:
 
-    Task taking snapshots of Python memory allocations: write them into files.
+    Task taking snapshots of Python memory allocations: write them into
+    files. By default, snapshots are written in the current directory.
 
 ``start(delay: int)`` method:
 
@@ -240,17 +251,19 @@ TakeSnapshot class
 
 ``filename_template`` attribute:
 
-    Template (str) to create a filename. "Variables" can be used in the
-    template:
+    Template (``str``) used to create a filename. The following
+    variables can be used in the template:
 
     * ``$pid``: identifier of the current process
     * ``$timestamp``: current date and time
     * ``$counter``: counter starting at 1 and incremented at each snapshot
 
+    The default pattern is ``'tracemalloc-$counter.pickle'``.
+
 ``user_data_callback`` attribute:
 
-    Optional callback collecting user data (callable, default: None).
-    See ``Snapshot.create()``.
+    Optional callback collecting user data (callable, default:
+    ``None``).  See ``Snapshot.create()``.
 
 
 Links
@@ -265,8 +278,6 @@ Similar projects:
 
 * `Meliae: Python Memory Usage Analyzer
   <https://pypi.python.org/pypi/meliae>`_
-* `Issue #3329: API for setting the memory allocator used by Python
-  <http://bugs.python.org/issue3329>`_
 * `Guppy-PE: umbrella package combining Heapy and GSL
   <http://guppy-pe.sourceforge.net/>`_
 * `PySizer <http://pysizer.8325.org/>`_: developed for Python 2.4