Python core developers

Stefan Behnel | 7 Aug 2012 22:52

PEP 366 is unclear about what it specifies

Hi,

could someone please add a sentence to PEP 366 that describes the actual
content of the new "__package__" attribute (and thus, the PEP)?

http://www.python.org/dev/peps/pep-0366/

I had to read through almost the entire document to be assured that
"__package__" is really supposed to contain a string and I had a hard time
nailing down its content. The only real hint in there is the example, and
even that is ambiguous.

Please change the first paragraph in the "proposed change" section to this:

"""
The major proposed change is the introduction of a new module level
[NEW]string[/NEW] attribute, __package__.[NEW:] It contains the fully
qualified name of the package that the module lives in, without the module
name itself[/NEW]. When it is present, ...
"""

Thanks,

Stefan

headers

Brett Cannon | 7 Aug 2012 23:26

Re: PEP 366 is unclear about what it specifies

On Tue, Aug 7, 2012 at 4:52 PM, Stefan Behnel <stefan_ml <at> behnel.de> wrote:

Hi,

could someone please add a sentence to PEP 366 that describes the actual
content of the new "__package__" attribute (and thus, the PEP)?

http://www.python.org/dev/peps/pep-0366/

I had to read through almost the entire document to be assured that
"__package__" is really supposed to contain a string and I had a hard time
nailing down its content. The only real hint in there is the example, and
even that is ambiguous.

Two things when it comes to understanding import now. One is that Barry's heavy rewrite of the import docs makes all of this much clearer and thus should be used as the reference over the PEPs, e.g. http://docs.python.org/dev/py3k/reference/import.html?highlight=__package__#loaders explains how __package__ should be set very clearly (yes, it references PEP 366 for nitty-gritty discussion and details, but honestly there isn't anything in the PEP that he didn't explain in the reference).

Two is that importlib makes it fairly straight-forward to read the source code to understand how some aspect of imports work and should be clear enough to not require reading PEPs to understand how a feature works.

Honestly, updating the PEPs constantly is a pain. We have code and docs already that most users follow, so worrying about constantly touching up PEPs is simply a third thing to have to keep track of that a majority of our users will never see. I know I don't plan to touch PEP 302 anymore in order to keep things straight in that doc as it's more hassle than it's worth.

<div>
<br><br><div class="gmail_quote">On Tue, Aug 7, 2012 at 4:52 PM, Stefan Behnel <span dir="ltr">&lt;<a href="mailto:stefan_ml <at> behnel.de" target="_blank">stefan_ml <at> behnel.de</a>&gt;</span> wrote:<br><blockquote class="gmail_quote">

Hi,<br><br>
could someone please add a sentence to PEP 366 that describes the actual<br>
content of the new "__package__" attribute (and thus, the PEP)?<br><br><a href="http://www.python.org/dev/peps/pep-0366/" target="_blank">http://www.python.org/dev/peps/pep-0366/</a><br><br>
I had to read through almost the entire document to be assured that<br>
"__package__" is really supposed to contain a string and I had a hard time<br>
nailing down its content. The only real hint in there is the example, and<br>
even that is ambiguous.<br>
</blockquote>
<div><br></div>
<div>Two things when it comes to understanding import now. One is that Barry's heavy rewrite of the import docs makes all of this much clearer and thus should be used as the reference over the PEPs, e.g.&nbsp;<a href="http://docs.python.org/dev/py3k/reference/import.html?highlight=__package__#loaders">http://docs.python.org/dev/py3k/reference/import.html?highlight=__package__#loaders</a>&nbsp;explains how __package__ should be set very clearly (yes, it references PEP 366 for nitty-gritty discussion and details, but honestly there isn't anything in the PEP that he didn't explain in the reference).</div>

<div><br></div>
<div>Two is that importlib makes it fairly straight-forward to read the source code to understand how some aspect of imports work and should be clear enough to not require reading PEPs to understand how a feature works.</div>

<div><br></div>
<div>Honestly, updating the PEPs constantly is a pain. We have code and docs already that most users follow, so worrying about constantly touching up PEPs is simply a third thing to have to keep track of that a majority of our users will never see. I know I don't plan to touch PEP 302 anymore in order to keep things straight in that doc as it's more hassle than it's worth.</div>

</div>
</div>

headers

Martin v. Löwis | 8 Aug 2012 00:25

Re: PEP 366 is unclear about what it specifies

> Honestly, updating the PEPs constantly is a pain.

Please understand that Stefan's request is not about updating the PEP
in order to match the current implementation - I agree that this is a
pain, and should not be done. Consequentially, relying on the PEPs
to understand what CPython does is also flawed.

However, what Stefan requests is that the PEP be changed to say what
really is the minimum requirement for acceptance - that the PEP actually
says what the proposed change is. What it currently does say is
the "change is the introduction of a new module level attribute, 
__package__". It nowhere says what value this attribute will have;
setting it to math.PI would be conforming, but clearly not intended.
The only occurrence of the word "string" is the sentence
"Note that setting __package__ to the empty string explicitly is 
permitted". So we know at least one possible value of the attribute:
the empty string - but that still clearly isn't the intention of the
PEP.

Of course, it's up to the PEP author to make a change, and perhaps
(to some degree) to non-author committers (who all can take the
role of a PEP editor, acknowledging that the proposed change
is editorial).

FWIW, the documentation (simple_stmts.rst) says that __package__
(if present) is "the name of package that contains the module or
package".

Regards,
Martin

headers

Nick Coghlan | 8 Aug 2012 01:00

Re: PEP 366 is unclear about what it specifies

I'm pretty sure the PEP already limits it to the same type as__name__, but I'll check. We may have assumed that was obvious, so nobody noticed I had left it out at the time.

--
Sent from my phone, thus the relative brevity :)

<div>
<p>I'm pretty sure the PEP already limits it to the same type as__name__, but I'll check. We may have assumed that was obvious, so nobody noticed I had left it out at the time. </p>
<p>--<br>
Sent from my phone, thus the relative brevity :) </p>
</div>