[Python-Dev] [Python-checkins] r87310 - in python/branches/release27-maint: Doc/library/compileall.rst Lib/compileall.py

[R. David Murray]

On Thu, 16 Dec 2010 07:15:02 +0100, eric.araujo <python-checkins at python.org> wrote:
> Modified: python/branches/release27-maint/Doc/library/compileall.rst
> ==============================================================================
> --- python/branches/release27-maint/Doc/library/compileall.rst	(original)
> +++ python/branches/release27-maint/Doc/library/compileall.rst	Thu Dec 16 07:15:02 2010
> @@ -1,4 +1,3 @@
> -
>  :mod:`compileall` --- Byte-compile Python libraries
>  ===================================================
>  
> @@ -50,14 +49,14 @@
>  
>     Expand list with its content (file and directory names).

I realize you didn't write this line, but note that '-' is accepted as
an argument and means "read the list from stdin".

> -.. versionadded:: 2.7
> -   The ``-i``  option.
> +.. versionchanged:: 2.7
> +   Added the ``-i``  option.
>  
>  
>  Public functions
>  ----------------
>  
> -.. function:: compile_dir(dir[, maxlevels[, ddir[, force[,  rx[, quiet]]]]])
> +.. function:: compile_dir(dir[, maxlevels[, ddir[, force[, rx[, quiet]]]]])
>  
>     Recursively descend the directory tree named by *dir*, compiling all :file:`.py`
>     files along the way.  The *maxlevels* parameter is used to limit the depth of
> @@ -72,6 +71,23 @@
>     If *quiet* is true, nothing is printed to the standard output in normal
>     operation.
>  
> +
> +.. function:: compile_file(fullname[, ddir[, force[, rx[, quiet]]]])
> +
> +   Compile the file with path *fullname*.  If *ddir* is given, it is used as the
> +   base path from  which the filename used in error messages will be generated.
> +   If *force* is true, modules are re-compiled even if the timestamp is up to
> +   date.

Although this is copied from the other descriptions of *ddir*, it and the
other instances (and the description of the -d option) should all really
be fixed.  As I discovered when writing the tests for the -d option,
what ddir is is the path that is "baked in" to the .pyc file.  In very
old versions of Python that meant it was the path that would show up in
tracebacks as the path to the source file.  In modern Pythons the ddir
path shows up if and only if the .py file does not exist and the .pyc
file is being run directly.  In 3.2, this means it will never show up
normally, since you can't even run the .pyc file without moving it out of
__pycache__.  Which means 'ddir' is henceforth useful only to those people
who want to package sourceless distributions of the python code.  (If you
want to see this in action check out the -d tests in test_compileall.)

So, 'in error messages' really means 'in tracebacks if the .py file
doesn't exist'.

--
R. David Murray                                      www.bitdance.com