PEP 454
* Remove GroupedStats class: replaced with a new Snapshot.statistics() method * Filter: rename include attribute to inclusive * Snapshot.group_by() now raises a ValueError when cumulative parameter is miused
This commit is contained in:
Victor Stinner
parent
bf16d73f39
commit
aa3b086113
120
pep-0454.txt
120
pep-0454.txt
|
|
@ -105,7 +105,7 @@ are ignored using a filter. Use ``clear_filters()`` to trace also these
|
|||
memory allocations.
|
||||
|
||||
|
||||
Main Functions
|
||||
Main functions
|
||||
--------------
|
||||
|
||||
``reset()`` function:
|
||||
|
|
@ -150,7 +150,7 @@ Main Functions
|
|||
See also ``disable()`` and ``enable()`` functions.
|
||||
|
||||
|
||||
Trace Functions
|
||||
Trace functions
|
||||
---------------
|
||||
|
||||
When Python allocates a memory block, ``tracemalloc`` attachs a "trace" to
|
||||
|
|
@ -235,7 +235,7 @@ has a size of 32 bytes and was allocated at ``x.py:7``, line called from line
|
|||
|
||||
|
||||
|
||||
Filter Functions
|
||||
Filter functions
|
||||
----------------
|
||||
|
||||
``add_filter(filter)`` function:
|
||||
|
|
@ -272,7 +272,7 @@ Filter Functions
|
|||
Filter
|
||||
------
|
||||
|
||||
``Filter(include: bool, filename_pattern: str, lineno: int=None, traceback: bool=False)`` class:
|
||||
``Filter(inclusive: bool, filename_pattern: str, lineno: int=None, traceback: bool=False)`` class:
|
||||
|
||||
Filter to select which memory allocations are traced. Filters can be
|
||||
used to reduce the memory usage of the ``tracemalloc`` module, which
|
||||
|
|
@ -287,14 +287,15 @@ Filter
|
|||
For example, use ``Filter(False, "<unknown>")`` to exclude empty
|
||||
tracebacks.
|
||||
|
||||
``include`` attribute:
|
||||
``inclusive`` attribute:
|
||||
|
||||
If *include* is ``True``, only trace memory blocks allocated in a
|
||||
file with a name matching ``filename_pattern`` at line number
|
||||
``lineno``.
|
||||
If *inclusive* is ``True`` (include), only trace memory blocks
|
||||
allocated in a file with a name matching ``filename_pattern`` at
|
||||
line number ``lineno``.
|
||||
|
||||
If *include* is ``False``, ignore memory blocks allocated in a file
|
||||
with a name matching ``filename_pattern`` at line number ``lineno``.
|
||||
If *inclusive* is ``False`` (exclude), ignore memory blocks
|
||||
allocated in a file with a name matching ``filename_pattern`` at
|
||||
line number ``lineno``.
|
||||
|
||||
``lineno`` attribute:
|
||||
|
||||
|
|
@ -314,61 +315,6 @@ Filter
|
|||
See the ``get_traceback_limit()`` function.
|
||||
|
||||
|
||||
GroupedStats
|
||||
------------
|
||||
|
||||
``GroupedStats(key_type: str, stats: dict, cumulative: bool)`` class:
|
||||
|
||||
Statistics of allocated memory blocks grouped by *key_type* as a
|
||||
dictionary.
|
||||
|
||||
The ``Snapshot.group_by()`` method creates a ``GroupedStats``
|
||||
instance.
|
||||
|
||||
``compare_to(old_stats: GroupedStats, sort=True)`` method:
|
||||
|
||||
Compare statistics to an older ``GroupedStats`` instance. Return a
|
||||
list of ``Statistic`` instances.
|
||||
|
||||
The result is sorted from the biggest to the smallest by
|
||||
``abs(size_diff)``, *size*, ``abs(count_diff)``, *count* and then by
|
||||
*key*. Set the *sort* parameter to ``False`` to get the list
|
||||
unsorted.
|
||||
|
||||
See also the ``statistics()`` method.
|
||||
|
||||
``statistics(sort=True)`` method:
|
||||
|
||||
Get statistics as a list of ``Statistic`` instances.
|
||||
``Statistic.size_diff`` and ``Statistic.count_diff`` attributes are
|
||||
set to zero.
|
||||
|
||||
The result is sorted from the biggest to the smallest by
|
||||
``abs(size_diff)``, *size*, ``abs(count_diff)``, *count* and then by
|
||||
*key*. Set the *sort* parameter to ``False`` to get the list
|
||||
unsorted.
|
||||
|
||||
See also the ``compare_to()`` method.
|
||||
|
||||
``cumulative`` attribute:
|
||||
|
||||
If ``True``, size and count of memory blocks of all frames of the
|
||||
traceback of a trace were cumulated, not only the most recent frame.
|
||||
|
||||
``key_type`` attribute:
|
||||
|
||||
Determine how memory allocations were grouped: see
|
||||
``Snapshot.group_by()`` for the available values.
|
||||
|
||||
``stats`` attribute:
|
||||
|
||||
Dictionary ``{key: [size: int, count: int]}`` where the type of
|
||||
*key* depends on the ``key_type`` attribute, *size* is the total
|
||||
size of memory blocks and *count* is the number of memory blocks.
|
||||
|
||||
See the ``Snapshot.group_by()`` method.
|
||||
|
||||
|
||||
Snapshot
|
||||
--------
|
||||
|
||||
|
|
@ -400,8 +346,11 @@ Snapshot
|
|||
|
||||
``group_by(key_type: str, cumulative: bool=False)`` method:
|
||||
|
||||
Group statistics by *key_type*. Return a ``GroupedStats`` instance.
|
||||
Key types:
|
||||
Get statistics as a dictionary, grouped by *key_type*. Return a
|
||||
dictionary ``{key: statistic}`` where the key type depends on
|
||||
*key_type* and *statistic* is a ``Statistic`` instance.
|
||||
|
||||
Available key types:
|
||||
|
||||
===================== ======================== ================================================
|
||||
key_type description type
|
||||
|
|
@ -413,9 +362,30 @@ Snapshot
|
|||
|
||||
If *cumulative* is ``True``, cumulate size and count of memory
|
||||
blocks of all frames of the traceback of a trace, not only the most
|
||||
recent frame. The *cumulative* parameter is set to ``False`` if
|
||||
*key_type* is ``'traceback'``, or if the ``traceback_limit``
|
||||
attribute is less than ``2``.
|
||||
recent frame.
|
||||
|
||||
The cumulative mode can only be used with key types ``'filename'``
|
||||
and ``'lineno'`` with tracebacks with at least 2 frames (see
|
||||
``traceback_limit``).
|
||||
|
||||
|
||||
``statistics(key_type: str, cumulative: bool=False, compare_to=None)`` method:
|
||||
|
||||
Get statistics as a sorted list of ``Statistic`` instances, grouped
|
||||
by *key_type*.
|
||||
|
||||
See the ``group_by()`` method for *key_type* and *cumulative*
|
||||
parameters.
|
||||
|
||||
If *compare_to* is set to a previous ``Snapshot`` instance, compute
|
||||
the differences betwen the two snapshots. Otherwise,
|
||||
``Statistic.size_diff`` and ``Statistic.count_diff`` attributes are
|
||||
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:
|
||||
|
|
@ -444,15 +414,15 @@ Statistic
|
|||
Statistic on memory allocations.
|
||||
|
||||
``size_diff`` and ``count_diff`` attributes are the difference
|
||||
between two ``GroupedStats`` instance.
|
||||
between two ``Snapshot`` instance.
|
||||
|
||||
``GroupedStats.compare_to()`` and ``GroupedStats.statistics()``
|
||||
return a list of ``Statistic`` instances.
|
||||
``Snapshot.statistics()`` returns a list of ``Statistic`` instances.
|
||||
|
||||
``key`` attribute:
|
||||
|
||||
Key identifying the statistic. The key type depends on
|
||||
``GroupedStats.key_type``, see the ``Snapshot.group_by()`` method.
|
||||
Key identifying the statistic. The key type depends on the
|
||||
*key_type* parameter of the ``Snapshot.group_by()`` or
|
||||
``Snapshot.statistics()`` method.
|
||||
|
||||
``count`` attribute:
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue