Mailman 3 December 2021 - Docs-bugs

[issue46120] Add note to `typing.Union` that it is recommended to use `|` instead
by Nikita Sobolev 29 Dec '21

29 Dec '21

New submission from Nikita Sobolev <mail(a)sobolevn.me>: As discussed in https://mail.python.org/archives/list/typing-sig@python.org/thread/TW5M6XDN… > we could probably stick a huge notice in the typing.Union docs saying `|` is preferred for readability in most cases, and not deprecate it for now. I will send a PR to `Union` and `Optional` docs with this note today. ---------- assignee: docs@python components: Documentation messages: 408836 nosy: docs@python, sobolevn priority: normal severity: normal status: open title: Add note to `typing.Union` that it is recommended to use `|` instead type: behavior versions: Python 3.10, Python 3.11 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue46120> _______________________________________

5 8

[issue23952] cgi: Document the 'maxlen' member of the cgi module
by Yatin Kanetkar 29 Dec '21

29 Dec '21

Change by Yatin Kanetkar <yatin.kanetkar(a)gmail.com>: ---------- nosy: +yatink _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue23952> _______________________________________

1 0

[issue38401] Make dataclass attribute docstrings accessible
by Erik Gebeshuber 29 Dec '21

29 Dec '21

Erik Gebeshuber <erik.gebeshuber(a)gmx.net> added the comment: There is some confusion in the answers that I want to clear up: "Attribute docstrings" were suggested in PEP 224 in August 2000 and rejected March 2001: https://www.python.org/dev/peps/pep-0224/ taleinat mentioned already PEP 258 from May 2001, which also contained "attribute docstrings" and was as well rejected. At the same time - May 2001 - the well-known PEP 257 about docstring conventions came up and was accepted. It also mentions "attribute docstrings", but in a kind of restricted way (highlighting *** by me): > String literals occurring elsewhere in Python code ***may also act as documentation***. They are ***not recognized*** by the Python bytecode compiler and are ***not accessible*** as runtime object attributes (i.e. not assigned to __doc__), ... > Please see PEP 258, "Docutils Design Specification" [2], for a detailed description of attribute and additional docstrings. The reference to the rejected PEP 258 does in my opinion not make the concept of "attribute docstrings" invalid, but indeed the restrictive wording (highlighted *** in the quote) defines their status, and it helps to explain the situation: * Attribute docstrings are not supported by Python itself (no __doc__ etc.) -> that's why it is hard to add support for dataclass documentation in `help` as John Parejko suggested. * It is totally fine to use attribute docstrings, since PEP 257 explicitly mentions them. Various tools support them. * There is - as far as I can see it - no clear notion to differentiate between "official" docstrings and "inofficial" ones (attribute docstrings, additional docstrings). All of them are docstrings in the broader sense, though most times only the "official" ones are meant, and many don't even know about the "inofficial" ones. ---------- nosy: +egebes _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue38401> _______________________________________

1 0

[issue30420] [doc] subprocess module: Clarify kwarg handing for convenience APIs
by Alex Waygood 29 Dec '21

29 Dec '21

Change by Alex Waygood <Alex.Waygood(a)Gmail.com>: ---------- title: Clarify kwarg handing for subprocess convenience APIs -> [doc] subprocess module: Clarify kwarg handing for convenience APIs _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue30420> _______________________________________

1 0

[issue30420] Clarify kwarg handing for subprocess convenience APIs
by Alex Waygood 28 Dec '21

28 Dec '21

Alex Waygood <Alex.Waygood(a)Gmail.com> added the comment: The modern docs for these functions seem to: * Document the cwd argument for these functions, following PR 1685 & PR 2253. * Include an **other_popen_kwargs parameter for all these functions. Nick, is there anything left to do here, or can this issue be closed now? ---------- nosy: +AlexWaygood _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue30420> _______________________________________

1 0

[issue21910] [doc] File protocol should document if writelines must handle generators sensibly
by Stanley 27 Dec '21

27 Dec '21

Stanley <ostanley.lee(a)gmail.com> added the comment: I'd be interested in taking a look at this - would these changes clarify things? Current (https://docs.python.org/3/library/codecs.html#codecs.StreamWriter): Writes the concatenated list of strings to the stream (possibly by reusing the write() method). The standard bytes-to-bytes codecs do not support this method. Proposed: Writes the concatenated list of strings to the stream by reusing the write() method, and thus does not support infinite or very large generators. The standard bytes-to-bytes codecs do not support this method. ---------- nosy: +slateny _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue21910> _______________________________________

1 0

[issue31369] re.RegexFlag is not included in __all__, makes type inference less useful
by Andrei Kulakov 27 Dec '21

27 Dec '21

Change by Andrei Kulakov <andrei.avk(a)gmail.com>: ---------- keywords: +patch nosy: +andrei.avk nosy_count: 10.0 -> 11.0 pull_requests: +28495 stage: -> patch review pull_request: https://github.com/python/cpython/pull/30279 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue31369> _______________________________________

1 0

[issue20751] Harmonize descriptor protocol documentation: direct call, super binding with Descriptor Howto docs
by Arthur Milchior 26 Dec '21

26 Dec '21

Change by Arthur Milchior <arthur(a)milchior.fr>: ---------- pull_requests: +28486 pull_request: https://github.com/python/cpython/pull/30271 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue20751> _______________________________________

1 0

[issue20751] Harmonize descriptor protocol documentation: direct call, super binding with Descriptor Howto docs
by Arthur Milchior 26 Dec '21

26 Dec '21

Arthur Milchior <arthur(a)milchior.fr> added the comment: "a base class ``B`` following ``A``" shouldn't it be "the base class"? . After all, there is at most one base class following ``A``. Also, I find it unclear what means "``x`` is returned unchanged, since in this context ``x`` is not a value which exists by itself. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue20751> _______________________________________

1 0

[issue20751] Harmonize descriptor protocol documentation: direct call, super binding with Descriptor Howto docs
by Arthur Milchior 26 Dec '21

26 Dec '21

Arthur Milchior <arthur(a)milchior.fr> added the comment: Shouldn't those change be ported to 3.10 and maybe even earlier version? They are great, but hard to find if you read the current version manual. I'm just surprised by the term "dotted lookup". The remaining of the documentation mention "attribute access". So I assumed that there was a reason to use "dotted lookup" instead of "attribute access". If there is such a reason, it's not clear right now. Otherwise, if they are equivalent, I'd suggest remaining consistent in the term used. I must note that "dotted lookup" is also used in the howto about descriptor, but it does not explain the difference with "attribute access". One last note, I find it a little bit strange that `a` was supposed to be the value on which the access is done, and suddenly it becomes a part of the value. ---------- nosy: +Arthur-Milchior _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue20751> _______________________________________

1 0