EP 454: reformat

pep-0454.txt

@@ -13,7 +13,7 @@ Python-Version: 3.4
 Abstract
 ========
 
-Add a new tracemalloc module to trace Python memory allocations.
+Add a new ``tracemalloc`` module to trace Python memory allocations.
 
 
 
@@ -29,6 +29,14 @@ information:
 * Compute delta between two "snapshots"
 * Location of a memory allocation: 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
+a memory allocation rather that the object type or object content.
+
+
+API
+===
+
 To trace the most Python memory allocations, the module should be
 enabled as early as possible in your application by calling
 ``tracemalloc.enable()`` function, by setting the ``PYTHONTRACEMALLOC``
@@ -36,9 +44,6 @@ environment variable to ``1``, or  by using ``-X tracemalloc`` command
 line option.
 
 
-API
-===
-
 Functions
 ---------
 
@@ -53,7 +58,8 @@ disable():
 
 is_enabled():
 
-  ``True`` if the module is enabled, ``False`` otherwise.
+    Get the status of the module: ``True`` if it is enabled, ``False``
+    otherwise.
 
 get_object_trace(obj):
 
@@ -68,8 +74,8 @@ get_object_trace(obj):
 
 get_process_memory():
 
-   Get the memory usage of the current process as a meminfo namedtuple with
+    Get the memory usage of the current process as a meminfo namedtuple
-   two attributes:
+    with two attributes:
 
     * ``rss``: Resident Set Size in bytes
     * ``vms``: size of the virtual memory in bytes
@@ -91,8 +97,8 @@ start_timer(delay: int, func: callable, args: tuple=(), kwargs: dict={}):
     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``
+    `start_timer()`` is used by ``DisplayTop`` and ``TakeSnapshot`` to
-   to run regulary a task.
+    run regulary a task.
 
 stop_timer():
 
@@ -102,53 +108,57 @@ stop_timer():
 DisplayTop class
 ----------------
 
-DisplayTop(count: int, file=sys.stdout) class:
+``DisplayTop(count: int, file=sys.stdout)`` class:
 
     Display the list of the N biggest memory allocations.
 
-display() method:
+``display()`` method:
 
     Display the top
 
-start(delay: int) method:
+``start(delay: int)`` method:
 
     Start a task using tracemalloc timer to display the top every delay seconds.
 
-stop() method:
+``stop()`` method:
 
     Stop the task started by the ``DisplayTop.start()`` method
 
-color attribute:
+``color`` attribute:
 
-      Use color if True (bool, default: stream.isatty()).
+    ``display()`` uses colors if ``True`` (bool,
+    default: ``stream.isatty()``).
 
-compare_with_previous attribute:
+``compare_with_previous`` attribute:
 
-      If ``True``, compare with the previous top if ``True``. If ``False``,
+    If ``True``, ``display()`` compares with the previous top if
-      compare with the first one (bool, default: ``True``): .
+    ``True``. If ``False``, compare with the first one (bool, default:
+    ``True``): .
 
-filename_parts attribute:
+``filename_parts`` attribute:
 
       Number of displayed filename parts (int, default: ``3``).
 
-show_average attribute:
+``show_average`` attribute:
 
-      If ``True``, show the average size of allocations (bool, default: ``True``).
+      If ``True``, ``display()`` shows the average size of allocations
+      (bool, default: ``True``).
 
-show_count attribute:
+``show_count`` attribute:
 
-      If ``True``, show the number of allocations (bool, default: ``True``).
+    If ``True``, ``display()`` shows the number of allocations (bool, default: ``True``).
 
-show_lineno attribute:
+``show_lineno`` attribute:
 
-      If ``True``, use also the line number, not only the filename (bool, default:
+    If ``True``, use also the line number, not only the filename (bool,
-      ``True``). If ``False``, only show the filename.
+    default: ``True``). If ``False``, only show the filename.
 
-show_size attribute:
+``show_size`` attribute:
 
-      if ``True``, show the size of allocations (bool, default: ``True``).
+    If ``True``, ``display()`` shows the size of allocations (bool,
+    default: ``True``).
 
-user_data_callback attribute:
+``user_data_callback`` attribute:
 
     Optional callback collecting user data (callable, default:
     ``None``).  See ``Snapshot.create()``.
@@ -157,43 +167,54 @@ user_data_callback attribute:
 Snapshot class
 --------------
 
-Snapshot() class:
+``Snapshot()`` class:
 
-   Snapshot of Python memory allocations. Use ``TakeSnapshot`` to regulary
+    Snapshot of Python memory allocations. Use ``TakeSnapshot`` to
-   take snapshots.
+    regulary take snapshots.
 
-create(user_data_callback=None) method:
+``create(user_data_callback=None)`` method:
 
-      Take a snapshot. If user_data_callback is specified, it must be a callable
+    Take a snapshot. If user_data_callback is specified, it must be a
-      object returning a list of (title: str, format: str, value: int). format
+    callable object returning a list of (title: str, format: str, value:
-      must be "size". The list must always have the same length and the same order
+    int). format must be "size". The list must always have the same
-      to be able to compute differences between values.
+    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: str|list, include: bool)`` method:
 
-      Remove filenames not matching any pattern if include is True, or remove
+    Remove filenames not matching any pattern if include is True, or
-      filenames matching a pattern if include is False (exclude). See
+    remove filenames matching a pattern if include is False (exclude).
-      fnmatch.fnmatch() for the syntax of patterns.
+    See fnmatch.fnmatch() for the syntax of patterns.
 
-write(filename) method:
+``write(filename)`` method:
 
     Write the snapshot into a file.
 
-load(filename), classmethod:
+``load(filename)`` classmethod:
 
     Load a snapshot from a file.
 
-pid attribute:
+``process_memory`` attribute:
+
+    Memory usage of the process, result of ``get_process_memory()``.
+    It can be ``None``.
+
+``user_data`` attribute:
+
+    Optional list of user data, result of *user_data_callback* in
+    ``Snapshot.create()`` (default: None).
+
+``pid`` attribute:
 
     Identifier of the process which created the snapshot (int).
 
-stats attribute:
+``stats`` attribute:
 
     Raw memory allocation statistics (dict).
 
-timestamp attribute:
+``timestamp`` attribute:
 
     Date and time of the creation of the snapshot (str).
 
@@ -201,23 +222,23 @@ timestamp attribute:
 TakeSnapshot class
 ------------------
 
-TakeSnapshot class:
+``TakeSnapshot`` class:
 
     Task taking snapshots of Python memory allocations: write them into files.
 
-start(delay: int) method:
+``start(delay: int)`` method:
 
     Start a task taking a snapshot every delay seconds.
 
-stop() method:
+``stop()`` method:
 
     Stop the task started by the ``TakeSnapshot.start()`` method.
 
-take_snapshot() method:
+``take_snapshot()`` method:
 
     Take a snapshot.
 
-filename_template attribute:
+``filename_template`` attribute:
 
     Template (str) to create a filename. "Variables" can be used in the
     template:
@@ -226,7 +247,7 @@ filename_template attribute:
     * ``$timestamp``: current date and time
     * ``$counter``: counter starting at 1 and incremented at each snapshot
 
-user_data_callback attribute:
+``user_data_callback`` attribute:
 
     Optional callback collecting user data (callable, default: None).
     See ``Snapshot.create()``.