[Tutor] How is "set(ls).add('a') evaluated? [Was: Re: A program that can check if all elements of the list are mutually disjoint]

[dn]

On 07/06/2021 09.54, dn via Tutor wrote:
> On 07/06/2021 05.22, boB Stepp wrote:
>> On Sun, Jun 6, 2021 at 3:53 AM dn via Tutor <tutor at python.org> wrote:
>>> On 06/06/2021 14.19, boB Stepp wrote:
...

>> My sincere apologies, David (*not* dn)!  I cannot seem to keep the
>> "bouncing cats" segregated from the " dancing (with) mice" in my head,
>> not to mention the same first names!

It's easy-enough: I'm the better-looking one!

(more, and more pertinent comment, below)

>>>> <Gripe>
>>>> I find it really hard to remember which functions and methods return
>>>> "None" and operate by side effect with those that return a new object.
>>>> This is especially difficult for me as I so often have long breaks
>>>> between using/studying Python.  I wish that Python had some sort of
>>>> clever syntax that made it *obvious* which of the two possibilities
>>>> will occur.
>>>> </Gripe>
>>>> ~(:>))
>>>
>>>
>>> It's "pythonic"!
>>> (hey, don't shoot me, I'm only the piano-player)
> 
> There are conventions at-play when help() and similar docs are composed.
> At the higher level there are considerations of conveying detail whilst
> also minimising the space required - the opposite applies (possibly)
> when reading the Python Docs!
> 
> Secondly, a 'skill' for reading such (as mentioned) lies in aligning
> one's thinking with the help()-idiom. For example, "We hold these truths
> to be self-evident" that each method will be preceded either by "self."
> (within the class definition) or 'object-name.' after instantiation.
> Thus, "s.pop()".
...

> (PEP-484 and after, https://www.python.org/dev/peps/pep-0484/)
> 
> Note that this PEP (and most) concentrates on automated features for its
> justification, eg static checking; rather than any
> documentation/readability factors!
> 
> 
> Thus (from help() ):
> 
>  |  __and__(self, Set, /) -> Set
>  |      Return self&value.
> ...
>  |  add( Any ) [NB no -> return-value noted]
>  |      Add an element to a set.
>  |
>  |      This has no effect if the element is already present.
> ...
>  |  __len__(self, /) -> int
>  |      Return len(self).
> ...
>  |  pop( index:Optional[ Int ] ) -> element:Any
>  |      Remove and return an arbitrary set element.
>         Raises KeyError if the set is empty.
> ...
>  |  update( Set) [NB no -> return-value noted]
>  |      Update a set with the union of itself and others.
...
>> Ah, but here's the rub.  The help(set) and online docs when they
>> describe the add() method do *not* _explicitly_ state what the method
>> returns.  When reading this originally I naively thought it returned
>> the updated set object.  OTOH, the union() method explicitly states
>> what is returned.  I guess I am just dense and should have realized
>> that if no *explicit* mention in the help and docs is made regarding a
>> method's return value then it by default will return "None".  This now
>> is making me even more of a believer in using type annotations and
>> making it *very explicit* for dense people like me what the return
>> value is for each method and function.  For me the docs and help()
>> would read better if in every case for every function and method its
>> return value is always explicitly stated.
> 
> Whilst there may be some improvement - what do you think?
> 
> It looks rather clumsy (to me), and one could argue that the lack of
> return-value (in some cases), still requires the reader to notice and
> appreciate the implication of its omission!
> 
> The balance here may be that help() is more an easy-access
> reference/reminder tool. When it comes to 'learning' (or reacting to an
> experiment resulting in "surprise") might the Python Docs be a better
> (official) source? eg
> https://docs.python.org/3.9/library/stdtypes.html#set-types-set-frozenset
> 
> Mea culpa: when trying something new, I often find that an aspect
> lacking clarity (in my mind) in the docs, may be resolved by playing
> with help() and the REPL - and equally, vice-versa!


After relating a personal view of 'the documentation', I recalled
another attitude applicable to a wider, and perhaps non-traditional
audience, voiced at the Python Language Summit 2020.

For your reading pleasure:
<<<
Batchelder observed that "twenty-five years ago, our main audience
seemed to be refugees from C," but most readers of the Python docs today
are not career software developers at all; they need different docs.
>>>

which goes-on to be 'bang on the money' regarding @boB's frustration:
<<<
Updating the documentation to fix common misunderstandings would save
time in the long run for users and the core team.
>>>
Python Software Foundation's Blog:
https://pyfound.blogspot.com/2020/04/cpython-documentation-next-5-years.html


NB perhaps I haven't paid sufficient attention, but I don't think that
the proposed Python Steering Council workgroup called the "Documentation
Editorial Board" has published much since.
(but will be delighted to be corrected on this, directed to web.refs, etc)
-- 
Regards,
=dn