[Python-checkins] peps: PEP 454
victor.stinner
python-checkins at python.org
Sun Oct 27 17:23:11 CET 2013
http://hg.python.org/peps/rev/eec85dece294
changeset: 5228:eec85dece294
user: Victor Stinner <victor.stinner at gmail.com>
date: Sun Oct 27 17:22:57 2013 +0100
summary:
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()
files:
pep-0454.txt | 206 ++++++++++----------------------------
1 files changed, 53 insertions(+), 153 deletions(-)
diff --git a/pep-0454.txt b/pep-0454.txt
--- a/pep-0454.txt
+++ b/pep-0454.txt
@@ -110,15 +110,15 @@
``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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
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 @@
``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 @@
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 @@
*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 @@
*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 @@
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 @@
``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 @@
``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 @@
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``).
--
Repository URL: http://hg.python.org/peps
More information about the Python-checkins
mailing list