PEP 454

* Add Trace, Traceback and Frame classes: generated on-demand read-only views
  of traces
* Add a new StatisticDiff class and add new Snapshot.compare_to() method.
  The method return a list of StatisticDiff instances and replaces the
  compare_to parameter of Snapshot.statistics()
* Remove Statistic.size_diff and Statistic.count_diff attributes
* Remove get_traces()

pep-0454.txt

@@ -161,13 +161,20 @@ Main functions
 
 ``take_snapshot()`` function:
 
-    Take a snapshot of traces of memory blocks allocated by Python using
+    Take a snapshot of traces of memory blocks allocated by Python.
-    the ``get_traces()`` function. Return a new ``Snapshot`` instance.
+    Return a new ``Snapshot`` instance.
+
+    The snapshot does not include memory blocks allocated before the
+    ``tracemalloc`` module started to trace memory allocations nor
+    memory blocks ignored by filters (see ``get_filters()``).
+
+    Tracebacks of traces are limited to ``traceback_limit`` frames. Use
+    ``set_traceback_limit()`` to store more frames.
 
     The ``tracemalloc`` module must be tracing memory allocations to
     take a snapshot, see the the ``start()`` function.
 
-    See also ``get_traces()`` and ``get_object_traceback()`` functions.
+    See also the ``get_object_traceback()`` function.
 
 
 Trace functions
@@ -175,31 +182,15 @@ Trace functions
 
 When Python allocates a memory block, ``tracemalloc`` attachs a "trace" to
 the memory block to store its size in bytes and the traceback where the
-allocation occurred.
+allocation occurred. See the ``Trace`` class.
-
-The following functions give access to these traces. A trace is a ``(size: int,
-traceback)`` tuple. *size* is the size of the memory block in bytes.
-*traceback* is a tuple of frames sorted from the most recent to the oldest
-frame, limited to ``get_traceback_limit()`` frames. A frame is
-a ``(filename: str, lineno: int)`` tuple.
-
-A traceback contains at least ``1`` frame. If the ``tracemalloc`` module
-failed to get a frame, the ``"<unknown>"`` filename and the line number ``0``
-are used. If it failed to get the traceback or if the traceback limit is ``0``,
-the traceback is ``(('<unknown>', 0),)``.
-
-Example of a trace: ``(32, (('x.py', 7), ('x.py', 11)))``.  The memory block
-has a size of 32 bytes and was allocated at ``x.py:7``, line called from line
-``x.py:11``.
 
 
 ``get_object_traceback(obj)`` function:
 
     Get the traceback where the Python object *obj* was allocated.
-    Return a tuple of ``(filename: str, lineno: int)`` tuples.
+    Return a ``Traceback`` instance, or ``None`` if the ``tracemalloc``
-
+    module is not tracing memory allocations or did not trace the
-    Return ``None`` if the ``tracemalloc`` module is not tracing memory
+    allocation of the object.
-    allocations or did not trace the allocation of the object.
 
     See also ``gc.get_referrers()`` and ``sys.getsizeof()`` functions.
 
@@ -214,30 +205,6 @@ has a size of 32 bytes and was allocated at ``x.py:7``, line called from line
     Use the ``set_traceback_limit()`` function to change the limit.
 
 
-``get_traces()`` function:
-
-    Get traces of memory blocks allocated by Python. Return a list of
-    ``(size: int, traceback: tuple)`` tuples. *traceback* is a tuple of
-    ``(filename: str, lineno: int)`` tuples.
-
-    The list of traces does not include memory blocks allocated before
-    the ``tracemalloc`` module started to trace memory allocations nor
-    memory blocks ignored by filters (see ``get_filters()``).
-
-    The list has an undefined order. Take a snapshot using
-    ``take_snapshot()`` and use the ``Snapshot.statistics()`` method to
-    get a sorted list of statistics.
-
-    Tracebacks of traces are limited to ``traceback_limit`` frames. Use
-    ``set_traceback_limit()`` to store more frames.
-
-    Return an empty list if the ``tracemalloc`` module is not tracing
-    memory allocations.
-
-    See also ``take_snapshot()`` and ``get_object_traceback()``
-    functions.
-
-
 ``set_traceback_limit(nframe: int)`` function:
 
     Set the maximum number of frames stored in the traceback of a trace.
@@ -351,10 +318,28 @@ Filter
     See the ``get_traceback_limit()`` function.
 
 
+Frame
+-----
+
+``Frame`` class:
+
+    Frame of a traceback.
+
+    The ``Traceback`` class is a sequence of ``Frame`` instances.
+
+``filename`` attribute:
+
+    Filename (``str``).
+
+``lineno`` attribute:
+
+    Line number (``int``).
+
+
 Snapshot
 --------
 
-``Snapshot(timestamp: datetime.datetime, traceback_limit: int, traces: dict=None)`` class:
+``Snapshot`` class:
 
     Snapshot of traces of memory blocks allocated by Python.
 
@@ -362,14 +347,28 @@ Snapshot
 
 ``apply_filters(filters)`` method:
 
-    Apply filters on the ``traces`` dictionary, *filters* is a list of
+    Create a new ``Snapshot`` instance with the filtered ``traces``,
-    ``Filter`` instances. Return a new ``Snapshot`` instance with the
+    *filters* is a list of ``Filter`` instances.
-    filtered traces.
 
     If *filters* is an empty list, return a new ``Snapshot`` instance
     with a copy of the traces.
 
 
+``compare_to(old_snapshot: Snapshot, group_by: str, cumulative: bool=False)`` method:
+
+    Compute the differences with an old snapshot *old_snapshot*. Get
+    statistics as a sorted list of ``StatisticDiff`` instances, grouped
+    by *group_by*.
+
+    See the ``statistics()`` method for *group_by* and *cumulative*
+    parameters.
+
+    The result is sorted from the biggest to the smallest by: absolute
+    value of ``StatisticDiff.size_diff``, ``StatisticDiff.size``,
+    absolute value of ``StatisticDiff.count_diff``, ``Statistic.count``
+    and then by ``StatisticDiff.traceback``.
+
+
 ``dump(filename)`` method:
 
     Write the snapshot into a file.
@@ -384,7 +383,7 @@ Snapshot
     See also ``dump()``.
 
 
-``statistics(group_by: str, cumulative: bool=False, compare_to=None)`` method:
+``statistics(group_by: str, cumulative: bool=False)`` method:
 
     Get statistics as a sorted list of ``Statistic`` instances, grouped
     by *group_by*:
@@ -403,15 +402,9 @@ Snapshot
     ``'filename'`` and ``'lineno'`` with ``traceback_limit`` greater
     than ``1``.
 
-    If *compare_to* is set to a previous ``Snapshot`` instance, compute
+    The result is sorted from the biggest to the smallest by:
-    the differences betwen the two snapshots. Otherwise,
+    ``Statistic.size``, ``Statistic.count`` and then by
-    ``Statistic.size_diff`` and ``Statistic.count_diff`` attributes are
+    ``Statistic.traceback``.
-    set to zero.
-
-    The result is sorted from the biggest to the smallest by: absolute
-    value of ``Statistic.size_diff``, ``Statistic.size``, absolute value
-    of ``Statistic.count_diff``, ``Statistic.count`` and then by
-    ``Statistic.key``.
 
 
 ``traceback_limit`` attribute:
@@ -421,8 +414,11 @@ Snapshot
 
 ``traces`` attribute:
 
-    Traces of all memory blocks allocated by Python: see the
+    Traces of all memory blocks allocated by Python: sequence of
-    ``get_traces()`` function.
+    ``Trace`` instances.
+
+    The sequence has an undefined order. Use the
+    ``Snapshot.statistics()`` method to get a sorted list of statistics.
 
 ``timestamp`` attribute:
 
@@ -433,7 +429,7 @@ Snapshot
 Statistic
 ---------
 
-``Statistic(key, size, size_diff, count, count_diff)`` class:
+``Statistic`` class:
 
     Statistic on memory allocations.
 
@@ -442,25 +438,101 @@ Statistic
 
     ``Snapshot.statistics()`` returns a list of ``Statistic`` instances.
 
-``traceback`` attribute:
+    See also the ``StatisticDiff`` class.
-
-    Tuple of ``(filename: str, lineno: int)`` tuples.
 
 ``count`` attribute:
 
     Number of memory blocks (``int``).
 
-``count_diff`` attribute:
-
-    Difference of number of memory blocks (``int``).
-
 ``size`` attribute:
 
     Total size of memory blocks in bytes (``int``).
 
+``traceback`` attribute:
+
+    Traceback where the memory block was allocated, ``Traceback``
+    instance.
+
+
+StatisticDiff
+-------------
+
+``StatisticDiff`` class:
+
+    Statistic difference on memory allocations between an old and a new
+    ``Snapshot`` instance.
+
+    ``Snapshot.compare_to()`` returns a list of ``StatisticDiff``
+    instances. See also the ``Statistic`` class.
+
+``count`` attribute:
+
+    Number of memory blocks in the new snapshot (``int``): ``0`` if the
+    memory blocks have been released in the new snapshot.
+
+``count_diff`` attribute:
+
+    Difference of number of memory blocks between the old and the new
+    snapshots (``int``): ``0`` if the memory blocks have been allocated
+    in the new snapshot.
+
+``size`` attribute:
+
+    Total size of memory blocks in bytes in the new snapshot (``int``):
+    ``0`` if the memory blocks have been released in the new snapshot.
+
 ``size_diff`` attribute:
 
-    Difference of total size of memory blocks in bytes (``int``).
+    Difference of total size of memory blocks in bytes between the old
+    and the new snapshots (``int``): ``0`` if the memory blocks have
+    been allocated in the new snapshot.
+
+``traceback`` attribute:
+
+    Traceback where the memory blocks were allocated, ``Traceback``
+    instance.
+
+
+Trace
+-----
+
+``Trace`` class:
+
+    Trace of a memory block.
+
+    The ``Snapshot.traces`` attribute is a sequence of ``Trace``
+    instances.
+
+``size`` attribute:
+
+    Size of the memory block in bytes (``int``).
+
+``traceback`` attribute:
+
+    Traceback where the memory block was allocated, ``Traceback``
+    instance.
+
+
+Traceback
+---------
+
+``Traceback`` class:
+
+    Sequence of ``Frame`` instances sorted from the most recent frame to
+    the oldest frame.
+
+    A traceback contains at least ``1`` frame. If the ``tracemalloc``
+    module failed to get a frame, the filename ``"<unknown>"`` and the
+    line number ``0`` are used. If it failed to get the traceback or if
+    the traceback limit is ``0``, the traceback only contains a frame:
+    filename ``'<unknown>'`` and line number ``0``.
+
+    When a snapshot is taken, tracebacks of traces are limited to
+    ``get_traceback_limit()`` frames. See the ``take_snapshot()``
+    function.
+
+    The ``Trace.traceback`` attribute is an instance of ``Traceback``
+    instance.
 
 
 Rejected Alternatives