Mailman 3 August 2011 - docs

[issue11001] Various obvious errors in cookies documentation
by Luke Plant 07 May '19

07 May '19

New submission from Luke Plant <L.Plant.98(a)cantab.net>: Docs for SimpleCookie, BaseCookie.value_encode and BaseCookie.value_decode are obviously incorrect. Attempt at patch attached. The error has existed in every Python version I've seen, I've tagged the ones I believe can receive fixes, sorry if I've made a mistake. Thanks. ---------- assignee: docs@python components: Documentation files: http_cookies_doc_corrections.diff keywords: patch messages: 126962 nosy: docs@python, spookylukey priority: normal severity: normal status: open title: Various obvious errors in cookies documentation versions: Python 2.7, Python 3.1, Python 3.2 Added file: http://bugs.python.org/file20507/http_cookies_doc_corrections.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11001> _______________________________________

8 12

[issue10789] Lock.acquire documentation is misleading
by Jyrki Pulliainen 26 Apr '19

26 Apr '19

New submission from Jyrki Pulliainen <jyrki(a)dywypi.org>: In threading module, the Lock.acquire documentation is misleading. The signature suggests that the blocking can be given as a keyword argument but that would lead to an TypeError, as thread.lock.acquire does not accept keyword arguments. The signature in documentation should be formatted as in thread.lock.acquire. ---------- assignee: docs@python components: Documentation messages: 124861 nosy: Jyrki.Pulliainen, docs@python priority: normal severity: normal status: open title: Lock.acquire documentation is misleading versions: Python 2.7, Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10789> _______________________________________

6 9

[issue10048] urllib.request documentation confusing
by Antoine Pitrou 26 Apr '19

26 Apr '19

New submission from Antoine Pitrou <pitrou(a)free.fr>: The urllib.request documentation intermingles old 2.x urllib (FancyURLopener, etc.) with urllib2-inherited (*Handler, build_opener, etc.) primitives without making any distinction. This makes it rather confusing for the reader to figure out which ones to use. Ideally, the use of the old primitives should also be discouraged. ---------- assignee: docs@python components: Documentation messages: 118179 nosy: docs@python, orsenthil, pitrou priority: normal severity: normal stage: needs patch status: open title: urllib.request documentation confusing versions: Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10048> _______________________________________

4 5

[issue11776] types.MethodType() params and usage is not documented
by anatoly techtonik 24 Feb '19

24 Feb '19

New submission from anatoly techtonik <techtonik(a)gmail.com>: types.MethodType(function, instance) is used as a replacement for new.instancemethod(function, instance, class), but this usage is not documented. ---------- assignee: docs@python components: Documentation messages: 133089 nosy: docs@python, techtonik priority: normal severity: normal status: open title: types.MethodType() params and usage is not documented versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________

13 31

[issue11352] Buf in cgi module doc
by Pierre Quentel 24 Feb '19

24 Feb '19

New submission from Pierre Quentel <pierre.quentel(a)gmail.com>: Hi, I wrote a patch for the cgi module in version 3.2rc1 (#4953). Small changes should be done to the documentation of this module to reflect the changes in the module API : - in section "20.2.2. Using the cgi module" original text : "If a field represents an uploaded file, accessing the value via the value attribute or the getvalue() method reads the entire file in memory as a string. This may not be what you want. You can test for an uploaded file by testing either the filename attribute or the file attribute. You can then read the data at leisure from the file attribute:" proposed new text (for files, value is bytes, not string, and the read() method on file also returns bytes) : "If a field represents an uploaded file, accessing the value via the value attribute or the getvalue() method reads the entire file in memory as bytes. This may not be what you want. You can test for an uploaded file by testing either the filename attribute or the file attribute. You can then read the data at leisure from the file attribute (the read() and readline() methods will return bytes) :" - version 3.2 introduced a parameter "encoding" for the FieldStorage constructor, used to decode the bytes received on the HTTP connection for fields other than files. This encoding must the one defined in the HTML document holding the form submitted to the CGI script ; it is usually defined by a meta tag : <meta http-equiv="Content-type" content="text/html;charset=latin-1"> or by the Content-Type header for this document I'm not sure where this should be mentioned in the module documentation. Maybe in "20.2.9. Common problems and solutions" for the moment. But there are plans (#11066) to introduce another interface to change the encoding of sys.stdout in the CGI script itself, so another option would be to open a specific section about encodings Hope it's clear enough Pierre ---------- assignee: docs@python components: Documentation messages: 129691 nosy: docs@python, quentel priority: normal severity: normal status: open title: Buf in cgi module doc type: behavior versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11352> _______________________________________

14 27

[issue9842] Document ... used in recursive repr of containers
by Éric Araujo 20 Nov '18

20 Nov '18

New submission from Éric Araujo <merwok(a)netwok.org>: Built-in containers like dict use an ellipsis to represent a recursive item. In the symbols index, “...” only links to the secondary prompt; I think it should also link to a paragraph explaining the display of recursive containers. ---------- assignee: docs@python components: Documentation keywords: easy messages: 116256 nosy: docs@python, eric.araujo priority: normal severity: normal stage: needs patch status: open title: Document ... used in recursive repr of containers versions: Python 2.7, Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9842> _______________________________________

8 17

[issue11233] clarifying Availability: Unix
by Sandro Tosi 15 Oct '18

15 Oct '18

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: Hi, following up http://mail.python.org/pipermail/docs/2011-February/003083.html we have a chat on #python-dev on the topic, the situation is - all started with os.lchmod() and as.lchflags() methods not available on a Debian system - that's because POSIX does not require those functions and then Linux systems don't provide them - so we then thought about clarifying, only for those 2 methods, that they might not be available with a format like "availability: some unix systems" - then we noticed that on top of os doc there's a notice "An “Availability: Unix” note means that this function is commonly found on Unix systems. It does not make any claims about its existence on a specific operating system." and so we thought about linking every 'Availability: Unix' to that note - or transform that not in a footnote and link every 'Availability: Unix' for functions that might not be present to that footnote. It's enough for the conversation dump: ideas/suggestions? :) ---------- assignee: docs@python components: Documentation messages: 128746 nosy: docs@python, sandro.tosi priority: normal severity: normal status: open title: clarifying Availability: Unix _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11233> _______________________________________

11 25

[issue12743] C API marshalling doc contains XXX
by JJeffries 27 Jul '18

27 Jul '18

New submission from JJeffries <jamesjeffries1(a)gmail.com>: The Python C API manual page for data marshaling contains the following paragraph. XXX What about error detection? It appears that reading past the end of the file will always result in a negative numeric value (where that’s relevant), but it’s not clear that negative values won’t be handled properly when there’s no error. What’s the right way to tell? Should only non-negative values be written using these routines? I suggest that the XXX should be removed as it is unclear why it's there. Patch to follow in the next couple of days if others agree. ---------- assignee: docs@python components: Documentation messages: 141959 nosy: JJeffries, docs@python priority: normal severity: normal status: open title: C API marshalling doc contains XXX _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12743> _______________________________________

7 13

[issue11015] Bring test.support docs up to date
by Nick Coghlan 11 Feb '18

11 Feb '18

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: The test.support docs are there to help CPython devs with writing good unit tests more easily. There are a few additions we've made in recent years that haven't made it into the .rst file, so it is easy to miss useful tools if you don't go looking through the module source code. There are some other helper modules (such as test.script_helper) that could also stand to be made easier to find. Fixing this is just a matter of doing a pass through test.support and the test directory looking for things that might be worth mentioning in the test package docs. ---------- assignee: docs@python keywords: easy messages: 127086 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Bring test.support docs up to date type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11015> _______________________________________

11 36

[issue8722] Documentation for __getattr__
by Paul Davis 05 Feb '18

05 Feb '18

New submission from Paul Davis <paul.joseph.davis(a)gmail.com>: The docs for __getattr__ in the object model section could be more specific on the behavior when a @property raises an AttributeError and there is a custom __getattr__ defined. Specifically, it wasn't exactly clear that __getattr__ would be invoked after a @property was found and evaluated. The attached script demonstrates the issue on OS X 10.6, Python 2.6.1 I'm thinking something along the lines of: If the attribute search encounters an AttributeError (perhaps due to a @property raising the error) the search is considered a failure and __getattr__ is invoked. ---------- assignee: docs@python components: Documentation files: example.py messages: 105790 nosy: Paul.Davis, docs@python priority: normal severity: normal status: open title: Documentation for __getattr__ type: feature request versions: Python 2.6 Added file: http://bugs.python.org/file17349/example.py _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8722> _______________________________________

8 23