[Python-Dev] Request for Pronouncement: PEP 441 - Improving Python ZIP Application Support

[Paul Moore]

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