Mailman 3 May 2017 - docs

[issue30466] Tutorial doesn't explain the use of classes
by Trey Hunner July 21, 2017

July 21, 2017

New submission from Trey Hunner: The tutorial page for classes starts with "Compared with other programming languages". While object-oriented programming and classes are popular in many programming languages, not everyone learning about Python's classes is familiar with the concept. I teach both new programmers and programmers who have heard of object-oriented programming but never created a class before. I think the first paragraph on this page should be a brief explanation of the use of classes. It may also be a good idea to have a "Why classes?" section explaining the uses of classes in more detail. ---------- assignee: docs@python components: Documentation messages: 294409 nosy: docs@python, trey priority: normal severity: normal status: open title: Tutorial doesn't explain the use of classes type: enhancement versions: Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30466> _______________________________________

3 9

[issue11230] "Full unicode import system" not in 3.2
by John July 19, 2017

July 19, 2017

New submission from John <jh45dev(a)gmail.com>: A few months ago I read that in 3.2 it will be possible to import modules that are located on paths containing any unicode character. (more precisely, with chars not in the local code page) After an hour or two trying to get this to work in 3.2rc3, I went looking for clues, and found these 2 messages in which Victor Stinner says this feature is delayed until Python 3.3: http://bugs.python.org/issue3080#msg126514 http://bugs.python.org/issue10828#msg125787 Could you please make it clear in documentation and web pages, that this feature is not working yet. The Python 3.2 download page includes this: "countless fixes regarding bytes/string issues; among them full support for a bytes environment (filenames, environment variables)" and I guessed this must cover importing from any unicode path, as there was no mention that such importing had been abandoned for this version. -- jh ---------- assignee: docs@python components: Documentation messages: 128711 nosy: docs@python, jh45 priority: normal severity: normal status: open title: "Full unicode import system" not in 3.2 versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11230> _______________________________________

7 11

[issue15360] Behavior of assigning to __dict__ is not documented
by Davide Rizzo July 13, 2017

July 13, 2017

New submission from Davide Rizzo <sorcio(a)gmail.com>: The documentation (at least the obvious places, see Doc/reference/datamodel.rst) says classes and class instances have the '__dict__' attribute, but nothing is said about what happens when assigning to it (like obj.__dict__ = something). As far as I understand that's undefined behavior and other implementations may not work the same as CPython (and CPython itself behaves differently between versions). I'd submit a documentation patch if I knew how to specify this matter. Maybe just say the behavior is not defined? ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 165538 nosy: davide.rizzo, docs@python priority: normal severity: normal status: open title: Behavior of assigning to __dict__ is not documented versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15360> _______________________________________

8 8

[issue10438] list an example for calling static methods from WITHIN classes
by Ian July 12, 2017

July 12, 2017

New submission from Ian <ifreecarve(a)gmail.com>: Concerning this section of the docs: http://docs.python.org/library/functions.html#staticmethod There is no example for calling a static method from another static method within the same class. As I discovered later, it's simple: C.f() -- from inside the class or outside it. A total newbie will accept this and move on... but in other programming languages, it's frowned upon to the class name from within the class. For example, in PHP you use the "self::" prefix and Java you don't need a prefix at all. So, even though I had it right the first time, it didn't SEEM right... so I went on a wild goose chase, for nothing. Googling "java call static method" will get you java documentation that lists both cases, as does "c++ call static method" and "php call static method". I feel that by adding "Note: you must also use the C.f() syntax when calling from within the class", the documentation will be more complete. ---------- assignee: docs@python components: Documentation messages: 121314 nosy: docs@python, ifreecarve priority: normal severity: normal status: open title: list an example for calling static methods from WITHIN classes type: feature request _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10438> _______________________________________

7 19

[issue30420] Clarify kwarg handing for subprocess convenience APIs
by Nick Coghlan June 20, 2017

June 20, 2017

New submission from Nick Coghlan: As per the discussion in https://github.com/python/cpython/pull/1685, the current nominal signatures of the convenience APIs in subprocess is confusing, as they don't make it clear that all Popen keyword arguments are supported, with only the most common ones being listed in the signature. Proposed fixes: * add `cwd` to the list of frequently used arguments, and list it in the nominal signatures for `run()`, `call()`, `check_call()`, and `check_output()` * append `**popenargs` to the nominal signatures of `run()`, `call()`, and `check_call()` * append `**runargs` to the nominal signature of `check_output()` * amend the prose descriptions for these functions accordingly Background: The status quo is that while this behaviour is documented, it's documented solely as text in the bodies of the API definitions, using paragraphs like the following: `run()`: """The arguments shown above are merely the most common ones, described below in Frequently Used Arguments (hence the use of keyword-only notation in the abbreviated signature). The full function signature is largely the same as that of the Popen constructor - apart from timeout, input and check, all the arguments to this function are passed through to that interface.""" `call()`, `check_call()`: """The arguments shown above are merely the most common ones. The full function signature is largely the same as that of the Popen constructor - this function passes all supplied arguments other than timeout directly through to that interface.""" `check_output()`: """The arguments shown above are merely the most common ones. The full function signature is largely the same as that of run() - most arguments are passed directly through to that interface.""" While it's technically anecdotal, we still have pretty decent evidence that this isn't adequate as: - I worked on the original patch splitting out the "Frequently Used Arguments" section, and initially missed not only that the run() docs had retained that paragraph, but also missed the revised paragraphs in the relocated docs for the older API - as mentioned in the linked PR, Paul Kehrer had missed that `check_call()` and `check_output()` both supported the Popen `cwd` parameter The working theory behind adding the appropriately named `**kwargs` parameters to the end of the nominal signatures is that it will give readers a clearer indication that we're *not* explicitly listing all the parameters, and a hint as to which API to go look at to find out more about the unlisted ones. ---------- assignee: docs@python components: Documentation messages: 294070 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Clarify kwarg handing for subprocess convenience APIs type: enhancement versions: Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30420> _______________________________________

4 7

[issue30176] curses attribute constants list is incomplete
by Serhiy Storchaka June 19, 2017

June 19, 2017

New submission from Serhiy Storchaka: Initially constants was enumerated in alphabetical order (except A_ITALIC). Maybe continue supporting this order? On other hand, it may be worth to group highlighting attributes separately. A_ATTRIBUTES, A_CHARTEXT and A_COLOR are not specific attributes, but bit masks, they also could be grouped separately or moved into a separate table. Perhaps it is worth to add notes for A_ITALIC and highlighting attributes. They are not always available. ---------- nosy: +serhiy.storchaka _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30176> _______________________________________

3 13

[issue20823] Clarify copyreg.pickle() documentation
by Peter Otten June 18, 2017

June 18, 2017

New submission from Peter Otten: The documentation for copyreg.pickle(type, function, constructor=None) has the sentence "TypeError will be raised if *object* is a class or *constructor* is not callable." It's not clear to me what "object" refers to. I believe it refers to the first arg (called ob_type in 2.x) and classic classes which were handled with def pickle(ob_type, pickle_function, constructor_ob=None): if type(ob_type) is _ClassType: raise TypeError("copy_reg is not intended for use with classes") in 2.x If I'm right the above sentence should become. "A TypeError will be raised if *constructor* is not callable." in 3.x. If I'm wrong please think of way to express the intended meaning more clearly. Another minor change: class C need not inherit from object explicitly in 3.x. ---------- assignee: docs@python components: Documentation messages: 212541 nosy: docs@python, peter.otten priority: normal severity: normal status: open title: Clarify copyreg.pickle() documentation versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20823> _______________________________________

2 3

[issue30217] Missing entry for the tilde (~) operator in the Index
by Eric O. LEBIGOT June 12, 2017

June 12, 2017

New submission from Eric O. LEBIGOT: The index (https://docs.python.org/3.6/genindex-Symbols.html) is missing an entry for the tilde operator ~ (there is also no entry under "tilde"). A relevant pointer could be to object.__invert__ (https://docs.python.org/3.6/reference/datamodel.html#object.__invert__). ---------- assignee: docs@python components: Documentation messages: 292641 nosy: docs@python, lebigot priority: normal severity: normal status: open title: Missing entry for the tilde (~) operator in the Index type: enhancement versions: Python 2.7, Python 3.3, Python 3.4, Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30217> _______________________________________

6 13

[issue30312] Small correction in set code sample
by Oskar Weser June 10, 2017

June 10, 2017

New submission from Oskar Weser: There is a code example about the set type found under: https://docs.python.org/3/tutorial/datastructures.html It reads as: ``` >>> basket = {'apple', 'orange', 'apple', 'pear', 'orange', 'banana'} >>> print(basket) # show that duplicates have been removed {'orange', 'banana', 'pear', 'apple'} >>> 'orange' in basket # fast membership testing True >>> 'crabgrass' in basket False >>> # Demonstrate set operations on unique letters from two words ... >>> a = set('abracadabra') >>> b = set('alacazam') >>> a # unique letters in a {'a', 'r', 'b', 'c', 'd'} >>> a - b # letters in a but not in b {'r', 'd', 'b'} >>> a | b # letters in either a or b ``` I read "either a or b" as "a .EXOR. b". Shouldn't it be: ``` >>> a | b # letters in a or b ``` I don't speak English as a native language, so perhaps I am wrong. ---------- assignee: docs@python components: Documentation messages: 293291 nosy: docs@python, mcocdawc priority: normal severity: normal status: open title: Small correction in set code sample versions: Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue30312> _______________________________________

6 9

some RFC references could be updated
by Sean Turner June 10, 2017

June 10, 2017

Hi, Just starting to learn python and have noted that at the bottom of this page: http://docs.python.org/3/library/ssl.html There's a couple of out of date references: 0) RFC 1750 has been been obsoleted by RFC 4086 so maybe this is a better reference (and I prefer the datatracker view as opposed to the tools view): http://datatracker.ietf.org/doc/rfc4086/ Same could be done on this link: http://docs.python.org/3.4/library/ssl.html 1) RFC 3280 has been obsoleted by RFC 5280 so maybe: http://datatracker.ietf.org/doc/rfc5280/ Same could be done on this link: http://docs.python.org/3.4/library/ssl.html 2) RFC 4366 has been obsoleted by RFC 6066 so maybe: http://datatracker.ietf.org/doc/rfc6066/ On http://docs.python.org/3.4/library/ssl.html you could probably just drop the reference and change in the ssl.HAS_SNI section. 3) The link to TLS seems broken maybe just point to: TLS 1.0 http://datatracker.ietf.org/doc/rfc2246/ TLS 1.1 http://datatracker.ietf.org/doc/rfc4346/ TLS 1.2 http://datatracker.ietf.org/doc/rfc5246/ SSL 3.0 http://datatracker.ietf.org/doc/rfc6101/ Actually the same link is broken on: http://docs.python.org/3.4/library/ssl.html 4) (this is a shameless plug) Might be worth adding a reference in the ssl.PROTOCOL_SSLv2 section that points to: http://datatracker.ietf.org/doc/rfc6146/ Cheers, spt

10 20