On 25 February 2015 at 20:12, Jim J. Jewett <jimjjewett@gmail.com> wrote:
On Wed, Feb 25, 2015 at 2:33 PM, Paul Moore <p.f.moore@gmail.com> wrote:
On 25 February 2015 at 17:06, Paul Moore <p.f.moore@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