PEP 454: add frame class
Other changes: * add the type and default value of almost all attributes * move the "Command line options" section to the end
This commit is contained in:
Victor Stinner
parent
a80266cdc2
commit
4ab328f1f2
217
pep-0454.txt
217
pep-0454.txt
|
|
@ -57,65 +57,6 @@ following information:
|
|||
and line number
|
||||
|
||||
|
||||
Command line options
|
||||
====================
|
||||
|
||||
The ``python -m tracemalloc`` command can be used to analyze and compare
|
||||
snapshots. The command takes a list of snapshot filenames and has the
|
||||
following options.
|
||||
|
||||
``-g``, ``--group-per-file``
|
||||
|
||||
Group allocations per filename, instead of grouping per line number.
|
||||
|
||||
``-n NTRACES``, ``--number NTRACES``
|
||||
|
||||
Number of traces displayed per top (default: 10).
|
||||
|
||||
``--first``
|
||||
|
||||
Compare with the first snapshot, instead of comparing with the
|
||||
previous snapshot.
|
||||
|
||||
``--include PATTERN``
|
||||
|
||||
Only include filenames matching pattern *PATTERN*. The option can be
|
||||
specified multiple times.
|
||||
|
||||
See ``fnmatch.fnmatch()`` for the syntax of patterns.
|
||||
|
||||
``--exclude PATTERN``
|
||||
|
||||
Exclude filenames matching pattern *PATTERN*. The option can be
|
||||
specified multiple times.
|
||||
|
||||
See ``fnmatch.fnmatch()`` for the syntax of patterns.
|
||||
|
||||
``-S``, ``--hide-size``
|
||||
|
||||
Hide the size of allocations.
|
||||
|
||||
``-C``, ``--hide-count``
|
||||
|
||||
Hide the number of allocations.
|
||||
|
||||
``-A``, ``--hide-average``
|
||||
|
||||
Hide the average size of allocations.
|
||||
|
||||
``-P PARTS``, ``--filename-parts=PARTS``
|
||||
|
||||
Number of displayed filename parts (default: 3).
|
||||
|
||||
``--color``
|
||||
|
||||
Force usage of colors even if ``sys.stdout`` is not a TTY device.
|
||||
|
||||
``--no-color``
|
||||
|
||||
Disable colors if ``sys.stdout`` is a TTY device.
|
||||
|
||||
|
||||
API
|
||||
===
|
||||
|
||||
|
|
@ -210,6 +151,22 @@ Functions
|
|||
Stop the timer started by ``start_timer()``.
|
||||
|
||||
|
||||
frame class
|
||||
-----------
|
||||
|
||||
``frame`` class:
|
||||
|
||||
Trace of a Python frame.
|
||||
|
||||
``filename`` attribute (``str``):
|
||||
|
||||
Python filename, ``None`` if unknown.
|
||||
|
||||
``lineno`` attribute (``int``):
|
||||
|
||||
Python line number, ``None`` if unknown.
|
||||
|
||||
|
||||
trace class
|
||||
-----------
|
||||
|
||||
|
|
@ -217,19 +174,19 @@ trace class
|
|||
|
||||
This class represents debug information of an allocated memory block.
|
||||
|
||||
``size`` attribute:
|
||||
``size`` attribute (``int``):
|
||||
|
||||
Size in bytes of the memory block.
|
||||
|
||||
``filename`` attribute:
|
||||
``frames`` attribute (``list``):
|
||||
|
||||
Name of the Python script where the memory block was allocated,
|
||||
``None`` if unknown.
|
||||
Traceback where the memory block was allocated as a list of
|
||||
``frame`` instances (most recent first).
|
||||
|
||||
``lineno`` attribute:
|
||||
The list can be empty or incomplete if the tracemalloc module was
|
||||
unable to retrieve the full traceback.
|
||||
|
||||
Line number where the memory block was allocated, ``None`` if
|
||||
unknown.
|
||||
For efficiency, the traceback is truncated to 10 frames.
|
||||
|
||||
|
||||
line_stat class
|
||||
|
|
@ -239,11 +196,11 @@ line_stat class
|
|||
|
||||
Statistics on Python memory allocations of a specific line number.
|
||||
|
||||
``size`` attribute:
|
||||
``size`` attribute (``int``):
|
||||
|
||||
Total size in bytes of all memory blocks allocated on the line.
|
||||
|
||||
``count`` attribute:
|
||||
``count`` attribute (``int``):
|
||||
|
||||
Number of memory blocks allocated on the line.
|
||||
|
||||
|
|
@ -269,45 +226,43 @@ DisplayTop class
|
|||
|
||||
Stop the task started by the ``DisplayTop.start()`` method
|
||||
|
||||
``color`` attribute:
|
||||
``color`` attribute (``bool``, default: ``file.isatty()``):
|
||||
|
||||
If ``True``, ``display()`` uses color. The default value is
|
||||
``file.isatty()``.
|
||||
If ``True``, ``display()`` uses color.
|
||||
|
||||
``compare_with_previous`` attribute:
|
||||
``compare_with_previous`` attribute (``bool``, default: ``True``):
|
||||
|
||||
If ``True`` (default value), ``display()`` compares with the
|
||||
If ``True``, ``display()`` compares with the
|
||||
previous snapshot. If ``False``, compare with the first snapshot.
|
||||
|
||||
``filename_parts`` attribute:
|
||||
``filename_parts`` attribute (``int``, default: ``3``):
|
||||
|
||||
Number of displayed filename parts (int, default: ``3``). Extra
|
||||
parts are replaced with ``"..."``.
|
||||
Number of displayed filename parts. Extra parts are replaced
|
||||
with ``"..."``.
|
||||
|
||||
``group_per_file`` attribute:
|
||||
``group_per_file`` attribute (``bool``, default: ``False``):
|
||||
|
||||
If ``True``, group memory allocations per Python filename. If
|
||||
``False`` (default value), group allocation per Python line number.
|
||||
``False``, group allocation per Python line number.
|
||||
|
||||
``show_average`` attribute:
|
||||
``show_average`` attribute (``bool``, default: ``True``):
|
||||
|
||||
If ``True`` (default value), ``display()`` shows the average size
|
||||
If ``True``, ``display()`` shows the average size
|
||||
of allocations.
|
||||
|
||||
``show_count`` attribute:
|
||||
``show_count`` attribute (``bool``, default: ``True``):
|
||||
|
||||
If ``True`` (default value), ``display()`` shows the number of
|
||||
If ``True``, ``display()`` shows the number of
|
||||
allocations.
|
||||
|
||||
``show_size`` attribute:
|
||||
``show_size`` attribute (``bool``, default: ``True``):
|
||||
|
||||
If ``True`` (default value), ``display()`` shows the size of
|
||||
If ``True``, ``display()`` shows the size of
|
||||
allocations.
|
||||
|
||||
``user_data_callback`` attribute:
|
||||
``user_data_callback`` attribute (``callable``, default: ``None``):
|
||||
|
||||
Optional callback collecting user data (callable, default:
|
||||
``None``). See ``Snapshot.create()``.
|
||||
Optional callback collecting user data. See ``Snapshot.create()``.
|
||||
|
||||
|
||||
Snapshot class
|
||||
|
|
@ -346,27 +301,26 @@ Snapshot class
|
|||
|
||||
Write the snapshot into a file.
|
||||
|
||||
``pid`` attribute:
|
||||
``pid`` attribute (``int``):
|
||||
|
||||
Identifier of the process which created the snapshot (int).
|
||||
Identifier of the process which created the snapshot.
|
||||
|
||||
``process_memory`` attribute:
|
||||
|
||||
Result of the ``get_process_memory()`` function, can be ``None``.
|
||||
|
||||
``stats`` attribute:
|
||||
``stats`` attribute (``dict``):
|
||||
|
||||
Result of the ``get_stats()`` function (dict).
|
||||
Result of the ``get_stats()`` function.
|
||||
|
||||
``timestamp`` attribute:
|
||||
``timestamp`` attribute (``datetime.datetime``):
|
||||
|
||||
Creation date and time of the snapshot, ``datetime.datetime``
|
||||
instance.
|
||||
Creation date and time of the snapshot.
|
||||
|
||||
``user_data`` attribute:
|
||||
``user_data`` attribute (``list``, default: ``None``):
|
||||
|
||||
Optional list of user data, result of *user_data_callback* in
|
||||
``Snapshot.create()`` (default: None).
|
||||
``Snapshot.create()``.
|
||||
|
||||
|
||||
TakeSnapshot class
|
||||
|
|
@ -389,21 +343,78 @@ TakeSnapshot class
|
|||
|
||||
Take a snapshot.
|
||||
|
||||
``filename_template`` attribute:
|
||||
``filename_template`` attribute (``str``,
|
||||
default: ``'tracemalloc-$counter.pickle'``):
|
||||
|
||||
Template (``str``) used to create a filename. The following
|
||||
variables can be used in the template:
|
||||
Template 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 (``callable``, default: ``None``):
|
||||
|
||||
``user_data_callback`` attribute:
|
||||
Optional callback collecting user data. See ``Snapshot.create()``.
|
||||
|
||||
Optional callback collecting user data (callable, default:
|
||||
``None``). See ``Snapshot.create()``.
|
||||
|
||||
Command line options
|
||||
====================
|
||||
|
||||
The ``python -m tracemalloc`` command can be used to analyze and compare
|
||||
snapshots. The command takes a list of snapshot filenames and has the
|
||||
following options.
|
||||
|
||||
``-g``, ``--group-per-file``
|
||||
|
||||
Group allocations per filename, instead of grouping per line number.
|
||||
|
||||
``-n NTRACES``, ``--number NTRACES``
|
||||
|
||||
Number of traces displayed per top (default: 10).
|
||||
|
||||
``--first``
|
||||
|
||||
Compare with the first snapshot, instead of comparing with the
|
||||
previous snapshot.
|
||||
|
||||
``--include PATTERN``
|
||||
|
||||
Only include filenames matching pattern *PATTERN*. The option can be
|
||||
specified multiple times.
|
||||
|
||||
See ``fnmatch.fnmatch()`` for the syntax of patterns.
|
||||
|
||||
``--exclude PATTERN``
|
||||
|
||||
Exclude filenames matching pattern *PATTERN*. The option can be
|
||||
specified multiple times.
|
||||
|
||||
See ``fnmatch.fnmatch()`` for the syntax of patterns.
|
||||
|
||||
``-S``, ``--hide-size``
|
||||
|
||||
Hide the size of allocations.
|
||||
|
||||
``-C``, ``--hide-count``
|
||||
|
||||
Hide the number of allocations.
|
||||
|
||||
``-A``, ``--hide-average``
|
||||
|
||||
Hide the average size of allocations.
|
||||
|
||||
``-P PARTS``, ``--filename-parts=PARTS``
|
||||
|
||||
Number of displayed filename parts (default: 3).
|
||||
|
||||
``--color``
|
||||
|
||||
Force usage of colors even if ``sys.stdout`` is not a TTY device.
|
||||
|
||||
``--no-color``
|
||||
|
||||
Disable colors if ``sys.stdout`` is a TTY device.
|
||||
|
||||
|
||||
Links
|
||||
|
|
|
|||
Loading…
Reference in New Issue