[Python-checkins] peps: PEP 454
victor.stinner
python-checkins at python.org
Tue Sep 3 13:18:46 CEST 2013
http://hg.python.org/peps/rev/9879b34ef73a
changeset: 5092:9879b34ef73a
user: Victor Stinner <victor.stinner at gmail.com>
date: Tue Sep 03 13:18:48 2013 +0200
summary:
PEP 454
files:
pep-0454.txt | 95 ++++++++++++++++++++++-----------------
1 files changed, 53 insertions(+), 42 deletions(-)
diff --git a/pep-0454.txt b/pep-0454.txt
--- a/pep-0454.txt
+++ b/pep-0454.txt
@@ -20,14 +20,15 @@
Rationale
=========
-This PEP proposes to a new ``tracemalloc`` module, a debug tool to trace
-memory allocations made by Python. The module provides the following
-information:
+This PEP proposes to a new ``tracemalloc`` module. It is a debug tool to
+trace memory allocations made by Python based on API added by the PEP
+445. The module provides the following information:
-* Statistics on allocations per Python line number (file and line):
- size, number, and average size of allocations
-* Compute delta between two "snapshots"
-* Location of a memory allocation: Python filename and line number
+* Statistics on Python memory allocations per Python filename and line
+ number: size, number, and average size of allocations
+* Compute differences between two snapshots of Python memory allocations
+* Location of a Python memory allocation: size in bytes, Python filename
+ and line number
The ``tracemalloc`` module is different than other third-party modules
like ``Heapy`` or ``PySizer``, because it is focused on the location of
@@ -47,32 +48,35 @@
Functions
---------
-enable():
+``enable()`` function:
Start tracing Python memory allocations.
-disable():
+``disable()`` function:
Stop tracing Python memory allocations and stop the timer started by
``start_timer()``.
-is_enabled():
+``is_enabled()`` function:
Get the status of the module: ``True`` if it is enabled, ``False``
otherwise.
-get_object_trace(obj):
+``get_object_trace(obj)`` function:
- Get the trace of a Python object *obj* as a namedtuple with 3 attributes:
+ Get the trace of the memory allocation of the Python object *obj*.
+ Return a namedtuple with 3 attributes if the memory allocation was
+ traced:
- ``size``: size in bytes of the object
- ``filename``: name of the Python script where the object was allocated
- ``lineno``: line number where the object was allocated
- Return ``None`` if tracemalloc did not save the location where the object
- was allocated, for example if tracemalloc was disabled.
+ Return ``None`` if ``tracemalloc`` did not trace the memory
+ allocation, for example if ``tracemalloc`` was disabled when the
+ object was created.
-get_process_memory():
+``get_process_memory()`` function:
Get the memory usage of the current process as a meminfo namedtuple
with two attributes:
@@ -84,7 +88,7 @@
Use the ``psutil`` module if available.
-start_timer(delay: int, func: callable, args: tuple=(), kwargs: dict={}):
+``start_timer(delay: int, func: callable, args: tuple=(), kwargs: dict={})`` function:
Start a timer calling ``func(*args, **kwargs)`` every *delay*
seconds.
@@ -97,10 +101,10 @@
If ``start_timer()`` is called twice, previous parameters are
replaced. The timer has a resolution of 1 second.
- `start_timer()`` is used by ``DisplayTop`` and ``TakeSnapshot`` to
+ ``start_timer()`` is used by ``DisplayTop`` and ``TakeSnapshot`` to
run regulary a task.
-stop_timer():
+``stop_timer()`` function:
Stop the timer started by ``start_timer()``.
@@ -110,15 +114,17 @@
``DisplayTop(count: int, file=sys.stdout)`` class:
- Display the list of the N biggest memory allocations.
+ Display the list of the *count* biggest memory allocations into
+ *file*.
``display()`` method:
- Display the top
+ Display the top once.
``start(delay: int)`` method:
- Start a task using tracemalloc timer to display the top every delay seconds.
+ Start a task using ``tracemalloc`` timer to display the top every
+ *delay* seconds.
``stop()`` method:
@@ -132,21 +138,22 @@
``compare_with_previous`` attribute:
If ``True``, ``display()`` compares with the previous top if
- ``True``. If ``False``, compare with the first one (bool, default:
- ``True``): .
+ ``True``. If ``False``, compare with the first top (bool, default:
+ ``True``).
``filename_parts`` attribute:
- Number of displayed filename parts (int, default: ``3``).
+ Number of displayed filename parts (int, default: ``3``).
``show_average`` attribute:
- If ``True``, ``display()`` shows the average size of allocations
- (bool, default: ``True``).
+ If ``True``, ``display()`` shows the average size of allocations
+ (bool, default: ``True``).
``show_count`` attribute:
- If ``True``, ``display()`` shows the number of allocations (bool, default: ``True``).
+ If ``True``, ``display()`` shows the number of allocations (bool,
+ default: ``True``).
``show_lineno`` attribute:
@@ -169,24 +176,27 @@
``Snapshot()`` class:
- Snapshot of Python memory allocations. Use ``TakeSnapshot`` to
- regulary take snapshots.
+ Snapshot of Python memory allocations.
+
+ Use ``TakeSnapshot`` to take regulary snapshots.
``create(user_data_callback=None)`` method:
- Take a snapshot. If user_data_callback is specified, it must be a
+ Take a snapshot. If *user_data_callback* is specified, it must be a
callable object returning a list of (title: str, format: str, value:
- int). format must be "size". The list must always have the same
+ int). format must be ``'size'``. The list must always have the same
length and the same order to be able to compute differences between
values.
Example: ``[('Video memory', 'size', 234902)]``.
-``filter_filenames(patterns: str|list, include: bool)`` method:
+``filter_filenames(patterns: list, include: bool)`` method:
- Remove filenames not matching any pattern if include is True, or
- remove filenames matching a pattern if include is False (exclude).
- See fnmatch.fnmatch() for the syntax of patterns.
+ Remove filenames not matching any pattern of *patterns* if *include*
+ is ``True``, or remove filenames matching a pattern of *patterns* if
+ *include* is ``False`` (exclude).
+
+ See ``fnmatch.fnmatch()`` for the syntax of a pattern.
``write(filename)`` method:
@@ -224,7 +234,8 @@
``TakeSnapshot`` class:
- Task taking snapshots of Python memory allocations: write them into files.
+ Task taking snapshots of Python memory allocations: write them into
+ files. By default, snapshots are written in the current directory.
``start(delay: int)`` method:
@@ -240,17 +251,19 @@
``filename_template`` attribute:
- Template (str) to create a filename. "Variables" can be used in the
- template:
+ Template (``str``) used to create a filename. The following
+ variables can be used in the template:
* ``$pid``: identifier of the current process
* ``$timestamp``: current date and time
* ``$counter``: counter starting at 1 and incremented at each snapshot
+ The default pattern is ``'tracemalloc-$counter.pickle'``.
+
``user_data_callback`` attribute:
- Optional callback collecting user data (callable, default: None).
- See ``Snapshot.create()``.
+ Optional callback collecting user data (callable, default:
+ ``None``). See ``Snapshot.create()``.
Links
@@ -265,8 +278,6 @@
* `Meliae: Python Memory Usage Analyzer
<https://pypi.python.org/pypi/meliae>`_
-* `Issue #3329: API for setting the memory allocator used by Python
- <http://bugs.python.org/issue3329>`_
* `Guppy-PE: umbrella package combining Heapy and GSL
<http://guppy-pe.sourceforge.net/>`_
* `PySizer <http://pysizer.8325.org/>`_: developed for Python 2.4
--
Repository URL: http://hg.python.org/peps
More information about the Python-checkins
mailing list