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". (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.
* 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.
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.
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? (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. -jJ