Re: Survey: improving the Python std lib docs
On Friday, May 12, 2017 at 3:02:58 AM UTC-7, Steve D'Aprano wrote: > One of the more controversial aspects of the Python ecosystem is the Python > docs. Some people love them, and some people hate them and describe them as > horrible. > > Here are a couple of suggestions for improving(?) the docs. What do you > think? > .[ deletia ]. Thank you for bringing up this important topic. As an occasional Python user, I find that Python documentation is all over the usability map - some great, some difficult. The Python docs have been at best a starting point. I usually need to go to other sites like this group, StackOverflow, and a blog or two to understand how to do something. After I learn to do that one thing, I am not any more independent, self-reliant, or able to contribute back to the community. Although Matlab gets a lot of grief in the open source community, its documentation is concise, complete, and self-contained. A table of functions/classes at the start of a Python doc would be very helpful. I'd also like to see a tree-like overview of a package so I can get an idea of what's available and how deep the dot-indexed hierarchy goes. I've tried to write code to extract/present this for myself and have failed. IDEs and Notebooks allow descending a branch one dot at a time - very time consuming. Many of the docs go deep into CS terminology from the start which can be daunting. Here's the first paragraph from the 'Classes' documentation: https://docs.python.org/2/tutorial/classes.html "Compared with other programming languages, Python’s class mechanism adds classes with a minimum of new syntax and semantics. It is a mixture of the class mechanisms found in C++ and Modula-3. Python classes provide all the standard features of Object Oriented Programming: the class inheritance mechanism allows multiple base classes, a derived class can override any methods of its base class or classes, and a method can call the method of a base class with the same name." I am sure it is all correct. I just don't know what it means. I saw pkgutil referenced in answers to some StackOverflow questions and I looked into it: https://docs.python.org/2/library/pkgutil.html "This module provides utilities for the import system, in particular package support." Then it gets very specialized. I am well aware of the distinction between documentation and tutorials. I think that the Python docs of today are too close to research articles and the specialized knowledge that implies. This blog post is "in-the-face" but has an example at the end of how docs might be rewritten. http://cryto.net/~joepie91/blog/2013/02/19/the-python-documentation-is-bad-and-you-should-feel-bad/ --- JBB -- https://mail.python.org/mailman/listinfo/python-list
Re: Rosetta: Zebra puzzle (2.)
On 2017-05-13, Robert L. wrote:
[Schnipp]
> def build_permutations things
> if block_given?
> things.permutation.select{|x| yield x}
> else
> things.permutation.to_a
> end
> end
I fail to recognize the Python-version.
--
Jan v/d Broek
balgl...@dds.nl
--
https://mail.python.org/mailman/listinfo/python-list
Re: Survey: improving the Python std lib docs
On 5/12/2017 6:02 AM, Steve D'Aprano wrote: Here are a couple of suggestions for improving(?) the docs. What do you think? (They're not my ideas, the originated on Reddit.) (1) Table of functions/classes at the start of each module doc The only thing possibly 'new' here is 'each' versus 'selected'. 'Each' could be seen as an aspiration. It could also be seen as a diversion from making concrete improvements, one chapter at a time, by a self-volunteer who will write and *commit to maintaining* such a table for a particular module. The docs for builtins starts with a table of built-in functions: https://docs.python.org/3/library/functions.html Table has names only, alphabetically. Maintenance will be collective. https://docs.python.org/3/library/itertools.html#module-itertools Categorized names, alphabetical within categories, with columns for arguments, results, and examples. Raymond Hettinger maintains it. > The statistics module shows something similar: > https://docs.python.org/3/library/statistics.html Categorized names with explanation, with a logical order within categories that is copied in the details section. Steve will presumably make sure the index is updated if anyone adds new functions. Steve, did you get any opposition to including that table? Does the abstract idea of 'more tables' need discussion? Docs for other modules should do similar, e.g. for the string module there should be a table showing: ascii_letters ascii_lowercase ascii_uppercase capwords digits Formatter hexdigits octdigits printable punctuation Template whitespace which link to the detailed documentation for that object. https://docs.python.org/3/library/string.html I disagree. The alphabetical list mixes together 9 string constants, defining subsets of ascii characters, and 3 callables (1 function and 2 classes). The doc *could* start with a short table Contents | string constants | define subsets of ascii characters | | capwords | Capitalize each word in a string | | Formatter| Custom formatting extending builtin format() | | Template | Simple $-based string substitution | But this listing of mostly unused *objects* misses the 99% meat of the chapter, the definition format strings and format specs and the format() examples. While this chapter originally documented the string module, it now mostly documents format() strings. The doc for the string functions which are now strings methods was moved elsewhere. (The capwords function is a vestigial remnant that was not made a string method.) There is already a sidebar Table of Contents, which is generated automatically. To me, the biggest deficiency of this chapter is the lack of any Formatter examples. From a cursory reading, I have no idea how to use it. I also question the placement of Formatter before the format() doc it depends on. A table I would like is one that replaces the wordy contents of the 'String constants' section, which should perhaps be renamed 'Character categories'. I may have proposed this a decade ago and had the idea rejected. | digits | '0123456789' ... | ascii_uppercase | 'ABCDEFGHIJKLMNOPQRSTUVWXYZ' ... | printable | digits + ascii_letters + punctuation + whitespace | There should then be an explanation or reference to how at access similar unicode categories. -- Conclusion: specific chapters need specific thought as to whether and what type of table might be useful. -- Terry Jan Reedy -- https://mail.python.org/mailman/listinfo/python-list
Re: Rosetta: Zebra puzzle (2.)
On 2017-05-13 22:03, Jan van den Broek wrote:
On 2017-05-13, Robert L. wrote:
[Schnipp]
def build_permutations things
if block_given?
things.permutation.select{|x| yield x}
else
things.permutation.to_a
end
end
I fail to recognize the Python-version.
It's not Python. I believe it's Ruby.
Ignore him. He's been banned from the Python-list proper, so if you're
seeing his posts you must be accessing the list via some mirror, e.g.
via Google Groups.
--
https://mail.python.org/mailman/listinfo/python-list
Re: Survey: improving the Python std lib docs
On 5/13/2017 1:23 PM, jeanbigbo...@gmail.com wrote:
Thank you for bringing up this important topic. As an occasional Python user,
I find that Python documentation is all over the usability map - some great,
some difficult. The Python docs have been at best a starting point. I usually
need to go to other sites like this group, StackOverflow, and a blog or two to
understand how to do something. After I learn to do that one thing, I am not
any more independent, self-reliant, or able to contribute back to the
community. Although Matlab gets a lot of grief in the open source community,
its documentation is concise, complete, and self-contained.
Thank you for writing a response focused on your experience with the docs.
A table of functions/classes at the start of a Python doc would be very
helpful. I'd also like to see a tree-like overview of a package so I can get
an idea of what's available and how deep the dot-indexed hierarchy goes. I've
tried to write code to extract/present this for myself and have failed. IDEs
and Notebooks allow descending a branch one dot at a time - very time consuming.
Many of the docs go deep into CS terminology from the start which can be
daunting. Here's the first paragraph from the 'Classes' documentation:
https://docs.python.org/2/tutorial/classes.html
The tutorial is meant to be for 'beginners'.
"Compared with other programming languages, Python’s class mechanism adds classes
with a minimum of new syntax and semantics. It is a mixture of the class mechanisms found
in C++ and Modula-3. Python classes provide all the standard features of Object Oriented
Programming: the class inheritance mechanism allows multiple base classes, a derived
class can override any methods of its base class or classes, and a method can call the
method of a base class with the same name."
I am sure it is all correct. I just don't know what it means.
When that was likely written, more that two decades ago, python
beginners were experienced programmers who would have known much of the
above. Python beginners today are much different (and even experienced
programmers are unlikely to know anything about Modula-x.)
If you would like it changed, open an issue on the tracker.
I saw pkgutil referenced in answers to some StackOverflow questions and I
looked into it:
https://docs.python.org/2/library/pkgutil.html
"This module provides utilities for the import system, in particular package
support."
Then it gets very specialized.
I am well aware of the distinction between documentation and tutorials. I think
that the Python docs of today are too close to research articles and the
specialized knowledge that implies.
This blog post is "in-the-face" [remainder of sentence moved below]
http://cryto.net/~joepie91/blog/2013/02/19/the-python-documentation-is-bad-and-you-should-feel-bad/
This blog post has several sins that you avoided, and did not help to
improve the docs. But anyway, to stay on topic...
> [moved] but has an example at the end of how docs might be rewritten.
The example is a separate page written after the original rant.
http://cryto.net/%7Ejoepie91/walk.html
This example expands 7 lines 6 times to about 42 and in the process
manages to omit the following important info, which is about 1/5 of the
original text.
"The visit function may modify names to influence the set of directories
visited below dirname, e.g. to avoid visiting certain parts of the tree.
(The object referred to by names must be modified in place, using del or
slice assignment.)"
I am not sure where it would go in the template. Templates can be
straightjackets ;-).
The big issue is examples. The problem with examples is that they are a
maintenance burden. Really. Without testing, they are not dependable.
And testing doc examples is not trivial. So they need to really add value.
There are no examples in the os.path doc, and the particular issue for
os.path is that results are idiosyncratic to a particular system. For
some things, like the os.path functions, it is trivial for a user to try
things out for themselves on their system. The following took just a
few minutes.
Python 3.6.1 (v3.6.1:69c0db5, Mar 21 2017, 18:41:36) [MSC v.1900 64 bit
(AMD64)] on win32
Type "copyright", "credits" or "license()" for more information.
>>> import sys
>>> x = sys.executable
>>> import os.path as op
>>> op.isfile(x)
True
>>> op.isdir(x)
False
>>> x
'C:\\Programs\\Python36\\pythonw.exe'
>>> op.isabs(x)
True
>>> op.islink(x)
False
>>> op.getsize(x)
98968
>>> op.isdir(op.split(x)[0])
True
>>> op.splitdrive(x)
('C:', '\\Programs\\Python36\\pythonw.exe')
>>> op.join(x, 'Lib')
'C:\\Programs\\Python36\\pythonw.exe\\Lib'
>>> op.isdir(op.join(x, 'Lib'))
False
>>> op.getmtime(x)
1490136264.0
In any case, besides the tutorial and some of the reference chapters,
python comes with some 'How-to's with examples. There are also multiple
3rd party sites that expand on the d
Re: Rosetta: Zebra puzzle (2.)
On Sun, 14 May 2017 07:03 am, Jan van den Broek wrote:
> On 2017-05-13, Robert L. wrote:
>
> [Schnipp]
>
>> def build_permutations things
>> if block_given?
>> things.permutation.select{|x| yield x}
>> else
>> things.permutation.to_a
>> end
>> end
>
> I fail to recognize the Python-version.
That is because it isn't Python, it is Ruby.
Ironically given Robert's "No_spamming" fake email address, he is a spammer.
He is posting Ruby code to the Python list as an excuse for sending his
vile, anti-Semitic and racist quotes. (Half of them are lies, the other
half are out-of-context half-truths.)
And the coward doesn't even have the courage to stand behind his
convictions: he doesn't even use his full name.
"Robert L" No_Spamming@fake-address thinks he is spreading his message of
White Power, but all he is doing is showing what a cowardly, hypocritical,
dumb-arse spammer he is.
--
Steve
Emoji: a small, fuzzy, indistinct picture used to replace a clear and
perfectly comprehensible word.
--
https://mail.python.org/mailman/listinfo/python-list
Re: Rosetta: Zebra puzzle (2.)
On Sun, May 14, 2017 at 11:44 AM, Steve D'Aprano wrote: > "Robert L" No_Spamming@fake-address thinks he is spreading his message of > White Power, but all he is doing is showing what a cowardly, hypocritical, > dumb-arse spammer he is. And here I thought we were supposed to be building more Green Power so we hurt the environment less. My bad. ChrisA -- https://mail.python.org/mailman/listinfo/python-list
