Mailman 3 March 2017 - docs

[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

[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

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

[issue24755] asyncio.wrap_future undocumented
by Marcin Szewczyk June 9, 2017

June 9, 2017

New submission from Marcin Szewczyk: While asyncio.wrap_future is mentioned in PEP 3156 and has its docstring it is undocumented in the reference. run_in_executor is documented but doesn't mention wrap_future either. $ grep -r wrap_future Doc; echo $? 1 ---------- assignee: docs@python components: Documentation messages: 247659 nosy: docs@python, wodny priority: normal severity: normal status: open title: asyncio.wrap_future undocumented type: enhancement versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24755> _______________________________________

7 12

[issue29596] Unfinished sentense in howto/clinic.rst
by Matthias Bussonnier June 6, 2017

June 6, 2017

New submission from Matthias Bussonnier: Around line 1400 of Doc/howto/clinic.rst ``two-pass`` A buffer like ``buffer``. However, a two-pass buffer can only be written once, and it prints out all text sent to it during all of processing, even from Clinic blocks *after* the I've rarely be kept in such suspense ! Unless it's a reference to Monty Python's "The Man Who Finishes Other People's Sentences". In which case, I must say it's ---------- assignee: docs@python components: Documentation messages: 288048 nosy: docs@python, mbussonn priority: normal severity: normal status: open title: Unfinished sentense in howto/clinic.rst versions: Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29596> _______________________________________

6 10

[issue23787] sum() function docstring lists arguments incorrectly
by Valentine Sinitsyn June 6, 2017

June 6, 2017

New submission from Valentine Sinitsyn: sum() function doctstring describes expected arguments as follows (Python 2.7.6): sum(...) sum(sequence[, start]) -> value ... This implies sum() should accept str, unicode, list, tuple, bytearray, buffer, and xrange. However, you clearly can't use this function to sum strings (which is also mentioned in the docstring): >>> sum('abc') Traceback (most recent call last): File "<stdin>", line 1, in <module> TypeError: unsupported operand type(s) for +: 'int' and 'str' I'd suggest to describe first argument as iterable, which is actually what sum() expects there. ---------- assignee: docs@python components: Documentation messages: 239388 nosy: docs@python, vsinitsyn priority: normal severity: normal status: open title: sum() function docstring lists arguments incorrectly type: enhancement versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23787> _______________________________________

6 13

[issue26602] argparse doc introduction is inappropriately targeted
by Daniel Stone June 4, 2017

June 4, 2017

New submission from Daniel Stone: The argparse documentation starts off, after a couple of sentences, by spending several paragraphs (and a couple of sentences) explaining this gem: import argparse parser = argparse.ArgumentParser(description='Process some integers.') parser.add_argument('integers', metavar='N', type=int, nargs='+', help='an integer for the accumulator') parser.add_argument('--sum', dest='accumulate', action='store_const', const=sum, default=max, help='sum the integers (default: find the max)') args = parser.parse_args() print(args.accumulate(args.integers)) While it is undoubtedly impressive, that a sidebar had to be inserted suggesting people in fact refer to other documentation, suggests it may be inappropriate. As an introduction, it is not particularly approachable (especially if you don't catch the nuance of assigning functions to accumulate), and is probably not going to serve the immediate needs of a lot of the audience: the people who click on the first hit for 'python argparse'. I would suggest relegating this example elsewhere in the documentation, with a much more straightforward/realistic example to lead the documentation. ---------- assignee: docs@python components: Documentation messages: 262121 nosy: Daniel Stone, docs@python priority: normal severity: normal status: open title: argparse doc introduction is inappropriately targeted _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26602> _______________________________________

5 4

[issue24899] Add an os.path <=> pathlib equivalence table in pathlib docs
by Ezio Melotti June 2, 2017

June 2, 2017

New submission from Ezio Melotti: I think it would be useful to add to the pathlib documentation a table listing os/os.path operations and their pathlib equivalent. This will be useful both for people porting their code to pathlib and for people that already know os/os.path and want to get familiar with pathlib. ---------- assignee: docs@python components: Documentation keywords: easy messages: 248877 nosy: docs@python, ezio.melotti, pitrou priority: normal severity: normal stage: needs patch status: open title: Add an os.path <=> pathlib equivalence table in pathlib docs type: enhancement versions: Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24899> _______________________________________

7 10

[issue29660] Document that print/format_exception ignore etype
by Matthias Bussonnier June 2, 2017

June 2, 2017

New submission from Matthias Bussonnier: As far as I can tell, http://bugs.python.org/issue17911 made a couple of function in traceback ignore their first arguments (etype) and infer the type from the second one (evalue). (In git 6bc2c1e7 and 2f0441f0 respectively). At least print_exception and format_exception are affected. This likely affect http://bugs.python.org/issue26389 (who wish to expand same API to remove these parameters). And inconsistency with `format_exception_only` which does need `etype` should be checked. If etype is a deprecated parameter it should be noted, and should likely raise a DeprecationWarning as well when set. ---------- assignee: docs@python components: Documentation messages: 288617 nosy: docs@python, mbussonn priority: normal severity: normal status: open title: Document that print/format_exception ignore etype versions: Python 3.5, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29660> _______________________________________

2 11