PEP 454
* replace Snapshot.create() class method with take_snapshot() function
* get_traces() now returns a list instead of a dict (remove addresses)
* remove get_stats()
* unknown frames are now stored as ("<unknown>", 0) instead of (None, None)
* remove get_object_address()
* remove get_trace()
* remove add_inclusive_filter() and add_exclusive_filter() functions
* remove "address" key type from Snapshot.group_by()
This commit is contained in:
Victor Stinner
parent
52967be17a
commit
98900f22d2
206
pep-0454.txt
206
pep-0454.txt
|
|
@ -110,15 +110,15 @@ Main Functions
|
|||
|
||||
``reset()`` function:
|
||||
|
||||
Clear traces and statistics on Python memory allocations.
|
||||
Clear traces of memory blocks allocated by Python.
|
||||
|
||||
See also ``disable()``.
|
||||
|
||||
|
||||
``disable()`` function:
|
||||
|
||||
Stop tracing Python memory allocations and clear traces and
|
||||
statistics.
|
||||
Stop tracing Python memory allocations and clear traces of memory
|
||||
blocks allocated by Python.
|
||||
|
||||
See also ``enable()`` and ``is_enabled()`` functions.
|
||||
|
||||
|
|
@ -130,23 +130,6 @@ Main Functions
|
|||
See also ``disable()`` and ``is_enabled()`` functions.
|
||||
|
||||
|
||||
``get_stats()`` function:
|
||||
|
||||
Get statistics on traced Python memory blocks as a dictionary
|
||||
``{filename (str): {line_number (int): stats}}`` where *stats* in a
|
||||
``(size: int, count: int)`` tuple, *filename* and *line_number* can
|
||||
be ``None``.
|
||||
|
||||
*size* is the total size in bytes of all memory blocks allocated on
|
||||
the line, or *count* is the number of memory blocks allocated on the
|
||||
line.
|
||||
|
||||
Return an empty dictionary if the ``tracemalloc`` module is
|
||||
disabled.
|
||||
|
||||
See also the ``get_traces()`` function.
|
||||
|
||||
|
||||
``get_traced_memory()`` function:
|
||||
|
||||
Get the current size and maximum size of memory blocks traced by the
|
||||
|
|
@ -178,58 +161,25 @@ 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 where *filename* and *lineno* can be
|
||||
``None``.
|
||||
a ``(filename: str, lineno: int)`` tuple.
|
||||
|
||||
If ``tracemalloc`` failed to get the whole traceback, the traceback may be
|
||||
empty, truncated or contain ``"<unknown>"`` filename and line number 0.
|
||||
|
||||
Example of 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_address(obj)`` function:
|
||||
|
||||
Get the address of the main memory block of the specified Python
|
||||
object.
|
||||
|
||||
A Python object can be composed by multiple memory blocks, the
|
||||
function only returns the address of the main memory block. For
|
||||
example, items of ``dict`` and ``set`` containers are stored in a
|
||||
second memory block.
|
||||
|
||||
See also ``get_object_traceback()`` and ``gc.get_referrers()``
|
||||
functions.
|
||||
|
||||
.. note::
|
||||
|
||||
The builtin function ``id()`` returns a different address for
|
||||
objects tracked by the garbage collector, because ``id()``
|
||||
returns the address after the garbage collector header.
|
||||
|
||||
|
||||
``get_object_traceback(obj)`` function:
|
||||
|
||||
Get the traceback where the Python object *obj* was allocated.
|
||||
Return a tuple of ``(filename: str, lineno: int)`` tuples,
|
||||
*filename* and *lineno* can be ``None``.
|
||||
Return a tuple of ``(filename: str, lineno: int)`` tuples.
|
||||
|
||||
Return ``None`` if the ``tracemalloc`` module did not trace the
|
||||
allocation of the object.
|
||||
Return ``None`` if the ``tracemalloc`` module is disabled or did not
|
||||
trace the allocation of the object.
|
||||
|
||||
See also ``get_object_address()``, ``gc.get_referrers()`` and
|
||||
``sys.getsizeof()`` functions.
|
||||
|
||||
|
||||
``get_trace(address)`` function:
|
||||
|
||||
Get the trace of a memory block allocated by Python. Return a tuple:
|
||||
``(size: int, traceback)``, *traceback* is a tuple of ``(filename:
|
||||
str, lineno: int)`` tuples, *filename* and *lineno* can be ``None``.
|
||||
|
||||
Return ``None`` if the ``tracemalloc`` module did not trace the
|
||||
allocation of the memory block.
|
||||
|
||||
See also ``get_object_traceback()``, ``get_stats()`` and
|
||||
``get_traces()`` functions.
|
||||
See also ``gc.get_referrers()`` and ``sys.getsizeof()`` functions.
|
||||
|
||||
|
||||
``get_traceback_limit()`` function:
|
||||
|
|
@ -237,24 +187,20 @@ a size of 32 bytes and was allocated at ``x.py:7``, line called from line
|
|||
Get the maximum number of frames stored in the traceback of a trace.
|
||||
|
||||
By default, a trace of an allocated memory block only stores the
|
||||
most recent frame: the limit is ``1``. This limit is enough to get
|
||||
statistics using ``get_stats()``.
|
||||
most recent frame: the limit is ``1``.
|
||||
|
||||
Use the ``set_traceback_limit()`` function to change the limit.
|
||||
|
||||
|
||||
``get_traces()`` function:
|
||||
|
||||
Get traces of all memory blocks allocated by Python. Return a
|
||||
dictionary: ``{address (int): trace}``, *trace* is a ``(size: int,
|
||||
traceback)`` tuple, *traceback* is a tuple of ``(filename: str,
|
||||
lineno: int)`` tuples, *filename* and *lineno* can be None.
|
||||
Get traces of all memory blocks allocated by Python. Return a list
|
||||
of ``(size: int, traceback: tuple)`` tuples. *traceback* is a tuple
|
||||
of ``(filename: str, lineno: int)`` tuples.
|
||||
|
||||
Return an empty dictionary if the ``tracemalloc`` module is
|
||||
disabled.
|
||||
Return an empty list if the ``tracemalloc`` module is disabled.
|
||||
|
||||
See also ``get_object_traceback()``, ``get_stats()`` and
|
||||
``get_trace()`` functions.
|
||||
See also the ``get_object_traceback()`` function.
|
||||
|
||||
|
||||
``set_traceback_limit(nframe: int)`` function:
|
||||
|
|
@ -273,6 +219,18 @@ a size of 32 bytes and was allocated at ``x.py:7``, line called from line
|
|||
limit at startup.
|
||||
|
||||
|
||||
``take_snapshot()`` function:
|
||||
|
||||
Take a snapshot of traces of memory blocks allocated by Python.
|
||||
|
||||
Tracebacks of traces are limited to ``traceback_limit`` frames. Use
|
||||
``set_traceback_limit()`` to store more frames.
|
||||
|
||||
The ``tracemalloc`` module must be enabled to take a snapshot, see
|
||||
the the ``enable()`` function.
|
||||
|
||||
|
||||
|
||||
Filter Functions
|
||||
----------------
|
||||
|
||||
|
|
@ -289,31 +247,6 @@ Filter Functions
|
|||
The new filter is not applied on already collected traces. Use the
|
||||
``reset()`` function to ensure that all traces match the new filter.
|
||||
|
||||
``add_inclusive_filter(filename_pattern: str, lineno: int=None, traceback: bool=False)`` function:
|
||||
|
||||
Add an inclusive filter: helper for the ``add_filter()`` function
|
||||
creating a ``Filter`` instance with the ``Filter.include`` attribute
|
||||
set to ``True``.
|
||||
|
||||
The ``*`` joker character can be used in *filename_pattern* to match
|
||||
any substring, including empty string.
|
||||
|
||||
Example: ``tracemalloc.add_inclusive_filter(subprocess.__file__)``
|
||||
only includes memory blocks allocated by the ``subprocess`` module.
|
||||
|
||||
|
||||
``add_exclusive_filter(filename_pattern: str, lineno: int=None, traceback: bool=False)`` function:
|
||||
|
||||
Add an exclusive filter: helper for the ``add_filter()`` function
|
||||
creating a ``Filter`` instance with the ``Filter.include`` attribute
|
||||
set to ``False``.
|
||||
|
||||
The ``*`` joker character can be used in *filename_pattern* to match
|
||||
any substring, including empty string.
|
||||
|
||||
Example: ``tracemalloc.add_exclusive_filter(tracemalloc.__file__)``
|
||||
ignores memory blocks allocated by the ``tracemalloc`` module.
|
||||
|
||||
|
||||
``clear_filters()`` function:
|
||||
|
||||
|
|
@ -348,6 +281,8 @@ Filter
|
|||
comparison is case insensitive and the alternative separator ``/``
|
||||
is replaced with the standard separator ``\``.
|
||||
|
||||
Use ``Filter(False, "<unknown>")`` to exclude empty tracebacks.
|
||||
|
||||
``include`` attribute:
|
||||
|
||||
If *include* is ``True``, only trace memory blocks allocated in a
|
||||
|
|
@ -359,8 +294,8 @@ Filter
|
|||
|
||||
``lineno`` attribute:
|
||||
|
||||
Line number (``int``) of the filter. If *lineno* is is ``None`` or
|
||||
less than ``1``, the filter matches any line number.
|
||||
Line number (``int``) of the filter. If *lineno* is ``None``, the
|
||||
filter matches any line number.
|
||||
|
||||
``filename_pattern`` attribute:
|
||||
|
||||
|
|
@ -378,9 +313,9 @@ Filter
|
|||
GroupedStats
|
||||
------------
|
||||
|
||||
``GroupedStats(timestamp: datetime.datetime, traceback_limit: int, stats: dict, key_type: str, cumulative: bool)`` class:
|
||||
``GroupedStats(timestamp: datetime.datetime, traceback_limit: int, key_type: str, stats: dict, cumulative: bool)`` class:
|
||||
|
||||
Top of allocated memory blocks grouped by *key_type* as a
|
||||
Statistics of allocated memory blocks grouped by *key_type* as a
|
||||
dictionary.
|
||||
|
||||
The ``Snapshot.group_by()`` method creates a ``GroupedStats``
|
||||
|
|
@ -396,10 +331,6 @@ GroupedStats
|
|||
*key*. Set the *sort* parameter to ``False`` to get the list
|
||||
unsorted.
|
||||
|
||||
``None`` values in keys are replaced with an empty string for
|
||||
filenames or zero for line numbers, because ``str`` and ``int``
|
||||
cannot be compared to ``None``.
|
||||
|
||||
See also the ``statistics()`` method.
|
||||
|
||||
``statistics(sort=True)`` method:
|
||||
|
|
@ -413,10 +344,6 @@ GroupedStats
|
|||
*key*. Set the *sort* parameter to ``False`` to get the list
|
||||
unsorted.
|
||||
|
||||
``None`` values in keys are replaced with an empty string for
|
||||
filenames or zero for line numbers, because ``str`` and ``int``
|
||||
cannot be compared to ``None``.
|
||||
|
||||
See also the ``compare_to()`` method.
|
||||
|
||||
``cumulative`` attribute:
|
||||
|
|
@ -450,35 +377,16 @@ GroupedStats
|
|||
Snapshot
|
||||
--------
|
||||
|
||||
``Snapshot(timestamp: datetime.datetime, traceback_limit: int, stats: dict=None, traces: dict=None)`` class:
|
||||
``Snapshot(timestamp: datetime.datetime, traceback_limit: int, traces: dict=None)`` class:
|
||||
|
||||
Snapshot of statistics and traces of memory blocks allocated by
|
||||
Python.
|
||||
Snapshot of traces of memory blocks allocated by Python.
|
||||
|
||||
``apply_filters(filters)`` method:
|
||||
|
||||
Apply filters on the ``traces`` and ``stats`` dictionaries,
|
||||
*filters* is a list of ``Filter`` instances.
|
||||
Apply filters on the ``traces`` dictionary, *filters* is a list of
|
||||
``Filter`` instances.
|
||||
|
||||
|
||||
``create(traces=False)`` classmethod:
|
||||
|
||||
Take a snapshot of statistics and traces of memory blocks allocated
|
||||
by Python.
|
||||
|
||||
If *traces* is ``True``, ``get_traces()`` is called and its result
|
||||
is stored in the ``Snapshot.traces`` attribute. This attribute
|
||||
contains more information than ``Snapshot.stats`` and uses more
|
||||
memory and more disk space. If *traces* is ``False``,
|
||||
``Snapshot.traces`` is set to ``None``.
|
||||
|
||||
Tracebacks of traces are limited to ``traceback_limit`` frames. Call
|
||||
``set_traceback_limit()`` before calling ``Snapshot.create()`` to
|
||||
store more frames.
|
||||
|
||||
The ``tracemalloc`` module must be enabled to take a snapshot, see
|
||||
the the ``enable()`` function.
|
||||
|
||||
``dump(filename)`` method:
|
||||
|
||||
Write the snapshot into a file.
|
||||
|
|
@ -495,32 +403,23 @@ Snapshot
|
|||
|
||||
``group_by(key_type: str, cumulative: bool=False)`` method:
|
||||
|
||||
Group statistics by *key_type* as a ``GroupedStats`` instance:
|
||||
Group statistics by *key_type*. Return a ``GroupedStats`` instance:
|
||||
|
||||
===================== =================================== ================================
|
||||
key_type description type
|
||||
===================== =================================== ================================
|
||||
``'filename'`` filename ``str``
|
||||
``'line'`` filename and line number ``(filename: str, lineno: int)``
|
||||
``'address'`` memory block address ``int``
|
||||
``'traceback'`` memory block address with traceback ``(address: int, traceback)``
|
||||
===================== =================================== ================================
|
||||
|
||||
The ``traceback`` type is a tuple of ``(filename: str, lineno:
|
||||
int)`` tuples, *filename* and *lineno* can be ``None``.
|
||||
===================== ======================== ================================================
|
||||
key_type description type
|
||||
===================== ======================== ================================================
|
||||
``'filename'`` filename ``str``
|
||||
``'lineno'`` filename and line number ``(filename: str, lineno: int)``
|
||||
``'traceback'`` traceback tuple of ``(filename: str, lineno: int)`` tuples
|
||||
===================== ======================== ================================================
|
||||
|
||||
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 ``'address'``, or if the traceback limit is less than
|
||||
``2``.
|
||||
*key_type* is ``'traceback'``, or if the ``traceback_limit``
|
||||
attribute is less than ``2``.
|
||||
|
||||
|
||||
``stats`` attribute:
|
||||
|
||||
Statistics on traced Python memory, result of the ``get_stats()``
|
||||
function.
|
||||
|
||||
``traceback_limit`` attribute:
|
||||
|
||||
Maximum number of frames stored in the traceback of ``traces``,
|
||||
|
|
@ -528,8 +427,10 @@ Snapshot
|
|||
|
||||
``traces`` attribute:
|
||||
|
||||
Traces of Python memory allocations, result of the ``get_traces()``
|
||||
function, can be ``None``.
|
||||
Traces of all memory blocks allocated by Python, result of the
|
||||
``get_traces()`` function: list of ``(size: int, traceback: tuple)``
|
||||
tuples, *traceback* is a tuple of ``(filename: str, lineno: int)``
|
||||
tuples.
|
||||
|
||||
``timestamp`` attribute:
|
||||
|
||||
|
|
@ -552,7 +453,6 @@ Statistic
|
|||
Key identifying the statistic. The key type depends on
|
||||
``GroupedStats.key_type``, see the ``Snapshot.group_by()`` method.
|
||||
|
||||
|
||||
``count`` attribute:
|
||||
|
||||
Number of memory blocks (``int``).
|
||||
|
|
|
|||
Loading…
Reference in New Issue