PEP 657: Update the env variable name and the C-API and add some clar…

…ifications (#2015)

pep-0657.rst

@@ -191,11 +191,16 @@ this PEP:
   four-element tuples containing the full location of every instruction
   (including start line, end line, start column offset and end column offset)
   or ``None`` if the code object was created without the offset information.
-* Three new C-API functions, ``PyCode_Addr2EndLine``, ``PyCode_Addr2StartOffset``
-  and ``PyCode_Addr2EndOffset`` will be added that can obtain the end line, the
-  start column offsets and the end column offset respectively given the index
-  of a bytecode instruction. These functions will return 0 if the information
-  is not available.
+* One new C-API function: ::
+
+    int PyCode_Addr2Location(
+        PyCodeObject *co, int addr,
+        int *startline, int *startcolumn,
+        int *endline, int *endcolumn)
+
+  will be added so the end line, the start column offsets and the end column
+  offset can be obtained given the index of a bytecode instruction. This
+  function will set the values to 0 if the information is not available.
 
 The internal storage, compression and encoding of the information is left as an
 implementation detail and can be changed at any point as long as the public API
@@ -311,18 +316,22 @@ storage and memory overhead and to allow third party tools and other
 programs that are currently parsing tracebacks to catch up the following
 methods will be provided to deactivate this feature:
 
-* A new environment variable: ``PYNODEBUGRANGES``.
+* A new environment variable: ``PYTHONNODEBUGRANGES``.
 * A new command line option for the dev mode: ``python -Xnodebugranges``.
 
 If any of these methods are used, the Python compiler will **not** populate
 code objects with the new information (``None`` will be used instead) and any
 unmarshalled code objects that contain the extra information will have it stripped
-away and replaced with ``None``). This method allows users to:
+away and replaced with ``None``). Additionally, the traceback machinery will not
+show the extended location information even if the information was present.
+This method allows users to:
 
 * Create smaller ``pyc`` files by using one of the two methods when said files
   are created.
 * Don't load the extra information from ``pyc`` files if those were created with
   the extra information in the first place.
+* Deactivate the extra information when displaying tracebacks (the caret characters
+  indicating the location of the error).
 
 Doing this has a **very small** performance hit as the interpreter state needs
 to be fetched when code objects are created to look up the configuration.