various tweaks

testing the current patch turned up a shortcoming.  When the bytecode base
is defined, it's not safe to delete the source code.  The bytecode file
generated won't be found.

pep-0304.txt

@@ -29,28 +29,52 @@ Proposal
 ========
 
 Add a new environment variable, PYTHONBYTECODEBASE, to the mix of
-environment variables which Python understands.  Its interpretation
-is:
+environment variables which Python understands.  PYTHONBYTECODEBASE is
+interpreted as follows:
 
-- If not present Python bytecode is generated in exactly the same way
-  as is currently done.  sys.bytecodebase is set to the root
-  directory (either / on Unix or the root directory of the startup
-  drive -- typically ``C:\`` -- on Windows).
+- If not defined, Python bytecode is generated in exactly the same way
+  as is currently done.  sys.bytecodebase is set to the root directory
+  (either / on Unix or the root directory of the startup drive --
+  typically ``C:\`` -- on Windows).
 
-- If present and it refers to an existing directory,
-  sys.bytecodebase is set to that directory and bytecode files
-  are written into a directory structure rooted at that location.
+- If defined and it refers to an existing directory to which the user
+  has write permission, sys.bytecodebase is set to that directory and
+  bytecode files are written into a directory structure rooted at that
+  location.
 
-- If present but empty, sys.bytecodebase is set to None and
-  generation of bytecode files is suppressed altogether.
-
-- If present and it does not refer to an existing directory, a warning
-  is displayed, sys.bytecodebase is set to None and generation
+- If defined but empty, sys.bytecodebase is set to None and generation
   of bytecode files is suppressed altogether.
 
-After startup, all runtime references are to sys.bytecodebase,
-not the PYTHONBYTECODEBASE environment variable.  sys.path is not
-modified.
+- If defined and one of the following is true::
+
+  * it does not refer to a directory,
+
+  * it refers to a directory, but not one for which the user has write
+    permission
+
+  a warning is displayed, sys.bytecodebase is set to None and
+  generation of bytecode files is suppressed altogether.
+
+After startup initialization, all runtime references are to
+sys.bytecodebase, not the PYTHONBYTECODEBASE environment variable.
+sys.path is not modified.
+
+From the above, we see sys.bytecodebase can only take on two valid
+types of values: None or a string referring to a valid directory on
+the system.
+
+During import, this extension works as follows:
+
+- The normal search for a module is conducted.  The search order is
+  roughly: dynamically loaded extension module, Python source file,
+  Python bytecode file.  The only time this mechanism comes into play
+  is if a Python source file is found.
+
+- Once we've found a source module, an attempt to read a byte-compiled
+  file in the same directory is made.  (This is the same as before.)
+
+- If no byte-compiled file is found, an attempt to read a
+  byte-compiled file from the augmented directory is made.
 
 Note that this PEP is explicitly *not* about providing
 module-by-module or directory-by-directory control over the
@@ -200,6 +224,14 @@ Issues
   considered yet.  In fact, the best way to implement this idea might
   be as an import hook.  See PEP 302. [5]_
 
+- In the current (pre-PEP 304) environment, it is safe to delete a
+  source file after the corresponding bytecode file has been created,
+  since they reside in the same directory.  With PEP 304 as currently
+  defined, this is not the case.  A bytecode file in the augmented
+  directory is only considered when the source file is present and it
+  thus never considered when looking for module files ending in
+  ".pyc".  I think this behavior may have to change.
+
 
 Examples
 ========