PEP 488: be explicit about what bytecode file names will be

pep-0488.txt

@@ -19,7 +19,7 @@ This PEP proposes eliminating the concept of PYO files from Python.
 To continue the support of the separation of bytecode files based on
 their optimization level, this PEP proposes extending the PYC file
 name to include the optimization level in the bytecode repository
-directory when it's called for (i.e., the ``__pycache__`` directory).
+directory when there are optimizations applied.
 
 
 Rationale
@@ -78,10 +78,15 @@ as well as to avoid having to regenerate optimized bytecode files
 needlessly in the `__pycache__` directory, the optimization level
 used to generate the bytecode file will be incorporated into the
 bytecode file name. When no optimization level is specified, the
-pre-PEP ``.pyc`` file name will be used (i.e., no change in file name
-semantics). This increases backwards-compatibility while also being
-more understanding of Python implementations which have no use for
-optimization levels (e.g., PyPy[10]_).
+pre-PEP ``.pyc`` file name will be used (i.e., no optimization level
+will be specified in the file name). For example, a source file named
+``foo.py`` in CPython 3.5 could have the following bytecode files
+based on the interpreter's optimization level (none, ``-O``, and
+``-OO``):
+
+  - 0: ``foo.cpython-35.pyc``
+  - 1: ``foo.cpython-35.opt-1.pyc``
+  - 2: ``foo.cpython-35.opt-2.pyc``
 
 Currently bytecode file names are created by
 ``importlib.util.cache_from_source()``, approximately using the
@@ -113,10 +118,15 @@ version as specified by the cache tag. It also lends to the use of
 the period in the file name to delineate semantically different
 concepts.
 
-For example, if ``-OO`` had been passed to the interpreter then instead
-of ``importlib.cpython-35.pyo`` the file name would be
+For example, if ``-OO`` had been passed to the interpreter then
+instead of ``importlib.cpython-35.pyo`` the file name would be
 ``importlib.cpython-35.opt-2.pyc``.
 
+Leaving out the new ``opt-`` tag when no optimization level is
+applied should increase backwards-compatibility. This is also more
+understanding of Python implementations which have no use for
+optimization levels (e.g., PyPy[10]_).
+
 It should be noted that this change in no way affects the performance
 of import. Since the import system looks for a single bytecode file
 based on the optimization level of the interpreter already and