On Thu, 16 Dec 2010 07:15:02 +0100, eric.araujo email@example.com wrote:
--- 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.
-.. 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
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
Thanks for double-checking.
When I first looked into compileall, I opened http://bugs.python.org/issue10454 where I state that I find the description of those options unclear or even not understandable, so your diagnosis that I just copied text is right.
A rewrite to fully cover the module functionality in clear English is needed. Your email was very helpful; can you turn it into a patch and post it to the bug? Thanks in advance.