Re: [Python-Dev] Best practice for documentation for std lib

[Larry Hastings]

On 09/23/2013 03:44 AM, Guido van Rossum wrote:
On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy > wrote:


I am gradually changing Idle docstrings, though only Idle
developers will ever see them. Writing a 60 char summary forces a
clear understanding of the function.


Glad you like it. I still do, too, but I've given up hope to convince 
all core developers to stick to this style. :-(


... Argument Clinic to the rescue?  Since the last time this subject 
came up, Clinic has started enforcing a summary line in docstrings. I 
didn't realize it had to be 60 columns though, should I add that? Is the 
entire docstring supposed to be 60 columns max?


p.s. status update: AC is done enough to be worth considering checking 
in.  Now I have to finish the PEP and write the documentation.



//arry/
___
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

Re: [Python-Dev] sys.intern should work on bytes

[Hrvoje Niksic]

On 09/20/2013 06:50 PM, PJ Eby wrote:

On Fri, Sep 20, 2013 at 9:54 AM, Jesus Cea  wrote:

Why str/bytes doesn't support weakrefs, beside memory use?


The typical use case for weakrefs is to break reference cycles,


Another typical use case, and the prime reason why languages without 
reference counting tend to introduce weak references, is managing object 
caches with automatic disposal of otherwise unused items. Such a cache 
is rarely necessary for primitive objects, so Python's choice to spare 
memory for weakrefs is quite justified.


However, if one wanted to implement their own sys.intern(), inability to 
refer to strings would become a problem. This is one reason why 
sys.intern() directly fiddles with reference counts instead of reusing 
the weakref machinery. (The other of course being that intern predates 
weakrefs by many years.)


___
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

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Nick Coghlan]

On 23 September 2013 16:11, Greg Ewing  wrote:
> Guido van Rossum wrote:
>>
>> Somehow "unraisable" sounds too technical,
>
>
> It's not even really accurate. It's been raised, it just
> can't be propagated any further. But "unpropagatable
> exception" would be a bit of a mouthful.

I felt I needed a reminder of the context where this string gets
printed, so I created this toy example:

>>> class C:
... def __del__(self):
... raise RuntimeError("Going away now")
...
>>> x = C()
>>> del x
Exception ignored in: >
Traceback (most recent call last):
  File "", line 3, in __del__
RuntimeError: Going away now

Here's what I suggest changing that error to:

>>> del x
Unraisable exception suppressed when calling >
Traceback (most recent call last):
  File "", line 3, in __del__
RuntimeError: Going away now

First and foremost, "Unraisable exception suppressed" should be quite
search engine friendly. The only current hits for that are on archived
versions of this thread, whereas the existing "Exception ignored"
sends you down a rabbit hole of Stack Overflow answers related to
broken pipe handling. If we create a new FAQ entry for "What does
'Exception ignored' or 'Unraisable exception suppressed' mean?" when
making the change for 3.4, then that will definitely help 3.4 users
and may eventually help users of other versions as well :)

Secondly, it concisely explains exactly what is going on, so
developers that look it up once should be able to remember the meaning
in the future:

- the given exception was suppressed (*what* happened)
- it was suppressed because Python couldn't raise it any further
(*why* it happened)

I think it's OK for the terms to be a little technical and arcane
because problems relating to broken finalizers and failures during
interpreter startup and shutdown *are* a little arcane.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncogh...@gmail.com   |   Brisbane, Australia
___
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

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Antoine Pitrou]

Le Mon, 23 Sep 2013 18:17:51 +1000,
Nick Coghlan  a écrit :
> 
> Here's what I suggest changing that error to:
> 
> >>> del x
> Unraisable exception suppressed when calling  of <__main__.C object at 0x7f98b8b61538>>
> Traceback (most recent call last):
>   File "", line 3, in __del__
> RuntimeError: Going away now

Why not simply "Exception automatically caught in  [...]" ?

Regards

Antoine.


___
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

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Nick Coghlan]

On 23 September 2013 18:45, Antoine Pitrou  wrote:
> Le Mon, 23 Sep 2013 18:17:51 +1000,
> Nick Coghlan  a écrit :
>>
>> Here's what I suggest changing that error to:
>>
>> >>> del x
>> Unraisable exception suppressed when calling > of <__main__.C object at 0x7f98b8b61538>>
>> Traceback (most recent call last):
>>   File "", line 3, in __del__
>> RuntimeError: Going away now
>
> Why not simply "Exception automatically caught in  C.__del__> [...]" ?

It only answers the "what" (i.e. the exception was automatically
caught), without addressing the "why" (i.e. because there wasn't
anything else useful the interpreter could do with it)

"Suppressed" also says more than "caught" does, since "caught and
reraised the exception" makes sense, while "suppressed and reraised
the exception" contradicts itself.

Cheers,
Nick.

-- 
Nick Coghlan   |   ncogh...@gmail.com   |   Brisbane, Australia
___
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

[Python-Dev] PEP 453 (pip bootstrapping) ready for pronouncement?

[Nick Coghlan]

With the last round of updates, I believe PEP 453 is ready for
Martin's pronouncement.

HTML: http://www.python.org/dev/peps/pep-0453/
Major diffs: http://hg.python.org/peps/rev/b2993450b32a

Many of the updates are just clarifications in response to questions,
but the actual significant changes are:

- the proposed module name is now "ensurepip" (thanks Antoine for that
suggestion)
- distros are granted considerable latitude to ensure the distro pip
package is used with the system Python installation, so long as they
ensure virtual environments continue to work as expected
- the two open questions regarding uninstallation and tweaking the
directory layout on Windows are decided in favour of the approaches
that were already documented in the PEP (since we hadn't received any
objections to them in earlier discussions)

Regards,
Nick.

=
PEP: 453
Title: Explicit bootstrapping of pip in Python installations
Version: $Revision$
Last-Modified: $Date$
Author: Donald Stufft ,
Nick Coghlan 
BDFL-Delegate: Martin von Löwis
Status: Draft
Type: Process
Content-Type: text/x-rst
Created: 10-Aug-2013
Post-History: 30-Aug-2013, 15-Sep-2013, 18-Sep-2013, 19-Sep-2013, 23-Sep-2013


Abstract


This PEP proposes that the `pip`_ package manager be made available by
default when installing CPython and when creating virtual environments
using the standard library's ``venv`` module via the ``pyvenv`` command line
utility).

To clearly demarcate development responsibilities, and to avoid
inadvertently downgrading ``pip`` when updating CPython, the proposed
mechanism to achieve this is to include an explicit `pip`_ bootstrapping
mechanism in the standard library that is invoked automatically by the
CPython installers provided on python.org.

The PEP also strongly recommends that CPython redistributors and other Python
implementations ensure that ``pip`` is available by default, or
at the very least, explicitly document the fact that it is not included.


Proposal


This PEP proposes the inclusion of an ``ensurepip`` bootstrapping module in
Python 3.4, as well as in the next maintenance releases of Python 3.3 and
2.7.

This PEP does *not* propose making pip (or any dependencies) directly
available as part of the standard library. Instead, pip will be a
bundled application provided along with CPython for the convenience
of Python users, but subject to its own development life cycle and able
to be upgraded independently of the core interpreter and standard library.


Rationale
=

Currently, on systems without a platform package manager and repository,
installing a third-party Python package into a freshly installed Python
requires first identifying an appropriate package manager and then
installing it.

Even on systems that *do* have a platform package manager, it is unlikely to
include every package that is available on the Python Package Index, and
even when a desired third-party package is available, the correct name in
the platform package manager may not be clear.

This means that, to work effectively with the Python Package Index
ecosystem, users must know which package manager to install, where to get
it, and how to install it. The effect of this is that third-party Python
projects are currently required to choose from a variety of undesirable
alternatives:

* Assume the user already has a suitable cross-platform package manager
  installed.
* Duplicate the instructions and tell their users how to install the
  package manager.
* Completely forgo the use of dependencies to ease installation concerns
  for their users.

All of these available options have significant drawbacks.

If a project simply assumes a user already has the tooling then beginning
users may get a confusing error message when the installation command
doesn't work. Some operating systems may ease this pain by providing a
global hook that looks for commands that don't exist and suggest an OS
package they can install to make the command work, but that only works
on systems with platform package managers (such as major Linux
distributions). No such assistance is available for Windows and
Mac OS X users. The challenges of dealing with this problem are a
regular feature of feedback the core Python developers receive from
professional educators and others introducing new users to Python.

If a project chooses to duplicate the installation instructions and tell
their users how to install the package manager before telling them how to
install their own project then whenever these instructions need updates
they need updating by every project that has duplicated them. This is
particular problematic when there are multiple competing installation
tools available, and different projects recommend different tools.

This specific problem can be partially alleviated by strongly promoting
``pip`` as the default installer and recommending that other projects
reference `pip's own bootstrapping instructions

Re: [Python-Dev] Best practice for documentation for std lib

[Walter Dörwald]

On 22.09.13 16:34, Brett Cannon wrote:


The rule of thumb I go by is the docstring should be enough to answer
the question "what args does this thing take and what does it do in
general to know it's the function I want and another one in the same
module?" quickly and succinctly; i.e. just enough so that help() reminds
you about details for a module you are already familiar with that might
come up while at the interpreter prompt. Everything else -- in-depth
discussion of the algorithms, extra examples, why you want to use this
function, etc. -- all go in the .rst docs.


It would be great if the docstring contained a link to the online 
documentation.


Servus,
   Walter

___
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

Re: [Python-Dev] Best practice for documentation for std lib

[Fred Drake]

On Mon, Sep 23, 2013 at 7:27 AM, Walter Dörwald  wrote:
> It would be great if the docstring contained a link to the online
> documentation.

The docstring itself, or the presentation generated by help() ?


  -Fred

-- 
Fred L. Drake, Jr.
"A storm broke loose in my mind."  --Albert Einstein
___
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

Re: [Python-Dev] Enum Eccentricities

[Chris Lambacher]

On Sun, Sep 22, 2013 at 10:41 PM, Zero Piraeus  wrote:

> I may be misunderstanding the use case given in the issue,
>

To clarify the use case, since it is my bug, this is so that the enum
values are always available for comparison. The exact use case is in Django
templates where a value comes from the database. If you want to compare you
either have to use __class__ which I would say is a code smell, or you have
to provide the Enum class. The code we are using for this is open source
http://github.com/tindie/django-tidyenum. An example of how this will be
used in practice is:

{% if object.state == object.state.completed %}
  some html
{% endif %}


> but it seems
> to me that having to use
>
> Color.red.__class__.blue
>
> (what is being complained about in the issue), while not exactly pretty,
> makes a lot more semantic sense than
>
> Color.red.blue
>
> ... which is just bizarre.
>

Any more bizarre than any other class that has properties of it's own type?

  a = 0
  a.real.numerator.real.numerator

It is only weird because we are not used to seeing classes where the
properties are instances of the class. I am not a core developer, but I
have been programming in Python for more than 10 years, and I (and the
other similarly experienced developers I work with) found that not having
access to the class level properties was weird (yes I am aware that they
are not actually class level properties but everywhere else Enum works hard
to make it look like they are. See for instance the __dir__ method:
http://hg.python.org/cpython/file/ed011b0d7daf/Lib/enum.py#l242).

-Chris

-- 
Christopher Lambacher
ch...@kateandchris.net
___
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

Re: [Python-Dev] Best practice for documentation for std lib

[Walter Dörwald]

On 23.09.13 15:38, Fred Drake wrote:


On Mon, Sep 23, 2013 at 7:27 AM, Walter Dörwald  wrote:

It would be great if the docstring contained a link to the online
documentation.


The docstring itself, or the presentation generated by help() ?


The presentation generated by help(), or the output of IPython's foo? or 
foo?? syntax.


Servus,
   Walter

___
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

Re: [Python-Dev] Best practice for documentation for std lib

[Antoine Pitrou]

Le Mon, 23 Sep 2013 15:51:27 +0200,
Walter Dörwald  a écrit :
> On 23.09.13 15:38, Fred Drake wrote:
> 
> > On Mon, Sep 23, 2013 at 7:27 AM, Walter Dörwald
> >  wrote:
> >> It would be great if the docstring contained a link to the online
> >> documentation.
> >
> > The docstring itself, or the presentation generated by help() ?
> 
> The presentation generated by help(), or the output of IPython's foo?
> or foo?? syntax.

Perhaps objects could gain some kind of optional __docurl__ attribute,
to avoid cluttering __doc__ with external links.
Not sure how that could be auto-generated, though (we certainly don't
want to maintain doc links manually).

Regards

Antoine.


___
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

Re: [Python-Dev] Best practice for documentation for std lib

[Guido van Rossum]

On Mon, Sep 23, 2013 at 4:27 AM, Walter Dörwald wrote:

> It would be great if the docstring contained a link to the online
> documentation.
>

That would have to be a feature of help(), not hardcoded in each docstring.

-- 
--Guido van Rossum (python.org/~guido)
___
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

Re: [Python-Dev] Best practice for documentation for std lib

[Guido van Rossum]

On Mon, Sep 23, 2013 at 12:57 AM, Larry Hastings  wrote:

>  On 09/23/2013 03:44 AM, Guido van Rossum wrote:
>
>  On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy  wrote:
>
>> I am gradually changing Idle docstrings, though only Idle developers will
>> ever see them. Writing a 60 char summary forces a clear understanding of
>> the function.
>
>
>  Glad you like it. I still do, too, but I've given up hope to convince
> all core developers to stick to this style. :-(
>
>
> ... Argument Clinic to the rescue?  Since the last time this subject came
> up, Clinic has started enforcing a summary line in docstrings.  I didn't
> realize it had to be 60 columns though, should I add that?  Is the entire
> docstring supposed to be 60 columns max?
>

I think 60 is just a guideline. In stdlib .py source code I want it not to
extend beyond the 79th column (see recent PEP 8 argument). For a typical
class, where the docstring is indented 4 spaces, that leaves 72 characters
for the summary line (including a final period!). For a method it's 68 due
to the extra indent.

FWIW I also prefer having the summary line on the same line as the opening
""":

def foo():
"""This is the summary.

This is the rest.
"""


> p.s. status update: AC is done enough to be worth considering checking
> in.  Now I have to finish the PEP and write the documentation.
>

-- 
--Guido van Rossum (python.org/~guido)
___
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

Re: [Python-Dev] Enum Eccentricities

[Steven D'Aprano]

On Mon, Sep 23, 2013 at 07:53:00AM -0700, Guido van Rossum wrote:

> there is no rule that because you can
> access something on the class you should be able to access it on the
> instance. Try asking an instance for its class's __mro__ or __bases__.

It might not be a rule, but it's certainly the norm. I reckon that class 
attributes that aren't accessible from the instance are significantly 
more surprising than Color.red.blue.

I know I'm in a minority here, but Color.red.blue seems obvious and 
straightforward to me. The fact that it doesn't work surprises me. Given 
that 

instance = Color.red
assert isinstance(instance, Color)  # well of course it is
assert hasattr(Color, "blue")

I would expect instance.blue to work, and I'm completely at a loss as to 
how Enum has managed to prevent it.



-- 
Steven
___
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

Re: [Python-Dev] Enum Eccentricities

[Guido van Rossum]

On Mon, Sep 23, 2013 at 6:45 AM, Chris Lambacher wrote:

>
> On Sun, Sep 22, 2013 at 10:41 PM, Zero Piraeus  wrote:
>
>> I may be misunderstanding the use case given in the issue,
>>
>
> To clarify the use case, since it is my bug, this is so that the enum
> values are always available for comparison. The exact use case is in Django
> templates where a value comes from the database. If you want to compare you
> either have to use __class__ which I would say is a code smell, or you have
> to provide the Enum class. The code we are using for this is open source
> http://github.com/tindie/django-tidyenum. An example of how this will be
> used in practice is:
>
> {% if object.state == object.state.completed %}
>   some html
> {% endif %}
>

Now I see your use case. But I disagree that the best solution is to allow
accessing the enum values as attributes on object.state -- I would
recommend using __class__ to make it clear to the reader what's going on,
or to add the right Enum subclass to your template parameters. Tbe
expression you show in your example here will just baffle most readers who
haven't thought deeply about the issue.

(How would you compare a value that is a timedelta with a known timedelta?
You'd have to import the datetime module or use __class__, right?)


>  but it seems
>> to me that having to use
>>
>> Color.red.__class__.blue
>>
>> (what is being complained about in the issue), while not exactly pretty,
>> makes a lot more semantic sense than
>>
>> Color.red.blue
>>
>> ... which is just bizarre.
>>
>
> Any more bizarre than any other class that has properties of it's own type?
>

Yes, because you rarely if ever see them accessed that way.


>   a = 0
>   a.real.numerator.real.numerator
>

But that's different! Each of the attributes here (.real, .numerator) is
defined as an instance attribute.


>
> It is only weird because we are not used to seeing classes where the
> properties are instances of the class. I am not a core developer, but I
> have been programming in Python for more than 10 years, and I (and the
> other similarly experienced developers I work with) found that not having
> access to the class level properties was weird (yes I am aware that they
> are not actually class level properties but everywhere else Enum works hard
> to make it look like they are. See for instance the __dir__ method:
> http://hg.python.org/cpython/file/ed011b0d7daf/Lib/enum.py#l242).
>

Sorry to burst your bubble, but there is no rule that because you can
access something on the class you should be able to access it on the
instance. Try asking an instance for its class's __mro__ or __bases__.

-- 
--Guido van Rossum (python.org/~guido)
___
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

Re: [Python-Dev] Best practice for documentation for std lib

[R. David Murray]

On Sun, 22 Sep 2013 16:19:21 -0700, Guido van Rossum  wrote:
> On Sun, Sep 22, 2013 at 2:41 PM, Xavier Morel wrote:
> 
> > The points here are that there's a single source of truth (so we can't
> > have conflicting docstring and rst documentation), and documentation
> > becoming outdated can be noticed from both docstring and published
> > documentation.

Another thing that hasn't been mentioned about docstrings vs rst docs,
is that even when the text is identical, it generally isn't.  By that I
mean the rst docs have ReST markup, but the docstrings don't.  So using
autodoc doesn't just mean adding autodoc to our doc building toolchain,
it *also* means adding support in pydoc for turning ReST into plain text.
And that still leaves the markup in the docstring, where it will be very
distracting while actually reading the source code.  Which, unlike other
commenters, I spend more time doing that than I do using help (and that
doesn't apply to just the stdlib for me).
 
> >
> Another case of DRY madness.
> 
> It seems too many programmers see documentation as unpleasant red tape they
> want to cut through as quickly as possible, instead of an opportunity to
> communicate with their *users*. To the contrary: users should be the most
> important people in the world if you're writing code that's worth
> documenting at all.

I won't pretend that I find having to edit two places when updating
fundamental documentation pleasant, but...

I find that as often as not I want to word things *differently* in
the docstring vs the rst docs for the same function.  Sometimes the
difference is subtle; most often it is an omission of detail along the
lines Guido suggests.  But when writing the rst version, it generally
isn't that I'm simply continuing on after the first paragraph; instead,
the organization of even that starting text is different, because
I'm aware that the reader has a different mindset (quick help vs
reference documentation) when reading the two texts.[*]

As with the question of NEWS items versus checkin messages, the intended
audience, or in this case the mindset of the intended audience, is
*different*, and so the text should very often be different as well[**].

--David

[*] I posit that this is even *more* true for those who say they only
use help and only fall back to the full docs when the docstrings
aren't enough.

[**] I also wonder if long function docstrings have a negative impact on
usability in IDEs that pop up windows with docstring information in them.
___
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

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Antoine Pitrou]

On Mon, 23 Sep 2013 18:51:04 +1000
Nick Coghlan  wrote:
> On 23 September 2013 18:45, Antoine Pitrou  wrote:
> > Le Mon, 23 Sep 2013 18:17:51 +1000,
> > Nick Coghlan  a écrit :
> >>
> >> Here's what I suggest changing that error to:
> >>
> >> >>> del x
> >> Unraisable exception suppressed when calling  >> of <__main__.C object at 0x7f98b8b61538>>
> >> Traceback (most recent call last):
> >>   File "", line 3, in __del__
> >> RuntimeError: Going away now
> >
> > Why not simply "Exception automatically caught in  > C.__del__> [...]" ?
> 
> It only answers the "what" (i.e. the exception was automatically
> caught), without addressing the "why" (i.e. because there wasn't
> anything else useful the interpreter could do with it)

Yes, but I agree with Greg that "unraisable" is wrong. After all, it
was raised, and it can even be caught by the programmer (inside
__del__).

Regards

Antoine.
___
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

Re: [Python-Dev] Best practice for documentation for std lib

[Antoine Pitrou]

On Mon, 23 Sep 2013 08:57:01 +0100
Larry Hastings  wrote:
> On 09/23/2013 03:44 AM, Guido van Rossum wrote:
> > On Sun, Sep 22, 2013 at 7:25 PM, Terry Reedy  > > wrote:
> >
> > I am gradually changing Idle docstrings, though only Idle
> > developers will ever see them. Writing a 60 char summary forces a
> > clear understanding of the function.
> >
> >
> > Glad you like it. I still do, too, but I've given up hope to convince 
> > all core developers to stick to this style. :-(
> 
> ... Argument Clinic to the rescue?  Since the last time this subject 
> came up, Clinic has started enforcing a summary line in docstrings. I 
> didn't realize it had to be 60 columns though, should I add that? Is the 
> entire docstring supposed to be 60 columns max?
> 
> p.s. status update: AC is done enough to be worth considering checking 
> in.  Now I have to finish the PEP and write the documentation.

I hope it can make it in for 3.4 :)

cheers

Antoine.


___
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

Re: [Python-Dev] Best practice for documentation for std lib

[Skip Montanaro]

>> It would be great if the docstring contained a link to the online
>> documentation.
>
> That would have to be a feature of help(), not hardcoded in each docstring.

That *is* a feature of the help function:

Help on built-in module sys:

>>> help(sys)
NAME
sys

FILE
(built-in)

MODULE DOCS
http://docs.python.org/library/sys
...

(pydoc too, though I'm 99.9% sure they use the same underlying
facility Ping originally implemented.)

Skip
___
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

Re: [Python-Dev] Enum Eccentricities

[Guido van Rossum]

On Mon, Sep 23, 2013 at 8:16 AM, Steven D'Aprano wrote:

> On Mon, Sep 23, 2013 at 07:53:00AM -0700, Guido van Rossum wrote:
>
> > there is no rule that because you can
> > access something on the class you should be able to access it on the
> > instance. Try asking an instance for its class's __mro__ or __bases__.
>
> It might not be a rule, but it's certainly the norm. I reckon that class
> attributes that aren't accessible from the instance are significantly
> more surprising than Color.red.blue.
>

Whether this feels right (to me) depends on whether the class attribute was
*meant* to be used as an instance attribute as well, or not. For methods,
that's an obvious yes. For class attributes used as defaults for instance
variables, yes again. For class attributes that are meant to be per-class
state rather than per-instance state, I would use the class name or
__class__ to make it clear to the (human) reader that we're using a class
variable. This also avoids accidentally overriding it with an instance
variable (although that's not an issue for Enum).


> I know I'm in a minority here, but Color.red.blue seems obvious and
> straightforward to me. The fact that it doesn't work surprises me. Given
> that
>
> instance = Color.red
> assert isinstance(instance, Color)  # well of course it is
> assert hasattr(Color, "blue")
>
> I would expect instance.blue to work, and I'm completely at a loss as to
> how Enum has managed to prevent it.
>

Through the magic of metaclasses. :-)

The only attributes that an enum instance should have are things like .name
and .value, and the methods implementing various standard protocols like
__repr__ and __eq__.

The whole point of Enum is that it involves a fair bit of magic to offer a
robust way to define Enums that "feel right" as Enums. You shouldn't think
of it as a slightly odd class. You should think of it as a different data
type altogether that happens to be implemented using metaclass tecnology.
But many things you "know" about classes don't apply to Enums; this is just
one of many.

-- 
--Guido van Rossum (python.org/~guido)
___
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

Re: [Python-Dev] Enum Eccentricities

[Ethan Furman]

On 09/23/2013 08:16 AM, Steven D'Aprano wrote:


I would expect instance.blue to work, and I'm completely at a loss as to
how Enum has managed to prevent it.


[A peek behind the curtains...]

Currently, Enum members do not live in the class dict.  So when, for example, blue is searched for in red, it is not 
found in the instance dict, and it is not found in the class dict.  As you know, __getattr__ will then be invoked -- but 
the Enum class does not have its own __getattr__, nor its own __getattribute__, and so we get an AttributeError.


Well, you may ask, if blue does not live in the class dict, how does Color.blue 
work?  I'm glad you asked.  ;)

Color is of type EnumMeta, and EnumMeta /does/ have __getattr__, so a failed /class/ lookup will invoke the metaclass 
__getattr__, which will search in the right place, find, and return, Color.blue.


--
~Ethan~
___
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

Re: [Python-Dev] Best practice for documentation for std lib

[Dag Sverre Seljebotn]

On 09/23/2013 04:43 PM, R. David Murray wrote:

On Sun, 22 Sep 2013 16:19:21 -0700, Guido van Rossum  wrote:

On Sun, Sep 22, 2013 at 2:41 PM, Xavier Morel wrote:


The points here are that there's a single source of truth (so we can't
have conflicting docstring and rst documentation), and documentation
becoming outdated can be noticed from both docstring and published
documentation.


Another thing that hasn't been mentioned about docstrings vs rst docs,
is that even when the text is identical, it generally isn't.  By that I
mean the rst docs have ReST markup, but the docstrings don't.  So using


FYI, the scientific Python community have their own standard (the NumPy 
docstring standard), with light RST markup in docstrings:


https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt

It's a fairly popular standard in the scientific sub-culture.

I think there's something about scientific codes which tips the scales 
away from Guido's position of short docstrings being better; when 
working with computation, you pretty much need the documentation, 
formulas, references to paper it is based on and so on in order to read 
and understand the code in the first place, so interspersing makes more 
sense than it may in the stdlib. Seeing code with references "x", 
"alpha", "beta", "gamma" without their definition is pretty useless :-)


Dag Sverre
___
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

Re: [Python-Dev] Enum Eccentricities

[Guido van Rossum]

On Mon, Sep 23, 2013 at 8:17 AM, Zero Piraeus  wrote:

> On Mon, Sep 23, 2013 at 09:45:46AM -0400, Chris Lambacher wrote:
> > [...] The exact use case is in Django templates where a value comes
> > from the database. If you want to compare you either have to use
> > __class__ which I would say is a code smell, or you have
> > to provide the Enum class.
>
> I'm having a hard time seeing why the latter is problematic, I must
> admit (certainly no more so than the "Alice in Wonderland" side effects
> previously described).
>
> > [...] An example of how this will be used in practice is:
> >
> > {% if object.state == object.state.completed %}
> >   some html
> > {% endif %}
>
> The names used slightly obscure the weirdness of it, but what you're
> really saying there is:
>
> if my_state == my_state.another_state
>
> ... which feels more like a code smell to me than
>
>  {% if object.state == State.completed %}
>some html
>  {% endif %}
>
> That's quite intelligible, and doesn't require anyone to know that an
> Enum member's siblings can, in your proposal, be accessed directly via
> dot notation (an unintuitive state of affairs, to me at least).
>

Right. The OP is just concerned that (because these are Django templates)
he will have to pass in the 'State' class as a separate template parameter
for this to work. But to me that's a problem with Django, and not something
for which the Enum type should bend over backwards to cover up for. Given
that it's a Djano weakness, IMO the __class__ solution is reasonable
enough, although in theory it would allow having object.state be something
of the wrong class that happens to have a 'completed' attribute -- that
would be a bug of a different color, though. :-)

-- 
--Guido van Rossum (python.org/~guido)
___
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

Re: [Python-Dev] Enum Eccentricities

[Zero Piraeus]

On Mon, Sep 23, 2013 at 09:45:46AM -0400, Chris Lambacher wrote:
> [...] The exact use case is in Django templates where a value comes
> from the database. If you want to compare you either have to use
> __class__ which I would say is a code smell, or you have
> to provide the Enum class.

I'm having a hard time seeing why the latter is problematic, I must
admit (certainly no more so than the "Alice in Wonderland" side effects
previously described).

> [...] An example of how this will be used in practice is:
> 
> {% if object.state == object.state.completed %}
>   some html
> {% endif %}

The names used slightly obscure the weirdness of it, but what you're
really saying there is:

if my_state == my_state.another_state

... which feels more like a code smell to me than

 {% if object.state == State.completed %}
   some html
 {% endif %}

That's quite intelligible, and doesn't require anyone to know that an
Enum member's siblings can, in your proposal, be accessed directly via
dot notation (an unintuitive state of affairs, to me at least).

 -[]z.

-- 
Zero Piraeus: omnia omnibus
http://etiol.net/pubkey.asc
___
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

Re: [Python-Dev] Best practice for documentation for std lib

[Terry Reedy]

On 9/23/2013 11:18 AM, Skip Montanaro wrote:

It would be great if the docstring contained a link to the online
documentation.


That would have to be a feature of help(), not hardcoded in each docstring.


That *is* a feature of the help function:

Help on built-in module sys:


help(sys)

NAME
 sys

FILE
 (built-in)

MODULE DOCS
 http://docs.python.org/library/sys


On 3.3.2 and 3.4.0:

Help on built-in module sys:

NAME
sys

MODULE REFERENCE
http://docs.python.org/3.3/library/sys
...
FILE
  (built-in)

On Windows, one will not see the top of the help(sys) output unless one 
either uses Idle or increases the number of lines in the console window 
from 300.


--
Terry Jan Reedy

___
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

Re: [Python-Dev] Best practice for documentation for std lib

[Terry Reedy]

On 9/23/2013 10:56 AM, Guido van Rossum wrote:


I think 60 is just a guideline. In stdlib .py source code I want it not
to extend beyond the 79th column (see recent PEP 8 argument). For a


PEP 8 says "Limit all lines to a maximum of 79 characters.

For flowing long blocks of text with fewer structural restrictions 
(docstrings or comments), the line length should be limited to 72 
characters."


I do not understand 72 instead of 79, but to me, that means 72 chars 
total, including indents, triple quote and period, which means the 
cursor not past 73. If that is not what you mean, please clarify.



typical class, where the docstring is indented 4 spaces, that leaves 72
characters for the summary line (including a final period!). For a
method it's 68 due to the extra indent.


72 - 2 indents - """ - . = 60, which is a bit skimpy ;-). Why not the 
full 79 at least?


--
Terry Jan Reedy

___
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

Re: [Python-Dev] Enum Eccentricities

[Guido van Rossum]

I am quickly losing interest in this -- I was only jumping in because I
feared there was support for making Color.red.blue "work". I don't think I
hve to worry about that any more -- what's best for Django templates is up
to the template author.


On Mon, Sep 23, 2013 at 10:46 AM, Stephen J. Turnbull wrote:

> Guido van Rossum writes:
>  > On Mon, Sep 23, 2013 at 8:17 AM, Zero Piraeus  wrote:
>  >> On Mon, Sep 23, 2013 at 09:45:46AM -0400, Chris Lambacher wrote:
>
>  >>> [...] An example of how this will be used in practice is:>
>  >>> {% if object.state == object.state.completed %}
>  >>>   some html
>  >>> {% endif %}
>
> [Zero Piraeus suggests instead:]
>
>  >> {% if object.state == State.completed %}
>  >>   some html
>  >> {% endif %}
>  >>
>  >> That's quite intelligible, and doesn't require anyone to know that
>  >> an Enum member's siblings can, in your proposal, be accessed directly
>  >> via dot notation (an unintuitive state of affairs, to me at least).
>
>  > Right. The OP is just concerned that (because these are Django
>  > templates) he will have to pass in the 'State' class as a separate
>  > template parameter for this to work.
>
> Given your earlier description of what makes sense for class
> attributes, an alternative solution might be to put State-valued class
> attributes (constants) on DjangoObject (the object's class), like
> DjangoObject.completed_state = State.completed, and so on.  Then you
> write "{% if object.state == object.completed_state %}".
>
> IIUC, you wouldn't have a problem with that?  It still doesn't feel
> quite right, but given the limitations of a template language, it
> might grow on me.
>
> Another alternative would be to have attributes like 'completed' be
> *boolean* properties computed from a State-valued attribute, and write
> just "{% if object.completed %}".  This actually feels good to me
> given it's a templating language.
>
> But I don't know if either of those is reasonable in the context.
>



-- 
--Guido van Rossum (python.org/~guido)
___
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

Re: [Python-Dev] Enum Eccentricities

[Stephen J. Turnbull]

Guido van Rossum writes:
 > On Mon, Sep 23, 2013 at 8:17 AM, Zero Piraeus  wrote:
 >> On Mon, Sep 23, 2013 at 09:45:46AM -0400, Chris Lambacher wrote:

 >>> [...] An example of how this will be used in practice is:>
 >>>     {% if object.state == object.state.completed %}
 >>>       some html
 >>>     {% endif %}

[Zero Piraeus suggests instead:]

 >>     {% if object.state == State.completed %}
 >>       some html
 >>     {% endif %}
 >>
 >> That's quite intelligible, and doesn't require anyone to know that
 >> an Enum member's siblings can, in your proposal, be accessed directly
 >> via dot notation (an unintuitive state of affairs, to me at least).

 > Right. The OP is just concerned that (because these are Django
 > templates) he will have to pass in the 'State' class as a separate
 > template parameter for this to work.

Given your earlier description of what makes sense for class
attributes, an alternative solution might be to put State-valued class
attributes (constants) on DjangoObject (the object's class), like
DjangoObject.completed_state = State.completed, and so on.  Then you
write "{% if object.state == object.completed_state %}".

IIUC, you wouldn't have a problem with that?  It still doesn't feel
quite right, but given the limitations of a template language, it
might grow on me.

Another alternative would be to have attributes like 'completed' be
*boolean* properties computed from a State-valued attribute, and write
just "{% if object.completed %}".  This actually feels good to me
given it's a templating language.

But I don't know if either of those is reasonable in the context.
___
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

Re: [Python-Dev] Best practice for documentation for std lib

[Guido van Rossum]

On Mon, Sep 23, 2013 at 10:52 AM, Terry Reedy  wrote:

> On 9/23/2013 10:56 AM, Guido van Rossum wrote:
>
>  I think 60 is just a guideline. In stdlib .py source code I want it not
>> to extend beyond the 79th column (see recent PEP 8 argument). For a
>>
>
> PEP 8 says "Limit all lines to a maximum of 79 characters.
>
> For flowing long blocks of text with fewer structural restrictions
> (docstrings or comments), the line length should be limited to 72
> characters."
>
> I do not understand 72 instead of 79, but to me, that means 72 chars
> total, including indents, triple quote and period, which means the cursor
> not past 73. If that is not what you mean, please clarify.


This is partly based on Emacs defaults (when I hit ESC-q, it reflows a
paragraph using the 72 char limit), partly on old punched card conventions
(columns 73-80 were reserved for sequence numbers), partly just to limit
the line length to of *columns* of text to something a bit narrower than
the full line width (i.e. 80 chars) to improve readability.

But the PEP specifically qualifies this with "for flowing long blocks of
text" which is meant to apply only to blocks of reflowable text that don't
fit on a line.

If it fits on a line, you can go to 79.


> typical class, where the docstring is indented 4 spaces, that leaves 72
> characters for the summary line (including a final period!). For a
> method it's 68 due to the extra indent.
>

72 - 2 indents - """ - . = 60, which is a bit skimpy ;-). Why not the full
> 79 at least?
>

For the summary line, that's fine (and actually how I interpret the PEP).

-- 
--Guido van Rossum (python.org/~guido)
___
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

Re: [Python-Dev] Best practice for documentation for std lib

[Terry Reedy]

On 9/22/2013 10:44 PM, Guido van Rossum wrote:


Glad you like it. I still do, too, but I've given up hope to convince
all core developers to stick to this style. :-(


>[me]  ('Return' rather than 'Returns' is the current convention.)


That's actually a religious argument which in the stdlib takes no strict
position -- a quick grep shows that both are used, although 'Return' is
more frequent by a 5-to-1 margin.


In the .rst docs, 'Return' versus 'Returns', exact uppercase word match, 
is a little over 3 to 1. I am sure I have seen 'Return' and similiar 
directive forms ('Print', 'Store', 'Compare', etc) recommended as 
current doc style, as prefered by the current doc crew.


> IIRC in the Java world you *have* to

use 'Returns', but I don't buy the argument from nit-picky grammarians
that leads to this rule. (It's something about the documentation not
being a command. But English is more flexible than that.)


My take is that 'Returns' describes to the programmer what the function 
(interpreter) does, while 'Return' says what the programmer says to the 
interpreter when using the function. I strongly prefer the directive 
form. Why? For one thing, *because* it is different from normal 
descriptive text, such as the first sentence of this paragraph. For 
another, the descriptive form seems addressed to me as code reader while 
the directive form seems addressed to me as code writer. For me, the 
latter seems more energizing.


--
Terry Jan Reedy

___
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

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Terry Reedy]

On 9/23/2013 12:23 PM, R. David Murray wrote:

On Mon, 23 Sep 2013 17:22:45 +0200, Antoine Pitrou  wrote:

On Mon, 23 Sep 2013 18:51:04 +1000
Nick Coghlan  wrote:

On 23 September 2013 18:45, Antoine Pitrou  wrote:

Le Mon, 23 Sep 2013 18:17:51 +1000,
Nick Coghlan  a écrit :


Here's what I suggest changing that error to:


del x

Unraisable exception suppressed when calling >
Traceback (most recent call last):
   File "", line 3, in __del__
RuntimeError: Going away now


Why not simply "Exception automatically caught in  [...]" ?


It only answers the "what" (i.e. the exception was automatically
caught), without addressing the "why" (i.e. because there wasn't
anything else useful the interpreter could do with it)


Yes, but I agree with Greg that "unraisable" is wrong. After all, it
was raised, and it can even be caught by the programmer (inside
__del__).


Would it work to say "Asynchronous exception suppressed..."?  It's
not-entirely-precise,


As in the example above ('del x').


but it's less imprecise than "unraisable".


How 'troublesome'? That is always accurate, as proven by this thread.

We really need an "Understanding Exceptions" HOWTO, and I expect we will 
get one. So I agree with Nick that something easily searched would be good.


--
Terry Jan Reedy


___
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

Re: [Python-Dev] Best practice for documentation for std lib

[MRAB]

On 23/09/2013 20:01, Terry Reedy wrote:

On 9/22/2013 10:44 PM, Guido van Rossum wrote:


Glad you like it. I still do, too, but I've given up hope to convince
all core developers to stick to this style. :-(


  >[me]  ('Return' rather than 'Returns' is the current convention.)


That's actually a religious argument which in the stdlib takes no strict
position -- a quick grep shows that both are used, although 'Return' is
more frequent by a 5-to-1 margin.


In the .rst docs, 'Return' versus 'Returns', exact uppercase word match,
is a little over 3 to 1. I am sure I have seen 'Return' and similiar
directive forms ('Print', 'Store', 'Compare', etc) recommended as
current doc style, as prefered by the current doc crew.

  > IIRC in the Java world you *have* to

use 'Returns', but I don't buy the argument from nit-picky grammarians
that leads to this rule. (It's something about the documentation not
being a command. But English is more flexible than that.)


My take is that 'Returns' describes to the programmer what the function
(interpreter) does, while 'Return' says what the programmer says to the
interpreter when using the function. I strongly prefer the directive
form. Why? For one thing, *because* it is different from normal
descriptive text, such as the first sentence of this paragraph. For
another, the descriptive form seems addressed to me as code reader while
the directive form seems addressed to me as code writer. For me, the
latter seems more energizing.


I think you mean "imperative" vs "indicative".
___
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

Re: [Python-Dev] Best practice for documentation for std lib

[Alexander Belopolsky]

On Mon, Sep 23, 2013 at 3:01 PM, Terry Reedy  wrote:

> > IIRC in the Java world you *have* to
>
>> use 'Returns', but I don't buy the argument from nit-picky grammarians
>> that leads to this rule. (It's something about the documentation not
>> being a command. But English is more flexible than that.)
>>
>
> My take is that 'Returns' describes to the programmer what the function
> (interpreter) does, while 'Return' says what the programmer says to the
> interpreter when using the function. I strongly prefer the directive form.


+1

I don't think "Returns bar." is a valid English sentence because it lacks
subject.  I would not mind

def foo():
  """returns bar"""

which I would read as "Function foo() returns bar," but in this case
"returns" should be in lower case.
___
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

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[R. David Murray]

On Mon, 23 Sep 2013 17:22:45 +0200, Antoine Pitrou  wrote:
> On Mon, 23 Sep 2013 18:51:04 +1000
> Nick Coghlan  wrote:
> > On 23 September 2013 18:45, Antoine Pitrou  wrote:
> > > Le Mon, 23 Sep 2013 18:17:51 +1000,
> > > Nick Coghlan  a écrit :
> > >>
> > >> Here's what I suggest changing that error to:
> > >>
> > >> >>> del x
> > >> Unraisable exception suppressed when calling  > >> of <__main__.C object at 0x7f98b8b61538>>
> > >> Traceback (most recent call last):
> > >>   File "", line 3, in __del__
> > >> RuntimeError: Going away now
> > >
> > > Why not simply "Exception automatically caught in  > > C.__del__> [...]" ?
> > 
> > It only answers the "what" (i.e. the exception was automatically
> > caught), without addressing the "why" (i.e. because there wasn't
> > anything else useful the interpreter could do with it)
> 
> Yes, but I agree with Greg that "unraisable" is wrong. After all, it
> was raised, and it can even be caught by the programmer (inside
> __del__).

Would it work to say "Asynchronous exception suppressed..."?  It's
not-entirely-precise, but it's less imprecise than "unraisable".

--David
___
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

Re: [Python-Dev] Best practice for documentation for std lib

[Fred Drake]

On Mon, Sep 23, 2013 at 3:01 PM, Terry Reedy  wrote:
> 'Return' versus 'Returns', exact uppercase word match, is a little over 3 to
> 1. I am sure I have seen 'Return' and similiar directive forms ('Print',
> 'Store', 'Compare', etc) recommended as current doc style, as prefered by
> the current doc crew.

I don't know about the current crew, but this dates way back to
Guido's initial LaTeX documentation, and Guido's strong preference on
this.


  -Fred

-- 
Fred L. Drake, Jr.
"A storm broke loose in my mind."  --Albert Einstein
___
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

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Nick Coghlan]

On 24 Sep 2013 01:24, "Antoine Pitrou"  wrote:
>
> On Mon, 23 Sep 2013 18:51:04 +1000
> Nick Coghlan  wrote:
> > On 23 September 2013 18:45, Antoine Pitrou  wrote:
> > > Le Mon, 23 Sep 2013 18:17:51 +1000,
> > > Nick Coghlan  a écrit :
> > >>
> > >> Here's what I suggest changing that error to:
> > >>
> > >> >>> del x
> > >> Unraisable exception suppressed when calling  > >> of <__main__.C object at 0x7f98b8b61538>>
> > >> Traceback (most recent call last):
> > >>   File "", line 3, in __del__
> > >> RuntimeError: Going away now
> > >
> > > Why not simply "Exception automatically caught in  > > C.__del__> [...]" ?
> >
> > It only answers the "what" (i.e. the exception was automatically
> > caught), without addressing the "why" (i.e. because there wasn't
> > anything else useful the interpreter could do with it)
>
> Yes, but I agree with Greg that "unraisable" is wrong. After all, it
> was raised, and it can even be caught by the programmer (inside
> __del__).

The word doesn't literally mean the exception itself was unraisable. It
means it was raised, we caught it and we're writing it to stderr because we
*can't raise it again*.

The relevant C API function is just called "PyErr_WriteUnraisable", not
"PyErr_WriteUnraisableButThatIsTechnicallyWrongSinceItWasAlreadyRaisedAndWeJustCaughtItAndAreNowReportingItToStdErr".

Cheers,
Nick.

>
> Regards
>
> Antoine.
> ___
> 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/ncoghlan%40gmail.com
___
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

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Antoine Pitrou]

On Tue, 24 Sep 2013 07:19:14 +1000
Nick Coghlan  wrote:
> On 24 Sep 2013 01:24, "Antoine Pitrou"  wrote:
> >
> > On Mon, 23 Sep 2013 18:51:04 +1000
> > Nick Coghlan  wrote:
> > > On 23 September 2013 18:45, Antoine Pitrou  wrote:
> > > > Le Mon, 23 Sep 2013 18:17:51 +1000,
> > > > Nick Coghlan  a écrit :
> > > >>
> > > >> Here's what I suggest changing that error to:
> > > >>
> > > >> >>> del x
> > > >> Unraisable exception suppressed when calling  > > >> of <__main__.C object at 0x7f98b8b61538>>
> > > >> Traceback (most recent call last):
> > > >>   File "", line 3, in __del__
> > > >> RuntimeError: Going away now
> > > >
> > > > Why not simply "Exception automatically caught in  > > > C.__del__> [...]" ?
> > >
> > > It only answers the "what" (i.e. the exception was automatically
> > > caught), without addressing the "why" (i.e. because there wasn't
> > > anything else useful the interpreter could do with it)
> >
> > Yes, but I agree with Greg that "unraisable" is wrong. After all, it
> > was raised, and it can even be caught by the programmer (inside
> > __del__).
> 
> The word doesn't literally mean the exception itself was unraisable. It
> means it was raised, we caught it and we're writing it to stderr because we
> *can't raise it again*.

But that's because you already know what it's supposed to convey. The
average user doesn't, and only sees "unraisable".

> The relevant C API function is just called "PyErr_WriteUnraisable", not
> "PyErr_WriteUnraisableButThatIsTechnicallyWrongSinceItWasAlreadyRaisedAndWeJustCaughtItAndAreNowReportingItToStdErr".

"PyErr_WriteUnraisable" is right at the point where it used: I can't
raise that exception at this point, therefore I call
PyErr_WriteUnraisable. However, from the point of view of the user
reading the traceback, the exception *was* raised.

Regards

Antoine.
___
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

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Ethan Furman]

On 09/23/2013 02:19 PM, Nick Coghlan wrote:


The relevant C API function is just called "PyErr_WriteUnraisable", not
"PyErr_WriteUnraisableButThatIsTechnicallyWrongSinceItWasAlreadyRaisedAndWeJustCaughtItAndAreNowReportingItToStdErr".


Wow.  How many legs does that HumptyCamel have, anyway?  ;)

--
~Ethan~
___
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

Re: [Python-Dev] Enum Eccentricities

[Greg Ewing]

Steven D'Aprano wrote:
It might not be a rule, but it's certainly the norm. I reckon that class 
attributes that aren't accessible from the instance are significantly 
more surprising than Color.red.blue.


There are really two different kinds of things that we
refer to as "class attributes". One is things that really
are attributes of the class itself, and the other is
things that are meant to serve as default or shared
instance attributes.

The confusion comes in because we use the same terminology
for both, and because Python doesn't provide any straightforward
way of creating user-defined class-only attributes, so
shared attributes tend to get abused for that purpose.
Then when someone comes along and creates a true
class-only attribute, people get all surprised and
complain about it. They shouldn't, IMO.

--
Greg
___
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

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Greg Ewing]

Antoine Pitrou wrote:

Yes, but I agree with Greg that "unraisable" is wrong. After all, it
was raised, and it can even be caught by the programmer (inside
__del__).


How about something like "Uncaught exception in __del__
method ignored"? It explains fairly clearly what has
happened, and also indicates what do do about it --
catch it in the __del__ method.

--
Greg
___
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

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Ethan Furman]

On 09/23/2013 02:35 PM, Antoine Pitrou wrote:

On Tue, 24 Sep 2013 07:19:14 +1000
Nick Coghlan  wrote:

On 24 Sep 2013 01:24, "Antoine Pitrou"  wrote:


On Mon, 23 Sep 2013 18:51:04 +1000
Nick Coghlan  wrote:

On 23 September 2013 18:45, Antoine Pitrou  wrote:

Le Mon, 23 Sep 2013 18:17:51 +1000,
Nick Coghlan  a écrit :


Here's what I suggest changing that error to:


del x

Unraisable exception suppressed when calling >
Traceback (most recent call last):
   File "", line 3, in __del__
RuntimeError: Going away now


Why not simply "Exception automatically caught in  [...]" ?


It only answers the "what" (i.e. the exception was automatically
caught), without addressing the "why" (i.e. because there wasn't
anything else useful the interpreter could do with it)


Yes, but I agree with Greg that "unraisable" is wrong. After all, it
was raised, and it can even be caught by the programmer (inside
__del__).


The word doesn't literally mean the exception itself was unraisable. It
means it was raised, we caught it and we're writing it to stderr because we
*can't raise it again*.


But that's because you already know what it's supposed to convey. The
average user doesn't, and only sees "unraisable".


All the more reason to have text in the error message that is easily searchable.

--
~Ethan~
___
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

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Antoine Pitrou]

On Mon, 23 Sep 2013 14:38:48 -0700
Ethan Furman  wrote:
> > But that's because you already know what it's supposed to convey. The
> > average user doesn't, and only sees "unraisable".
> 
> All the more reason to have text in the error message that is easily 
> searchable.

Then I propose "CA6yuaYV6dygPfJRxUrhtg". It should be easily
searchable ;-)

Seriously, "easily searchable" is a rather weak criterion for an
error message. It should be easily understandable and non-misleading
first.

Regards

Antoine.


___
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

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[MRAB]

On 23/09/2013 22:19, Nick Coghlan wrote:


On 24 Sep 2013 01:24, "Antoine Pitrou" mailto:solip...@pitrou.net>> wrote:
 >
 > On Mon, 23 Sep 2013 18:51:04 +1000
 > Nick Coghlan mailto:ncogh...@gmail.com>> wrote:
 > > On 23 September 2013 18:45, Antoine Pitrou mailto:solip...@pitrou.net>> wrote:
 > > > Le Mon, 23 Sep 2013 18:17:51 +1000,
 > > > Nick Coghlan mailto:ncogh...@gmail.com>> a
écrit :
 > > >>
 > > >> Here's what I suggest changing that error to:
 > > >>
 > > >> >>> del x
 > > >> Unraisable exception suppressed when calling  > >> of <__main__.C object at 0x7f98b8b61538>>
 > > >> Traceback (most recent call last):
 > > >>   File "", line 3, in __del__
 > > >> RuntimeError: Going away now
 > > >
 > > > Why not simply "Exception automatically caught in  > > C.__del__> [...]" ?
 > >
 > > It only answers the "what" (i.e. the exception was automatically
 > > caught), without addressing the "why" (i.e. because there wasn't
 > > anything else useful the interpreter could do with it)
 >
 > Yes, but I agree with Greg that "unraisable" is wrong. After all, it
 > was raised, and it can even be caught by the programmer (inside
 > __del__).

The word doesn't literally mean the exception itself was unraisable. It
means it was raised, we caught it and we're writing it to stderr because
we *can't raise it again*.


Ah, you mean "unreraisable". :-)


The relevant C API function is just called "PyErr_WriteUnraisable", not
"PyErr_WriteUnraisableButThatIsTechnicallyWrongSinceItWasAlreadyRaisedAndWeJustCaughtItAndAreNowReportingItToStdErr".



___
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

Re: [Python-Dev] Enum Eccentricities

[Nick Coghlan]

On 24 Sep 2013 08:09, "Greg Ewing"  wrote:
>
> Steven D'Aprano wrote:
>>
>> It might not be a rule, but it's certainly the norm. I reckon that class
attributes that aren't accessible from the instance are significantly more
surprising than Color.red.blue.
>
>
> There are really two different kinds of things that we
> refer to as "class attributes". One is things that really
> are attributes of the class itself, and the other is
> things that are meant to serve as default or shared
> instance attributes.
>
> The confusion comes in because we use the same terminology
> for both, and because Python doesn't provide any straightforward
> way of creating user-defined class-only attributes,

Using @property in a metaclass definition isn't *that* complicated :)

(says the guy who helps maintain the type system)

> so
> shared attributes tend to get abused for that purpose.
> Then when someone comes along and creates a true
> class-only attribute, people get all surprised and
> complain about it.

One of the interesting aspects of adding Enum has been the subtle
descriptor handling bugs it has uncovered in the inspect module :)

> They shouldn't, IMO.

There's a helper for Enum's descriptors that will probably be exposed
through the types module in the next 3.4 alpha (tentative name is
types.DynamicClassAttribute). It's the inverse, though - it throws
AttributeError when looked up on the *class* in order to trigger
__getattr__ on the metaclass.

Cheers,
Nick.

>
> --
> Greg
>
> ___
> 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/ncoghlan%40gmail.com
___
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

Re: [Python-Dev] PEP 453 (pip bootstrapping) ready for pronouncement?

[Ned Deily]

In general, I think this is a very important usability feature and I
am in favor of the general approach.  Good work, all!  I do have some
comments, primarily about items that are not currently addressed.

> ``ensurepip`` itself (including the private copy of ``pip`` and its
> dependencies) will still be installed normally (as it is a regular
> part of the standard library), only the implicit installation of pip and
> its dependencies will be skipped.

The PEP should address the license implications of this since the PEP will
add the source of pip and setuptools to all new Python releases, both
source and binary installers releases.  For Python itself, we go to some
trouble to ensure that all contributions are contributed under a suitable
license.  What steps are needed, initially and on-going, to ensure that
these third-party items to be pulled in at each release are compatible
with the license of Python itself?  Who will do this: release managers?
Are updates needed in the internal and external documentation for releases
(README, LICENSE)?  I took a quick look at the current source releases for
both pip and setuptools.  I noted a reference to the LGPL for pip's CA
certs bundle; I didn't see a license file for setuptools.

> This PEP proposes that, if pip still requires it as a dependency,
> ``ensurepip`` will include a private copy of ``setuptools`` (in addition
> to the private copy of ``ensurepip``). ``python -m ensurepip`` will then
> install the private copy in addition to installing ``pip`` itself.
> 
> However, this behavior is officially considered an implementation
> detail. Other projects which explicitly require ``setuptools`` must still
> provide an appropriate dependency declaration, rather than assuming
> ``setuptools`` will always be installed alongside ``pip``.
> 
> Once pip is able to run ``pip install --upgrade pip`` without needing
> ``setuptools`` installed first, then the private copy of ``setuptools``
> will be removed from ``ensurepip`` in subsequent CPython releases.

The PEP does not sufficiently address the issue of the setuptools-provided
easy_install command.  I think it is important to do that for several
reasons:

1. The PEP should make clear whether the easy_install scripts are or
are not installed, globally or in a venv, as a side effect of running
ensurepip, at least while pip has the implicit private dependency
on setuptools.  By default, the scripts are installed so ensurepip
would need to take action to prevent this if that is not desired.

2. Despite the current strong preference for using pip as a command
line installer, the fact is that much third-party documentation still refers
to and recommends using easy_install for their projects.  That is not
going to change overnight.  The PEP should identify some steps needed to
facilitate the migration, like perhaps adding something to the "Installing
Python Modules" documentation explicitly deprecating easy_install use
and/or giving pip equivalents for the most common easy_install
scenarios (or linking to other documentation that does so).

3. A specific issue for OS X users is that, as part of OS X, Apple ships
versions of Python 2 and various third-party packages, including
setuptools (older, pre-reunification versions, at that) but not pip.
That means that OS X ships with easy_install and easy_install-2.n
commands in /usr/bin, including 2.7 in recent OS X releases.  This has
been an ongoing source of confusion for OS X users who install a newer
version of Python.  Depending on the distributor and/or source build
configure options, the new version of Python will be installed to a
different path, like /usr/local/bin.  Which instance is used
is generally managed by direct PATH environment manipulations (or by
launcher programs similar to the Windows py launcher).  If setuptools
is not installed using the new instance, users invoking the easy_install
command will by default end up with distributions being installed to a
system Python rather than to the new Python.  This leads to the
unfortunately common scenario of:

sudo easy_install blah # --> installs to system Python 2.7
python -c 'import blah' # --> fails because using newer Python 2.7

This may very well be the most common current usability problem today
with python.org (and other third-party) Pythons on OS X.

With this PEP, we have an opportunity to fix this problem in one of
two ways.  As long as pip requires setuptools and we do not inhibit
the installation of the easy_install scripts is to the same directory
as the python command itself, the new easy_install scripts will
shadow the Apple-supplied ones just as the python commands do.  If it
is decided to not install the easy_install scripts now or in the
future (e.g. when pip no longer depends on setuptools),
ensurepip could install dummy easy_install scripts (if there
are none already installed there) that merely emit a message to the user
to encourage migration to pip and suggest, if needed, to use pip to

Re: [Python-Dev] PEP 453 (pip bootstrapping) ready for pronouncement?

[Donald Stufft]

On Sep 23, 2013, at 7:34 PM, Ned Deily  wrote:

> One final comment is that the PEP does not go into any detail on how it
> will be implemented.  As it stands, there is a fair amount of one-time
> work, including implementing ensurepip, changes to the Windows installer,
> changes to the OS X installer, documentation changes, all with testing and
> backporting to 2.7.x and 3.3.x.  Then there are the on-going process changes
> for all future releases, impacting all release team members, which will need
> to be documented in PEP 101.  Do we have an understanding of who is do the
> big pieces and by when?  For the record, I am willing to do the extra
> one-time and ongoing work for the OS X installers but it would be helpful
> to know how we are going to get it all done in time for upcoming releases.

I'm in a meeting right now so I only skimmed this email, but I wanted to mention
here that I've been assuming I would be writing the python portions of this. I 
don't
know how to do the OSX/Window installer pieces and I was hoping that the
relevant people would be at least willing to help me figure it out or would 
implement
the parts that need to be done inside the installers (mostly running the 
command).

-
Donald Stufft
PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA



signature.asc
Description: Message signed with OpenPGP using GPGMail
___
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

Re: [Python-Dev] PEP 453 (pip bootstrapping) ready for pronouncement?

[Donald Stufft]

On Sep 23, 2013, at 7:34 PM, Ned Deily  wrote:

> In general, I think this is a very important usability feature and I
> am in favor of the general approach.  Good work, all!  I do have some
> comments, primarily about items that are not currently addressed.
> 
>> ``ensurepip`` itself (including the private copy of ``pip`` and its
>> dependencies) will still be installed normally (as it is a regular
>> part of the standard library), only the implicit installation of pip and
>> its dependencies will be skipped.
> 
> The PEP should address the license implications of this since the PEP will
> add the source of pip and setuptools to all new Python releases, both
> source and binary installers releases.  For Python itself, we go to some
> trouble to ensure that all contributions are contributed under a suitable
> license.  What steps are needed, initially and on-going, to ensure that
> these third-party items to be pulled in at each release are compatible
> with the license of Python itself?  Who will do this: release managers?
> Are updates needed in the internal and external documentation for releases
> (README, LICENSE)?  I took a quick look at the current source releases for
> both pip and setuptools.  I noted a reference to the LGPL for pip's CA
> certs bundle; I didn't see a license file for setuptools.

As far as I know the certificate bundle is licensed under either GPL, MPL,
or LGPL. However there is debate about wether a CA bundle *can* be
licensed at all (see https://github.com/pypa/pip/pull/971).

Pip also includes some code taken from other libraries however everything
is licensed as either 1, 2, or 3 clause BSD (besides the aforementioned
certificates). I can't think of us being ok with adding a copyleft license
such as GPL so code we bring in will likely be restricted to things like BSD.

> 
>> This PEP proposes that, if pip still requires it as a dependency,
>> ``ensurepip`` will include a private copy of ``setuptools`` (in addition
>> to the private copy of ``ensurepip``). ``python -m ensurepip`` will then
>> install the private copy in addition to installing ``pip`` itself.
>> 
>> However, this behavior is officially considered an implementation
>> detail. Other projects which explicitly require ``setuptools`` must still
>> provide an appropriate dependency declaration, rather than assuming
>> ``setuptools`` will always be installed alongside ``pip``.
>> 
>> Once pip is able to run ``pip install --upgrade pip`` without needing
>> ``setuptools`` installed first, then the private copy of ``setuptools``
>> will be removed from ``ensurepip`` in subsequent CPython releases.
> 
> The PEP does not sufficiently address the issue of the setuptools-provided
> easy_install command.  I think it is important to do that for several
> reasons:
> 
> 1. The PEP should make clear whether the easy_install scripts are or
> are not installed, globally or in a venv, as a side effect of running
> ensurepip, at least while pip has the implicit private dependency
> on setuptools.  By default, the scripts are installed so ensurepip
> would need to take action to prevent this if that is not desired.
> 
> 2. Despite the current strong preference for using pip as a command
> line installer, the fact is that much third-party documentation still refers
> to and recommends using easy_install for their projects.  That is not
> going to change overnight.  The PEP should identify some steps needed to
> facilitate the migration, like perhaps adding something to the "Installing
> Python Modules" documentation explicitly deprecating easy_install use
> and/or giving pip equivalents for the most common easy_install
> scenarios (or linking to other documentation that does so).
> 
> 3. A specific issue for OS X users is that, as part of OS X, Apple ships
> versions of Python 2 and various third-party packages, including
> setuptools (older, pre-reunification versions, at that) but not pip.
> That means that OS X ships with easy_install and easy_install-2.n
> commands in /usr/bin, including 2.7 in recent OS X releases.  This has
> been an ongoing source of confusion for OS X users who install a newer
> version of Python.  Depending on the distributor and/or source build
> configure options, the new version of Python will be installed to a
> different path, like /usr/local/bin.  Which instance is used
> is generally managed by direct PATH environment manipulations (or by
> launcher programs similar to the Windows py launcher).  If setuptools
> is not installed using the new instance, users invoking the easy_install
> command will by default end up with distributions being installed to a
> system Python rather than to the new Python.  This leads to the
> unfortunately common scenario of:
> 
>sudo easy_install blah # --> installs to system Python 2.7
>python -c 'import blah' # --> fails because using newer Python 2.7
> 
> This may very well be the most common current usability problem today
> with python.org (and other third-par

Re: [Python-Dev] PEP 453 (pip bootstrapping) ready for pronouncement?

[Donald Stufft]

On Sep 23, 2013, at 8:12 PM, Donald Stufft  wrote:

>> 
>> 
>>> A common source of Python installations are through downstream distributors
>>> such as the various Linux Distributions [#ubuntu]_ [#debian]_ [#fedora]_, 
>>> OSX
>>> package managers [#homebrew]_, or Python-specific tools [#conda]_. In order
>> 
>> If you are going to call out Homebrew, you should include the other major
>> OS X package managers, MacPorts and Fink.
>> 
>>> .. [#homebrew] `Homebrew  `
>> 
>> .. [#macports] `MacPorts  `
>> .. [#fink] `Fink `
> 
> I can add them, I added homebrew because it's what I use :) Didn't really
> think to hard about being super inclusive.

Updated this in PEP453.

-
Donald Stufft
PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA



signature.asc
Description: Message signed with OpenPGP using GPGMail
___
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

Re: [Python-Dev] Revert #12085 fix for __del__ attribute error message

[Stephen J. Turnbull]

MRAB writes:

 > > The word doesn't literally mean the exception itself was unraisable. It
 > > means it was raised, we caught it and we're writing it to stderr because
 > > we *can't raise it again*.

 > Ah, you mean "unreraisable". :-)

+1

Ugly as sin, but satisfies all other criteria (except for Antoine's "easily
understandable" which simply can't be satisfied).
___
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

Re: [Python-Dev] Best practice for documentation for std lib

[Steven D'Aprano]

This is getting off-topic, if you're not interested in English grammar 
you should stop reading.

On Mon, Sep 23, 2013 at 03:18:01PM -0400, Alexander Belopolsky wrote:

> I don't think "Returns bar." is a valid English sentence because it lacks
> subject. 

Subjectless sentences are unusual in English, but you do see them. 
Sentences consisting of only an interjection are subjectless: 

"Ouch!" "Hear hear!" "Rubbish!" "Oh dear!"

Imperative sentences often have no explicit subject:

"Close the door." "Put that light out!" "Follow me."

Conversational English (especially spoken English) often displays the 
phenomenon called "Conversational Deletion", where the beginning of 
sentences are eroded away, dropping (e.g.) possessives, articles, and 
subject nouns.

"Hope this helps." "See you next week." "No need to get upset!"

In the example given, "Returns bar", I would identify this as an example 
of conversational deletion. The full sentence would be "This function 
returns bar". Personally, I don't mind such a conversational style, 
although many people consider it too informal for written English, even 
docstrings :-)


> I would not mind
> 
> def foo():
>   """returns bar"""
> 
> which I would read as "Function foo() returns bar," but in this case
> "returns" should be in lower case.

I certainly don't like that. Sentences, even eroded sentences, start 
with capital letters in English. Unless you are the poet e.e. cummings, 
capital letters are non-negotiable.


-- 
Steven
___
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

Re: [Python-Dev] Best practice for documentation for std lib

[Alexander Belopolsky]

Given near-consensus on the "Return ..." form, the following discussion is
of academic interest only.

On Mon, Sep 23, 2013 at 9:31 PM, Steven D'Aprano wrote:

> > I would not mind
> >
> > def foo():
> >   """returns bar"""
> >
> > which I would read as "Function foo() returns bar," but in this case
> > "returns" should be in lower case.
>
> I certainly don't like that. Sentences, even eroded sentences, start
> with capital letters in English. Unless you are the poet e.e. cummings,
> capital letters are non-negotiable.


I still believe "Returns bar." is a non-sentence even if "Return bar!" is.
 While absence of subject noun in itself may not be an issue, but combined
with a singular third-person verb form, it makes "Returns bar."
grammatically incorrect.
___
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

Re: [Python-Dev] PEP 453 (pip bootstrapping) ready for pronouncement?

[Ned Deily]

In article <44f4e1f8-5533-45a7-810e-b9c13530e...@stufft.io>,
 Donald Stufft  wrote:
> On Sep 23, 2013, at 7:34 PM, Ned Deily  wrote:
> > [... license implications ...]
> 
> As far as I know the certificate bundle is licensed under either GPL, MPL,
> or LGPL. However there is debate about wether a CA bundle *can* be
> licensed at all (see https://github.com/pypa/pip/pull/971).
> 
> Pip also includes some code taken from other libraries however everything
> is licensed as either 1, 2, or 3 clause BSD (besides the aforementioned
> certificates). I can't think of us being ok with adding a copyleft license
> such as GPL so code we bring in will likely be restricted to things like BSD.

IANAL, but I think it would be good if, at least, the setuptools license were 
clearer and the LGPL reference for the cert bundle was changed.  It *might* be 
a good idea to get an opinion from Van Lindberg.  But I'm happy to defer to 
Martin's judgement on this.

>  > [... easy_install on OS X ...]
> 
> So this is an interesting question. On one hand I would say we shouldn't be
> installing easy_install as that feels very user facing to me and the fact 
> that
> setuptools is being installed is an implementation detail. On the other hand
> if we put in stub commands that just simply direct the user to use pip then
> people who *want* to use easy_install (perhaps for Egg support) won't be
> able too (unless perhaps something is released on PyPI that restores the
> easy_install commands?)

I was thinking that, in the latter case, those users who really want to use 
easy_install could be told to just use pip to install a PyPI version of 
setuptools which would replace the stub commands with the real things - 
assuming that works.

> > [... implementation plan ...]
> 
> To further expand upon my original answer, I'm volunteering to do the initial
> work on the ensurepip library, the scripts that will automated the ongoing
> maintenance work, and the back porting of both of the above. I can also 
> attempt
> to do the OSX Installer and Windows installer but I have zero idea how the
> installers actually function so it's probably better for someone else to do 
> that.
> 
> Since it sounds like you're willing to do the work for the OSX installer that
> saves me from having to flail around trying to figure out how to do that 
> part,
> so hopefully MvL or someone can do the same with the Windows installer.
> 
> I'm not sure what needs done outside of the up front work, do I just propose
> changes to PEP 101? Do I make a whole new PEP? Is there more than
> just updating PEP 101?

I think the thing to do is get review buy-in from the release managers for the 
affected active releases (2.7.x = Benjamin, 3.3.x = Georg, 3.4.x = Larry) and 
let them worry about updating PEP 101.  The key point is that this PEP is 
implicitly adding some new responsibilities for the release team; I think they 
just need to be explicit.

-- 
 Ned Deily,
 n...@acm.org

___
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

Re: [Python-Dev] PEP 453 (pip bootstrapping) ready for pronouncement?

[Donald Stufft]

On Sep 24, 2013, at 12:32 AM, Ned Deily  wrote:

> IANAL, but I think it would be good if, at least, the setuptools license were 
> clearer and the LGPL reference for the cert bundle was changed.  It *might* 
> be 
> a good idea to get an opinion from Van Lindberg.  But I'm happy to defer to 
> Martin's judgement on this.

After your concern was raised I went ahead and emailed VanL.

-
Donald Stufft
PGP: 0x6E3CBCE93372DCFA // 7C6B 7C5D 5E2B 6356 A926 F04F 6E3C BCE9 3372 DCFA



signature.asc
Description: Message signed with OpenPGP using GPGMail
___
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