PEP 454: remove enable/disble/is_enabled() functions

pep-0454.txt

@@ -64,13 +64,12 @@ following information:
   number: total size, number and average size of allocated memory blocks
 * Computed differences between two snapshots to detect memory leaks
 
-The API of the tracemalloc module is similar to the API of the
+The API of the tracemalloc module is similar to the API of the faulthandler
-faulthandler module: ``enable()``, ``disable()`` and ``is_enabled()``
+module: ``enable()`` / ``start()``, ``disable()`` / ``stop()`` and
-functions, an environment variable (``PYTHONFAULTHANDLER`` and
+``is_enabled()`` / ``is_tracing()`` functions, an environment variable
-``PYTHONTRACEMALLOC``), and a ``-X`` command line option (``-X
+(``PYTHONFAULTHANDLER`` and ``PYTHONTRACEMALLOC``), and a ``-X`` command line
-faulthandler`` and ``-X tracemalloc``). See the
+option (``-X faulthandler`` and ``-X tracemalloc``). See the `documentation of
-`documentation of the faulthandler module
+the faulthandler module <http://docs.python.org/3/library/faulthandler.html>`_.
-<http://docs.python.org/3/library/faulthandler.html>`_.
 
 The idea of tracing memory allocations is not new. It was first
 implemented in the PySizer project in 2005. PySizer was implemented
@@ -79,7 +78,7 @@ types were linked the trace with the name of object type. PySizer patch
 on CPython adds a overhead on performances and memory footprint, even if
 the PySizer was not used. tracemalloc attachs a traceback to the
 underlying layer, to memory blocks, and has no overhead when the module
-is disabled.
+is not tracing memory allocations.
 
 The tracemalloc module has been written for CPython. Other
 implementations of Python may not be able to provide it.
@@ -89,9 +88,9 @@ API
 ===
 
 To trace most memory blocks allocated by Python, the module should be
-enabled as early as possible by setting the ``PYTHONTRACEMALLOC``
+started as early as possible by setting the ``PYTHONTRACEMALLOC``
 environment variable to ``1``, or by using ``-X tracemalloc`` command
-line option. The ``tracemalloc.enable()`` function can be called at
+line option. The ``tracemalloc.start()`` function can be called at
 runtime to start tracing Python memory allocations.
 
 By default, a trace of an allocated memory block only stores the most
@@ -112,28 +111,7 @@ Main functions
 
     Clear traces of memory blocks allocated by Python.
 
-    See also ``disable()``.
+    See also ``stop()``.
-
-
-``disable()`` function:
-
-    Disable temporarily tracing new Python memory allocations,
-    deallocations are still traced. The change is process-wide, tracing
-    new Python memory allocations is disabled in all threads. Call
-    ``enable()`` to reenable tracing new Python memory allocations.
-
-    Filters can be used to not trace memory allocations in some files:
-    use the ``add_filter()`` function.
-
-    See also ``enable()`` and ``is_enabled()`` functions.
-
-
-``enable()`` function:
-
-    Reenable tracing Python memory allocations if was disabled by te
-    ``disable()`` method.
-
-    See also ``is_enabled()`` functions.
 
 
 ``get_traced_memory()`` function:
@@ -148,28 +126,25 @@ Main functions
     store traces of memory blocks. Return an ``int``.
 
 
-``is_enabled()`` function:
-
-    ``True`` if the ``tracemalloc`` module is enabled Python memory
-    allocations, ``False`` if the module is disabled.
-
-    The ``tracemalloc`` module only traces new allocations if
-    ``is_tracing()`` and ``is_enabled()`` are ``True``.
-
-    See also ``enable()`` and ``disable()`` functions.
-
-
 ``is_tracing()`` function:
 
     ``True`` if the ``tracemalloc`` module is tracing Python memory
     allocations, ``False`` otherwise.
 
-    The ``tracemalloc`` module only traces new allocations if
-    ``is_tracing()`` and ``is_enabled()`` are ``True``.
-
     See also ``start()`` and ``stop()`` functions.
 
 
+``start()`` function:
+
+    Start tracing Python memory allocations.
+
+    The function installs hooks on Python memory allocators. These hooks
+    have important overhead in term of performances and memory usage:
+    see `Filter functions`_ to limit the overhead.
+
+    See also ``stop()`` and ``is_tracing()`` functions.
+
+
 ``stop()`` function:
 
     Stop tracing Python memory allocations and clear traces of memory
@@ -179,21 +154,9 @@ Main functions
     overhead of the module becomes null.
 
     Call ``get_traces()`` or ``take_snapshot()`` function to get traces
-    before clearing them. Use ``disable()`` to disable tracing
+    before clearing them.
-    temporarily.
 
-    See also ``enable()`` and ``is_enabled()`` functions.
+    See also ``start()`` and ``is_tracing()`` functions.
-
-
-``start()`` function:
-
-    Start tracing Python memory allocations.
-
-    The function installs hooks on Python memory allocators. These hooks
-    have important overhead in term of performances and memory usage:
-    see `Filter functions`_ to limit the overhead.
-
-    See also ``disable()`` and ``is_tracing()`` functions.
 
 
 ``take_snapshot()`` function:
@@ -201,8 +164,8 @@ Main functions
     Take a snapshot of traces of memory blocks allocated by Python using
     the ``get_traces()`` function. Return a new ``Snapshot`` instance.
 
-    The ``tracemalloc`` module must be enabled to take a snapshot, see
+    The ``tracemalloc`` module must be tracing memory allocations to take a
-    the the ``enable()`` function.
+    snapshot, see the the ``start()`` function.
 
     See also ``get_traces()`` and ``get_object_traceback()`` functions.
 
@@ -235,8 +198,8 @@ has a size of 32 bytes and was allocated at ``x.py:7``, line called from line
     Get the traceback where the Python object *obj* was allocated.
     Return a tuple of ``(filename: str, lineno: int)`` tuples.
 
-    Return ``None`` if the ``tracemalloc`` module is disabled or did not
+    Return ``None`` if the ``tracemalloc`` module is not tracing memory
-    trace the allocation of the object.
+    allocations or did not trace the allocation of the object.
 
     See also ``gc.get_referrers()`` and ``sys.getsizeof()`` functions.
 
@@ -258,8 +221,8 @@ has a size of 32 bytes and was allocated at ``x.py:7``, line called from line
     ``(filename: str, lineno: int)`` tuples.
 
     The list of traces do not include memory blocks allocated before the
-    ``tracemalloc`` module was enabled nor memory blocks ignored by
+    ``tracemalloc`` module started to trace memory allocations nor memory
-    filters (see ``get_filters()``).
+    blocks ignored by filters (see ``get_filters()``).
 
     The list is not sorted. Take a snapshot using ``take_snapshot()``
     and use the ``Snapshot.statistics()`` method to get a sorted list of
@@ -268,7 +231,8 @@ has a size of 32 bytes and was allocated at ``x.py:7``, line called from line
     Tracebacks of traces are limited to ``traceback_limit`` frames. Use
     ``set_traceback_limit()`` to store more frames.
 
-    Return an empty list if the ``tracemalloc`` module is disabled.
+    Return an empty list if the ``tracemalloc`` module is not tracing memory
+    allocations.
 
     See also ``take_snapshot()`` and ``get_object_traceback()``
     functions.
@@ -308,8 +272,6 @@ memory allocations in the ``tracemalloc`` module
 By default, there is one exclusive filter to ignore Python memory blocks
 allocated by the ``tracemalloc`` module.
 
-Tracing can be also be disabled temporarily using the ``disable()`` function.
-
 Use the ``get_tracemalloc_memory()`` function to measure the memory usage.
 See also the ``set_traceback_limit()`` function to configure how many
 frames are stored.