On 25 February 2015 at 20:12, Jim J. Jewett <jimjjew...@gmail.com> wrote: > On Wed, Feb 25, 2015 at 2:33 PM, Paul Moore <p.f.mo...@gmail.com> wrote: >> On 25 February 2015 at 17:06, Paul Moore <p.f.mo...@gmail.com> wrote: > >> I've included the resulting API >> documentation below. It looks pretty good to me. > > Me too. I have a few nits anyhow. > >> .. function:: create_archive(directory, target=None, interpreter=None, >> main=None) > >> Create an application archive from *source*. The source can be any >> of the following: > > (1) *source* makes me think of source code, as opposed to binary. > This is only a small objection, in part because I can't think of > anything better. > > (2) If you do keep *source*, I think that the the "directory" > parameter should be renamed to "source".
Yep, that's a typo. Think of it as source -> target as opposed to source code and it's fine :-) > (3) >> * The name of an existing application archive file, in which case the >> file is copied to the target. > > ==> > >> * The name of an existing application archive file, in which case the >> file is copied (possibly with changes) to the target. > > My concern is that someone who does want just another copy will use > this, see "copied", not read the other options, and be surprised when > the shebang is dropped. Hmm, how about "... the content of the archive is copied to the target with a replacement shebang line"? > >> * A file object open for reading in bytes mode. The content of the >> file should be an application archive, and the file object is >> assumed to be positioned at the start of the archive. > > I like this way of ducking the "does it need to be seekable" question. :-) >> The *target* argument determines where the resulting archive will be >> written: >> >> * If it is the name of a file, the archive will be written to that >> file. > > (4) Note that the filename is not required to end with pyz, although > that is good practice. Or maybe just be explicit that the function > itself does not add a .pyz, and assumes that the caller will do so > when appropriate. Hmm, I thought I'd added an explanation. Maybe I did that somewhere else and missed it here. I'll clarify. >> The *interpreter* argument specifies the name of the Python >> interpreter with which the archive will be executed. ... >> ... Omitting the *interpreter* results in no shebang line being >> written. > > (5) even if there was an explicit shebang line in the source archive. I'll clarify the wording. >> If an interpreter is specified, and the target is a >> filename, the executable bit of the target file will be set. > > (6) (target is a filename, or None) Or does that clarification just > confuse the issue, and only benefit people so careful they'll verify > it themselves anyway? Probably :-) How about "if the target is a real file" or "unless the target is a file-like object"? But in all honesty I think it's fine as is. > (7) That is a good idea, but not quite as clear cut as it sounds. On > unix, there are generally 3 different executable bits specifying *who* > can run it. Setting the executable bit only for the owner is probably > a conservative but sensible default. I know, but excuse the naivete of a Windows user. I'm inclined to leave it as it is and direct people to read the source if they care that much (I actually used I_EXEC, which is what I've seen other code use). The alternative is to not set the executable bit at all and make the user do it as a separate step. My instinct is that doing that would be less user friendly, but my instincts on what's good Unix behaviour aren't strong... Thanks for the comments. Paul _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
