classification
Title: Clarify compileall command-line options
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.1, Python 3.2, Python 2.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, eric.araujo, georg.brandl, python-dev, r.david.murray
Priority: normal Keywords: easy, patch

Created on 2010-11-18 16:11 by eric.araujo, last changed 2011-09-02 16:03 by python-dev. This issue is now closed.

Files
File name Uploaded Description Edit
compileall_help.patch r.david.murray, 2010-12-17 01:15
compileall-help-2.7.diff eric.araujo, 2011-05-29 16:22
compileall-help-3.x.diff eric.araujo, 2011-05-29 16:23 review
Messages (9)
msg121469 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-18 16:11
This is the help text of compileall:

 usage: python compileall.py [-l] [-f] [-q] [-d destdir] [-x regexp] [-i list] [directory|file ...]
 -l: don't recurse down
 -f: force rebuild even if timestamps are up-to-date
 -q: quiet operation
 -d destdir: purported directory name for error messages
    if no directory arguments, -l sys.path is assumed
 -x regexp: skip files matching the regular expression regexp
    the regexp is searched for in the full path of the file
 -i list: expand list with its content (file and directory names)
 -b: Produce legacy byte-compile file paths

1) I do not understand the help of -d and -i.  Experimenting with the script, reading the code and eventually looking at the file history would certainly clear that.

2) The short usage line at the top also lacks mention of “-b”.

3) (minor) I want to rephrase -x, -d and -b.

Bug week-end candidate!
msg121471 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2010-11-18 16:17
In addition, the line “if no directory arguments, -l sys.path is assumed” seems misplaced.
msg124171 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-12-17 01:15
Here is a proposed patch to both docs and help output.  The help output now looks like this:

usage: compileall.py [-h] [-l] [-f] [-q] [-b] [-d DESTDIR] [-x REGEXP]
                     [-i FILE]
                     [FILE|DIR [FILE|DIR ...]]

Utilities to support installing Python libraries.

positional arguments:
  FILE|DIR    zero or more file and directory names to compile; if no
              arguments given, defaults to the equivalent of -l sys.path

optional arguments:
  -h, --help  show this help message and exit
  -l          don't recurse into subdirectories
  -f          force rebuild even if timestamps are up to date
  -q          output only error messages
  -b          use legacy (pre-PEP3147) compiled file locations
  -d DESTDIR  directory to prepend to file paths for use in compile time
              tracebacks and in runtime tracebacks in cases where the source
              file is unavailable
  -x REGEXP   skip files matching the regular expression. The regexp is
              searched for in the full path to each file considered for
              compilation.
  -i FILE     add all the files and directories listed in FILE to the list
              considered for compilation. If "-", names are read from stdin.
msg124213 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2010-12-17 15:42
+1 -- Didn't read through all of the diff, but in general I trust you enough to believe that the new version is better than the old :)
msg124227 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2010-12-17 16:31
Committed in r87338.  Backporting the relevant bits will be a bit of a pain, anyone who feels like doing it is welcome to.  I may or may not get to it myself.
msg137194 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-05-29 16:22
Hi David, I made this patch to port the improvements you made to 2.7.  The new usage message looks like this:

usage: python compileall.py [-l] [-f] [-q] [-d destdir] [-x regexp] [-i list] [directory|file ...]

arguments: zero or more file and directory names to compile; if no arguments given, 
           defaults to the equivalent of -l sys.path

options:
-l: don't recurse into subdirectories
-f: force rebuild even if timestamps are up-to-date
-q: output only error messages
-d destdir: directory to prepend to file paths for use in compile-time tracebacks and in
            runtime tracebacks in cases where the source file is unavailable
-x regexp: skip files matching the regular expression regexp; the regexp is searched for
           in the full path of each file considered for compilation
-i file: add all the files and directories listed in file to the list considered for
         compilation; if "-", names are read from stdin

I noticed some minor style issues, so I (IMO) improved them in my 2.7 patch and made a 3.x patch with the same minor touch-ups.
msg138639 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2011-06-19 16:12
Looks fine except for your changes to the parenthesized defaults.  Those should be '0' and 'False' for 2.7 and 3.x, respectively, since that's what they areally are.
msg143405 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-09-02 15:45
New changeset 755a57f987ca by Éric Araujo in branch '3.2':
#10454: a few edits to compileall help messages
http://hg.python.org/cpython/rev/755a57f987ca

New changeset 892e0ee4ca32 by Éric Araujo in branch 'default':
Merge doc changes from 3.2 (#10454, #12298)
http://hg.python.org/cpython/rev/892e0ee4ca32
msg143406 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2011-09-02 16:03
New changeset 4ae85348e3e8 by Éric Araujo in branch '2.7':
Clarify compileall command-line options (#10454).
http://hg.python.org/cpython/rev/4ae85348e3e8
History
Date User Action Args
2011-09-02 16:03:04python-devsetmessages: + msg143406
2011-09-02 15:45:01python-devsetnosy: + python-dev
messages: + msg143405
2011-06-19 16:12:23r.david.murraysetmessages: + msg138639
2011-05-29 16:23:13eric.araujosetfiles: + compileall-help-3.x.diff
2011-05-29 16:22:52eric.araujosetfiles: + compileall-help-2.7.diff

messages: + msg137194
2010-12-17 16:31:16r.david.murraysetstatus: open -> closed
nosy: georg.brandl, eric.araujo, r.david.murray, docs@python
messages: + msg124227

resolution: fixed
stage: patch review -> resolved
2010-12-17 15:42:29georg.brandlsetnosy: + georg.brandl
messages: + msg124213
2010-12-17 01:15:26r.david.murraysetfiles: + compileall_help.patch

messages: + msg124171
keywords: + patch
stage: needs patch -> patch review
2010-12-16 16:41:38eric.araujosetnosy: + r.david.murray
2010-11-18 16:17:59eric.araujosetmessages: + msg121471
2010-11-18 16:11:54eric.araujosettitle: Clarify compileall options -> Clarify compileall command-line options
2010-11-18 16:11:29eric.araujocreate