docs September 2020

docs@python.org

7 participants
179 discussions

[issue15029] Update Defining New Types chapter according to PEP 253

by Mateusz Loskot

New submission from Mateusz Loskot <mateusz(a)loskot.net>: The chapter '2. Defining New Types" in the Python 3.2 documentation [1] does not cover all important elements, especially in the subsection 2.1.4. Subclassing other types. The accepted PEP 253 [2] provides much more detailed and thorough explanation for Python C API users willing to define and subclass new types, than the official manual. I'd like to suggest update of the manual with information enclosed in the PEP 253. In fact, the PEP's sections like * Preparing a type for subtyping * Creating a subtype of a built-in type in C could be copied with little editing, IMHO. The PEP 253 really seems to be a must-read document for Python C API users. [1] http://docs.python.org/release/3.2.2/extending/newtypes.html [2] http://www.python.org/dev/peps/pep-0253/ ---------- assignee: docs@python components: Documentation messages: 162480 nosy: docs@python, mloskot priority: normal severity: normal status: open title: Update Defining New Types chapter according to PEP 253 type: enhancement versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15029> _______________________________________

5 hours, 17 minutes

[issue41805] types.GenericAlias and types.Union have no documentation

by Patrick Reader

New submission from Patrick Reader <pxeger(a)protonmail.com>: See title. For reference: `GenericAlias` was added by Guido van Rossum <guido(a)python.org> in commit 48b069a003ba6c684a9ba78493fbbec5e89f10b8 "bpo-39481: Implementation for [PEP 585](https://www.python.org/dev/peps/pep-0585/) (#18239)" `Union` was added by Maggi Moss <MaggieMoss(a)users.noreply.github.com> in commit 1b4552c5e8e925f24c15f707050f22c977171125 "bpo-41428: Implementation for [PEP 604](https://www.python.org/dev/peps/pep-0604/) (GH-21515)" I can do a PR which would need backporting (is that the right word?) to 3.9 at least for `GenericAlias`. ---------- assignee: docs@python components: Documentation messages: 377064 nosy: docs@python, pxeger priority: normal severity: normal status: open title: types.GenericAlias and types.Union have no documentation versions: Python 3.10, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue41805> _______________________________________

5 hours, 33 minutes

[issue32122] Improve -x option documentation

by Serhiy Storchaka

New submission from Serhiy Storchaka <storchaka+cpython(a)gmail.com>: The documentation of the -x option is virtually not existing. The current short line of the description was enough to me for understanding what is the purpose of this option and how it can be used (I didn't use Windows for more than 10 years). But I was surprised not founding more detailed information about this feature in the documentation. Definitely it should be better documented. Most of users will have no ideas about this feature. The purpose of this option is turning Python scripts into Windows batch files which can be ran as other executables. Similarly as adding she-bang and setting the executable bit allows to run them on Unix. The extension of the Python script should be changed to ".bat", and the following line should be added at the start of the script: @path\to\python -x %0 %* & exit /b Or @py -3 -x %0 %* & exit /b Unlike a she-bang line which is a Python comment, this line is not valid Python syntax, and the -x option is used for skipping it. ---------- assignee: docs@python components: Documentation, Windows messages: 306878 nosy: docs@python, paul.moore, serhiy.storchaka, steve.dower, tim.golden, zach.ware priority: normal severity: normal stage: needs patch status: open title: Improve -x option documentation type: enhancement versions: Python 2.7, Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue32122> _______________________________________

1 day

[issue21510] fma documentation should provide better example.

by Jayanth Koushik

New submission from Jayanth Koushik: The documentation for decimal.fma provides an example which fails to illustrate the most important feature of the function i.e. single rounding. In fact: Decimal(2).fma(3, 5) == Decimal(2)*3 + 5 An example such as this would make it much more clear: >>> getcontext().prec = 2 >>> getcontext().rounding = ROUND_DOWN >>> Decimal('1.5')*Decimal('1.5') + Decimal('1.05') Decimal('3.2') >>> Decimal('1.5').fma(Decimal('1.5'), Decimal('1.05')) Decimal('3.3') ---------- assignee: docs@python components: Documentation messages: 218592 nosy: docs@python, jayanthkoushik priority: normal severity: normal status: open title: fma documentation should provide better example. type: enhancement versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21510> _______________________________________

1 day, 7 hours

[issue26954] Add Guido's rejection notice to the "with" FAQ

by Steven D'Aprano

New submission from Steven D'Aprano: The FAQs include a discussion of the rejected Pascal "with" statement (different from the Python `with`). From time to time people propose variants of it, such as using a leading dot to make it unambiguous. Guido has just firmly rejected the latest such proposal. The FAQ should be updated to make it clear that even with a leading dot the proposal is dead, with a link to Guido's pronouncement. https://mail.python.org/pipermail/python-ideas/2016-May/040070.html ---------- assignee: docs@python components: Documentation messages: 264832 nosy: docs@python, steven.daprano priority: normal severity: normal status: open title: Add Guido's rejection notice to the "with" FAQ versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26954> _______________________________________

1 day, 15 hours

[issue15339] document the threading "facts of life" in Python

by Chris Jerdonek

New submission from Chris Jerdonek <chris.jerdonek(a)gmail.com>: I think it would be helpful if the Python documentation included certain high-level information about multi-threading in Python. At minimum, I think it would help for the documentation to provide a definition that can be linked to of what it means when some part of the Python documentation says something is "thread-safe". In particular, such a definition could clarify that this is different from being atomic. This might best be addressed by an entry in the glossary for the term "thread-safe". Other documentation possibilities include stating what guarantees one should or should not expect regarding thread-safety, both within and across implementations, and providing centralized guidance on how to approach multi-threaded programming in Python. A HOWTO is one possibility for addressing these other possibilities. This issue stems from the discussion in issue 15329, which is more specific. ---------- assignee: docs@python components: Documentation messages: 165336 nosy: cjerdonek, docs@python priority: normal severity: normal status: open title: document the threading "facts of life" in Python _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15339> _______________________________________

1 day, 15 hours

[issue12832] The documentation for the print function should explain/point to how to control the sys.stdout encoding

by R. David Murray

New submission from R. David Murray <rdmurray(a)bitdance.com>: A common problem encountered when using python3 is writing non-ascii to stdout. This will work fine if stdout is a terminal and the terminal encoding handles the characters, but will fail if stdout is later redirected to a pipe. The docs for sys.stdout and for print should contain or point to an explanation of why, and how to solve the problem (ie: how to set the encoding for sys.stdout/sys.stderr). Note that IMO it makes more sense for sys.stdout to default to the LOCALE encoding, but that should be a separate issue. ---------- assignee: docs@python components: Documentation messages: 142880 nosy: docs@python, r.david.murray priority: normal severity: normal status: open title: The documentation for the print function should explain/point to how to control the sys.stdout encoding versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12832> _______________________________________

2 days, 4 hours

[issue39108] Documentation for "random.gauss" vs "random.normalvariate" is lacking

by Charles Newey

New submission from Charles Newey <charlie(a)newey.me>: The Python 3 documentation for the "random" module mentions two possible ways to generate a random variate drawn from a normal distribution - "random.gauss" and "random.normalvariate" (see: https://docs.python.org/3/library/random.html#random.gauss). It's not clear what the distinction is other than apparently the "random.gauss" function is faster. Digging through the source code, it eventually becomes apparent that "random.gauss" is NOT thread safe... but this isn't mentioned in the documentation anywhere. Further, the documentation doesn't make explicit reference to the particular method used for generating these Gaussian variates. Basically what I'm getting at is that it's difficult to tell which function ("gauss" or "randomvariate") I should be using. I feel that the documentation could be clarified here. I'm happy to do this in a PR at some point if required. ---------- assignee: docs@python components: Documentation messages: 358703 nosy: cnewey, docs@python priority: normal severity: normal status: open title: Documentation for "random.gauss" vs "random.normalvariate" is lacking type: enhancement versions: Python 3.5, Python 3.6, Python 3.7, Python 3.8, Python 3.9 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue39108> _______________________________________

2 days, 11 hours

[issue29981] Update Index set, dict, and generator 'comprehensions'

by Terry J. Reedy

New submission from Terry J. Reedy: The index currently has comprehensions *list* with *list* linked to 6.2.5 List displays. I suggest: 1. Link *comprehensions* to 6.2.4. Displays for lists, sets and dictionaries 2. Add subentries *set*, *dict*, and *generator* linked to 2a. 6.2.6. Set displays 2b. 6.2.7. Dictionary displays 2c. 6.2.8. Generator expressions We don't *call* generator expressions 'generator comprehensions', but that is what they are syntactically and one looking for 'comprehensions' should be able to find them there. There is already *list* ... *comprehensions* ... *list comprehensions* with 'list' and 'list comprehensions' linked to glossary entries, while 'list, comprehensions' links to the same section as 'comprehensions, list'. 3. Add 'set/dictionary, comprehensions' sub-entries linked like 'list, com 4. Add Glossary entries and links like 'list comprehensions' ---------- assignee: docs@python components: Documentation keywords: easy messages: 291129 nosy: docs@python, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Update Index set, dict, and generator 'comprehensions' type: behavior versions: Python 3.6, Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29981> _______________________________________

3 days

[issue37203] Correct classmethod emulation in Descriptor HowTo Guide

by Géry

New submission from Géry <gery.ogam(a)gmail.com>: With the current Python equivalent `ClassMethod` implementation of `classmethod` given in Raymond Hettinger's _Descriptor HowTo Guide_, the following code snippet: ``` class A: @ClassMethod def f(cls, *, x): pass print(A.f) A.f(x=3) ``` prints: > <function ClassMethod.\_\_get\_\_.<locals>.newfunc at 0x106b76268> and raises: > TypeError: newfunc() got an unexpected keyword argument 'x' instead of only printing: > <bound method A.f of <class '\_\_main\_\_.A'>> like the `@classmethod` decorator would do. So the `ClassMethod` implementation fails in two regards: * it does not return a bound method to a class; * it does not handle keyword-only arguments. With this PR `ClassMethod` will correctly emulate `classmethod`. This approach (`types.MethodType`) is already used in the Python equivalent `Function` implementation of functions given earlier in the same guide. ---------- assignee: docs@python components: Documentation messages: 345031 nosy: docs@python, eric.araujo, ezio.melotti, maggyero, mdk, rhettinger, willingc priority: normal pull_requests: 13785 severity: normal status: open title: Correct classmethod emulation in Descriptor HowTo Guide type: behavior versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <https://bugs.python.org/issue37203> _______________________________________

3 days, 4 hours

Jump to page:

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

docs September 2020