[Python-checkins] peps: PEP 454: remove GroupedStats.timestamp/.traceback_limit attributes

victor.stinner python-checkins at python.org
Mon Oct 28 00:20:34 CET 2013


http://hg.python.org/peps/rev/62149b9671ff
changeset:   5230:62149b9671ff
user:        Victor Stinner <victor.stinner at gmail.com>
date:        Mon Oct 28 00:20:26 2013 +0100
summary:
  PEP 454: remove GroupedStats.timestamp/.traceback_limit attributes

various cleanup

files:
  pep-0454.txt |  82 ++++++++++++++++++++-------------------
  1 files changed, 42 insertions(+), 40 deletions(-)


diff --git a/pep-0454.txt b/pep-0454.txt
--- a/pep-0454.txt
+++ b/pep-0454.txt
@@ -138,8 +138,8 @@
 
 ``get_tracemalloc_memory()`` function:
 
-    Get the memory usage in bytes of the ``tracemalloc`` module used
-    internally to trace memory allocations. Return an ``int``.
+    Get the memory usage in bytes of the ``tracemalloc`` module used to
+    store traces of memory blocks. Return an ``int``.
 
 
 ``is_enabled()`` function:
@@ -166,8 +166,8 @@
 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
+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``.
 
 
@@ -194,9 +194,13 @@
 
 ``get_traces()`` function:
 
-    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.
+    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 do not include memory blocks allocated before the
+    ``tracemalloc`` module was enabled and memory blocks ignored by
+    filters (see ``get_filters()()``).
 
     Return an empty list if the ``tracemalloc`` module is disabled.
 
@@ -240,9 +244,8 @@
     ``Filter`` instance.
 
     All inclusive filters are applied at once, a memory allocation is
-    only ignored if no inclusive filters match its trace. A memory
-    allocation is ignored if at least one exclusive filter matchs its
-    trace.
+    ignored if no inclusive filters match its trace. A memory allocation
+    is ignored if at least one exclusive filter matchs its trace.
 
     The new filter is not applied on already collected traces. Use the
     ``reset()`` function to ensure that all traces match the new filter.
@@ -275,13 +278,14 @@
     used to reduce the memory usage of the ``tracemalloc`` module, which
     can be read using the ``get_tracemalloc_memory()`` function.
 
-    The ``*`` joker character can be used in *filename_pattern* to match
-    any substring, including empty string. The ``.pyc`` and ``.pyo``
-    file extensions are replaced with ``.py``. On Windows, the
-    comparison is case insensitive and the alternative separator ``/``
-    is replaced with the standard separator ``\``.
+    The ``'*'`` joker character can be used in *filename_pattern* to
+    match any substring, including empty string. The ``'.pyc'`` and
+    ``'.pyo'`` file extensions are replaced with ``'.py'``. On Windows,
+    the comparison is case insensitive and the alternative separator
+    ``'/'`` is replaced with the standard separator ``'\'``.
 
-    Use ``Filter(False, "<unknown>")`` to exclude empty tracebacks.
+    For example, use ``Filter(False, "<unknown>")`` to exclude empty
+    tracebacks.
 
 ``include`` attribute:
 
@@ -313,7 +317,7 @@
 GroupedStats
 ------------
 
-``GroupedStats(timestamp: datetime.datetime, traceback_limit: int, key_type: str, stats: dict, cumulative: bool)`` class:
+``GroupedStats(key_type: str, stats: dict, cumulative: bool)`` class:
 
     Statistics of allocated memory blocks grouped by *key_type* as a
     dictionary.
@@ -326,7 +330,7 @@
     Compare statistics to an older ``GroupedStats`` instance. Return a
     list of ``Statistic`` instances.
 
-    The result is sorted in the biggest to the smallest by
+    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.
@@ -339,7 +343,7 @@
     ``Statistic.size_diff`` and ``Statistic.count_diff`` attributes are
     set to zero.
 
-    The result is sorted in the biggest to the smallest by
+    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.
@@ -354,25 +358,16 @@
 ``key_type`` attribute:
 
     Determine how memory allocations were grouped: see
-    ``Snapshot.group_by()()`` for the available values.
+    ``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.
+    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.
 
-``traceback_limit`` attribute:
-
-    Maximum number of frames stored in the traceback of ``traces``,
-    result of the ``get_traceback_limit()`` function.
-
-``timestamp`` attribute:
-
-    Creation date and time of the snapshot, ``datetime.datetime``
-    instance.
-
 
 Snapshot
 --------
@@ -381,6 +376,8 @@
 
     Snapshot of traces of memory blocks allocated by Python.
 
+    The ``take_snapshot()`` function create a snapshot instance.
+
 ``apply_filters(filters)`` method:
 
     Apply filters on the ``traces`` dictionary, *filters* is a list of
@@ -403,15 +400,16 @@
 
 ``group_by(key_type: str, cumulative: bool=False)`` method:
 
-    Group statistics by *key_type*. Return a ``GroupedStats`` instance:
+    Group statistics by *key_type*. Return a ``GroupedStats`` instance.
+    Key types:
 
-      =====================  ========================  ================================================
-      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
-      =====================  ========================  ================================================
+    =====================  ========================  ================================================
+    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
@@ -445,6 +443,9 @@
 
     Statistic on memory allocations.
 
+    ``size_diff`` and ``count_diff`` attributes are the difference
+    between two ``GroupedStats`` instance.
+
     ``GroupedStats.compare_to()``  and ``GroupedStats.statistics()``
     return a list of ``Statistic`` instances.
 
@@ -520,6 +521,7 @@
 * `pytracemalloc on PyPI
   <https://pypi.python.org/pypi/pytracemalloc>`_
 
+
 Copyright
 =========
 

-- 
Repository URL: http://hg.python.org/peps


More information about the Python-checkins mailing list