PEP 454: add frame class

Other changes:

* add the type and default value of almost all attributes
* move the "Command line options" section to the end

pep-0454.txt

@@ -57,65 +57,6 @@ following information:
   and line number
 
 
-Command line options
-====================
-
-The ``python -m tracemalloc`` command can be used to analyze and compare
-snapshots. The command takes a list of snapshot filenames and has the
-following options.
-
-``-g``, ``--group-per-file``
-
-    Group allocations per filename, instead of grouping per line number.
-
-``-n NTRACES``, ``--number NTRACES``
-
-    Number of traces displayed per top (default: 10).
-
-``--first``
-
-    Compare with the first snapshot, instead of comparing with the
-    previous snapshot.
-
-``--include PATTERN``
-
-    Only include filenames matching pattern *PATTERN*. The option can be
-    specified multiple times.
-
-    See ``fnmatch.fnmatch()`` for the syntax of patterns.
-
-``--exclude PATTERN``
-
-    Exclude filenames matching pattern *PATTERN*. The option can be
-    specified multiple times.
-
-    See ``fnmatch.fnmatch()`` for the syntax of patterns.
-
-``-S``, ``--hide-size``
-
-    Hide the size of allocations.
-
-``-C``, ``--hide-count``
-
-    Hide the number of allocations.
-
-``-A``, ``--hide-average``
-
-    Hide the average size of allocations.
-
-``-P PARTS``, ``--filename-parts=PARTS``
-
-    Number of displayed filename parts (default: 3).
-
-``--color``
-
-    Force usage of colors even if ``sys.stdout`` is not a TTY device.
-
-``--no-color``
-
-    Disable colors if ``sys.stdout`` is a TTY device.
-
-
 API
 ===
 
@@ -210,6 +151,22 @@ Functions
     Stop the timer started by ``start_timer()``.
 
 
+frame class
+-----------
+
+``frame`` class:
+
+    Trace of a Python frame.
+
+``filename`` attribute (``str``):
+
+    Python filename, ``None`` if unknown.
+
+``lineno`` attribute (``int``):
+
+    Python line number, ``None`` if unknown.
+
+
 trace class
 -----------
 
@@ -217,19 +174,19 @@ trace class
 
     This class represents debug information of an allocated memory block.
 
-``size`` attribute:
+``size`` attribute (``int``):
 
     Size in bytes of the memory block.
 
-``filename`` attribute:
+``frames`` attribute (``list``):
 
-    Name of the Python script where the memory block was allocated,
+    Traceback where the memory block was allocated as a list of
-    ``None`` if unknown.
+    ``frame`` instances (most recent first).
 
-``lineno`` attribute:
+    The list can be empty or incomplete if the tracemalloc module was
+    unable to retrieve the full traceback.
 
-    Line number where the memory block was allocated, ``None`` if
+    For efficiency, the traceback is truncated to 10 frames.
-    unknown.
 
 
 line_stat class
@@ -239,11 +196,11 @@ line_stat class
 
     Statistics on Python memory allocations of a specific line number.
 
-``size`` attribute:
+``size`` attribute (``int``):
 
     Total size in bytes of all memory blocks allocated on the line.
 
-``count`` attribute:
+``count`` attribute (``int``):
 
     Number of memory blocks allocated on the line.
 
@@ -269,45 +226,43 @@ DisplayTop class
 
     Stop the task started by the ``DisplayTop.start()`` method
 
-``color`` attribute:
+``color`` attribute (``bool``, default: ``file.isatty()``):
 
-    If ``True``, ``display()`` uses color. The default value is
+    If ``True``, ``display()`` uses color.
-    ``file.isatty()``.
 
-``compare_with_previous`` attribute:
+``compare_with_previous`` attribute (``bool``, default: ``True``):
 
-    If ``True`` (default value), ``display()`` compares with the
+    If ``True``, ``display()`` compares with the
     previous snapshot. If ``False``, compare with the first snapshot.
 
-``filename_parts`` attribute:
+``filename_parts`` attribute (``int``, default: ``3``):
 
-    Number of displayed filename parts (int, default: ``3``). Extra
+    Number of displayed filename parts. Extra parts are replaced
-    parts are replaced with ``"..."``.
+    with ``"..."``.
 
-``group_per_file`` attribute:
+``group_per_file`` attribute (``bool``, default: ``False``):
 
     If ``True``, group memory allocations per Python filename. If
-    ``False`` (default value), group allocation per Python line number.
+    ``False``, group allocation per Python line number.
 
-``show_average`` attribute:
+``show_average`` attribute (``bool``, default: ``True``):
 
-      If ``True`` (default value), ``display()`` shows the average size
+      If ``True``, ``display()`` shows the average size
       of allocations.
 
-``show_count`` attribute:
+``show_count`` attribute (``bool``, default: ``True``):
 
-    If ``True`` (default value), ``display()`` shows the number of
+    If ``True``, ``display()`` shows the number of
     allocations.
 
-``show_size`` attribute:
+``show_size`` attribute (``bool``, default: ``True``):
 
-    If ``True`` (default value), ``display()`` shows the size of
+    If ``True``, ``display()`` shows the size of
     allocations.
 
-``user_data_callback`` attribute:
+``user_data_callback`` attribute (``callable``, default: ``None``):
 
-    Optional callback collecting user data (callable, default:
+    Optional callback collecting user data.  See ``Snapshot.create()``.
-    ``None``).  See ``Snapshot.create()``.
 
 
 Snapshot class
@@ -346,27 +301,26 @@ Snapshot class
 
     Write the snapshot into a file.
 
-``pid`` attribute:
+``pid`` attribute (``int``):
 
-    Identifier of the process which created the snapshot (int).
+    Identifier of the process which created the snapshot.
 
 ``process_memory`` attribute:
 
     Result of the ``get_process_memory()`` function, can be ``None``.
 
-``stats`` attribute:
+``stats`` attribute (``dict``):
 
-    Result of the ``get_stats()`` function (dict).
+    Result of the ``get_stats()`` function.
 
-``timestamp`` attribute:
+``timestamp`` attribute (``datetime.datetime``):
 
-    Creation date and time of the snapshot, ``datetime.datetime``
+    Creation date and time of the snapshot.
-    instance.
 
-``user_data`` attribute:
+``user_data`` attribute (``list``, default: ``None``):
 
     Optional list of user data, result of *user_data_callback* in
-    ``Snapshot.create()`` (default: None).
+    ``Snapshot.create()``.
 
 
 TakeSnapshot class
@@ -389,21 +343,78 @@ TakeSnapshot class
 
     Take a snapshot.
 
-``filename_template`` attribute:
+``filename_template`` attribute (``str``,
+default: ``'tracemalloc-$counter.pickle'``):
 
-    Template (``str``) used to create a filename. The following
+    Template used to create a filename. The following variables can be
-    variables can be used in the template:
+    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 (``callable``, default: ``None``):
 
-``user_data_callback`` attribute:
+    Optional callback collecting user data.  See ``Snapshot.create()``.
 
-    Optional callback collecting user data (callable, default:
+
-    ``None``).  See ``Snapshot.create()``.
+Command line options
+====================
+
+The ``python -m tracemalloc`` command can be used to analyze and compare
+snapshots. The command takes a list of snapshot filenames and has the
+following options.
+
+``-g``, ``--group-per-file``
+
+    Group allocations per filename, instead of grouping per line number.
+
+``-n NTRACES``, ``--number NTRACES``
+
+    Number of traces displayed per top (default: 10).
+
+``--first``
+
+    Compare with the first snapshot, instead of comparing with the
+    previous snapshot.
+
+``--include PATTERN``
+
+    Only include filenames matching pattern *PATTERN*. The option can be
+    specified multiple times.
+
+    See ``fnmatch.fnmatch()`` for the syntax of patterns.
+
+``--exclude PATTERN``
+
+    Exclude filenames matching pattern *PATTERN*. The option can be
+    specified multiple times.
+
+    See ``fnmatch.fnmatch()`` for the syntax of patterns.
+
+``-S``, ``--hide-size``
+
+    Hide the size of allocations.
+
+``-C``, ``--hide-count``
+
+    Hide the number of allocations.
+
+``-A``, ``--hide-average``
+
+    Hide the average size of allocations.
+
+``-P PARTS``, ``--filename-parts=PARTS``
+
+    Number of displayed filename parts (default: 3).
+
+``--color``
+
+    Force usage of colors even if ``sys.stdout`` is not a TTY device.
+
+``--no-color``
+
+    Disable colors if ``sys.stdout`` is a TTY device.
 
 
 Links