Mailman 3 November 2015 - docs

[issue22576] ftplib documentation gives a wrong argument name for storbinary
by Derek Kurth 13 Mar '17

13 Mar '17

New submission from Derek Kurth: The Python 3 documentation for ftplib gives the storbinary method signature as: FTP.storbinary(cmd, file, blocksize=8192, callback=None, rest=None) However, the parameter named "file" is actually named "fp" in the code, so if you do something like this: ftp.storbinary(cmd="RETR something.txt", file=f) then you will get a TypeError: storbinary() got an unexpected keyword argument 'file'. I think the documentation should be updated to call that argument "fp" instead of "file." ---------- assignee: docs@python components: Documentation messages: 228773 nosy: Derek.Kurth, docs@python priority: normal severity: normal status: open title: ftplib documentation gives a wrong argument name for storbinary versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22576> _______________________________________

4 4

[issue17003] Unification of read() and readline() argument names
by Serhiy Storchaka 07 Mar '17

07 Mar '17

New submission from Serhiy Storchaka: read() and readline() optional parameter which limit the amount of read data has different names in different classes. All this classes mimic (less or more) io classes. Keyword parameter name is a part of method specification. Therefore it will be good made all read() arguments names the same and all readline() arguments names the same (and be consistent with documentation and C implementation). At least we should choose most consistent name for new implementations. If existent C implementation of some method doesn't support keyword argument (all _io classes) or argument names in C and Python implementations are different then we are free to change this name without breaking existing code. For example, read()'s parameter named as: "n" in _pyio, zipfile, and io documentation; "size" in gzip, bz2, imaplib, tarfile, codecs, mailbox; "len" in ssl; "wtd" or "totalwtd" in binhex; "amt" in http/client; "chars" in codecs; "buffersize" in os. readline()'s parameter named as: "limit" in _pyio, zipfile, and io documentation; "size" in gzip, bz2, codecs, mailbox, lzma. ---------- assignee: docs@python components: Documentation, IO, Library (Lib) messages: 180298 nosy: benjamin.peterson, christian.heimes, docs@python, hynek, pitrou, serhiy.storchaka, stutzbach priority: normal severity: normal status: open title: Unification of read() and readline() argument names type: enhancement _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17003> _______________________________________

5 10

[issue18423] Document limitations on -m
by andrew cooke 23 Feb '17

23 Feb '17

New submission from andrew cooke: Apparently the limited support for -m is standard behaviour - see http://bugs.python.org/issue18422 - but it's not documented at http://docs.python.org/3/using/cmdline.html#cmdoption-m That should say, somewhere, that it only applies to leaf modules and packages. ---------- assignee: docs@python components: Documentation messages: 192804 nosy: acooke, docs@python priority: normal severity: normal status: open title: Document limitations on -m _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18423> _______________________________________

6 6

[issue15657] Error in Python 3 docs for PyMethodDef
by Sandro Tosi 22 Feb '17

22 Feb '17

New submission from Sandro Tosi: Hello, it has been reported at http://mail.python.org/pipermail/docs/2012-April/008215.html but given it raises some question whether it's a bug in the doc or in the code, i'd rather report the issue here and hear what other think: >>> In the Python 3.2.2 documentation (and earlier Python 3 versions), in the Python/C API Reference Manual, chapter Object Implementation Support, the documentation for PyMethodDef says: The ml_flags field is a bitfield which can include the following flags. The individual flags indicate either a calling convention or a binding convention. Of the calling convention flags, only METH_VARARGS and METH_KEYWORDS can be combined (but note that METH_KEYWORDS alone is equivalent to METH_VARARGS | METH_KEYWORDS). The bit in the parenthetical is incorrect. If you take a look at PyCFunction_Call in Objects/methodobject.c, you will find a switch for METH_VARARGS | METH_KEYWORDS, but no switch for METH_KEYWORDS. Hence, using METH_KEYWORDS will land you with a SystemError that complains about METH_OLDARGS. This is either a bug in the documentation, or a bug in Python. In this case, since the code has persisted through three major revisions of Python 3, I suggest that the bug _is_ in the documentation (whether it should be or not), since changing the code for this at this late date means a programmer has to use METH_VARARGS | METH_KEYWORDS anyway for compatibility. It may be work pointing out specifically in the documentation that just using METH_KEYWORDS will not work. <<< ---------- assignee: docs@python components: Documentation messages: 168226 nosy: docs@python, sandro.tosi priority: normal severity: normal stage: patch review status: open title: Error in Python 3 docs for PyMethodDef versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15657> _______________________________________

12 18

[issue10938] Undocumented option for datetime.strftime: %s
by Humberto Diogenes 22 Feb '17

22 Feb '17

New submission from Humberto Diogenes <humberto(a)digi.com.br>: On some systems, datetime.strftime() accepts a %s format string that returns epoch / UNIX timestamp, but this behavior is not documented at http://docs.python.org/library/datetime.html Python 2.7 (r27:82508, Jul 3 2010, 21:12:11) [GCC 4.0.1 (Apple Inc. build 5493)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> import datetime >>> datetime.datetime.now().strftime('%s') '1295376929' ---------- assignee: docs@python components: Documentation messages: 126481 nosy: docs@python, hdiogenes priority: normal severity: normal status: open title: Undocumented option for datetime.strftime: %s versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10938> _______________________________________

7 9

[issue11924] Pickle and copyreg modules doesn't document the interface
by Jesús Cea Avión 18 Feb '17

18 Feb '17

New submission from Jesús Cea Avión <jcea(a)jcea.es>: Python 3.2 here. "copyreg" module documentation says "See the pickle module for more details on the interface expected of function and constructor.", but I don't see any useful "copyreg" reference in pickle documentation. Some examples would be useful here, too. ---------- assignee: docs@python messages: 134416 nosy: docs@python, jcea priority: normal severity: normal status: open title: Pickle and copyreg modules doesn't document the interface versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11924> _______________________________________

5 6

[issue23109] French quotes in the documentation are often ungrammatical
by Clément 15 Feb '17

15 Feb '17

New submission from Clément: >From https://docs.python.org/3/howto/unicode.html: > For a while people just wrote programs that didn’t display accents. > In the mid-1980s an Apple II BASIC program written by a French > speaker might have lines like these: > > PRINT "FICHIER EST COMPLETE." > PRINT "CARACTERE NON ACCEPTE." > > Those messages should contain accents (completé, caractère, accepté), > and they just look wrong to someone who can read French. One of the reasons the message looks wrong is that "FICHIER EST COMPLETE" in ungrammatical in French. Google has 16 hits for that query, half of which are from the Python documentation. The second one is better. I imagine the first one comes from the English "FILE IS COMPLETE", but I'm not even sure what that meant, so it's hard to give a better translation :/ Instead, here are a few examples that could work: MISE A JOUR TERMINEE (Update completed − missing à and é in terminée) VEUILLEZ REDEMARRER (Please reboot − missing é in redémarrer) PARAMETRES ENREGISTRES (Settings saved − missing è in paramètre and é in enregistrés) Similarly, https://docs.python.org/3/library/email-examples.html#examples-using-the-pr…: > msg['Subject'] = "Ayons asperges pour le déjeuner" I imagine this comes from the English "Let's have asparagus for lunch!", but the translation reads "Possess asparagus for lunch we". A proper idiomatic French version would be "Ça te dirait de manger des asperges à midi?" (Would you like to eat asparagus for lunch?) Again further on the same page: > Cela ressemble à un excellent recipie[1] déjeuner. Could this mean "This looks like a delicious lunch recipie?" The typo in recipie would have prevented the machine translation from picking up recipie, which survived in the French version? This currently reads "This look like recipie lunch a excellent". A proper French version (adjusted to have accents) might be "J'ai trouvé une recette sympa: [1]" ("I found a nice recipe: [1]"). Not sure why using French is needed though; English already has a few accented words: a message with subject "Résumé attached", and body "Here's my résumé" would probably work just as well, and might not divert the reader's attention as much. Side note: in the example Pépé writes to Fabrette and Penelope. Aren't they the same character? Clément. ---------- assignee: docs@python components: Documentation messages: 233076 nosy: cpitcla, docs@python priority: normal severity: normal status: open title: French quotes in the documentation are often ungrammatical 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/issue23109> _______________________________________

6 6

[issue18779] Misleading documentations and comments in regular expression about alphanumerics and underscore
by Vajrasky Kok 15 Feb '17

15 Feb '17

New submission from Vajrasky Kok: According to: http://oald8.oxfordlearnersdictionaries.com/dictionary/alphanumeric http://en.wikipedia.org/wiki/Alphanumeric Alphanumeric is defined as [A-Za-z0-9]. Underscore (_) is not one of them. One of the documentation in Python (Doc/tutorial/stdlib2.rst) differentiates them very clearly: "The format uses placeholder names formed by ``$`` with valid Python identifiers (alphanumeric characters and underscores). Surrounding the placeholder with braces allows it to be followed by more alphanumeric letters with no intervening spaces. Writing ``$$`` creates a single escaped ``$``::" Yet, in documentations as well as comments in regex, we implicitely assumes underscore belongs to alphanumeric. Explicit is better than implicit! Attached the patch to differentiate alphanumeric and underscore in documentations and comments in regex. This is important in case someone is confused with this code: >>> import re >>> re.split('\W', 'haha$hihi*huhu_hehe hoho') ['haha', 'hihi', 'huhu_hehe', 'hoho'] On the side note: In Python code base, sometimes we write "alphanumerics" and "underscores", yet sometimes we write "alphanumeric characters" and "underscore characters". Which one again is the true way? ---------- assignee: docs@python components: Documentation files: fix_alphanumeric_and_underscore_doc_in_regex.patch keywords: patch messages: 195611 nosy: akuchling, docs@python, vajrasky priority: normal severity: normal status: open title: Misleading documentations and comments in regular expression about alphanumerics and underscore versions: Python 3.3, Python 3.4 Added file: http://bugs.python.org/file31371/fix_alphanumeric_and_underscore_doc_in_reg… _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18779> _______________________________________

5 6

[issue11173] Undocumented public APIs in Python 3.2
by Marc-Andre Lemburg 14 Feb '17

14 Feb '17

New submission from Marc-Andre Lemburg <mal(a)egenix.com>: Mark Shannon on python-dev: The following API functions were removed from 3.1.3: PyAST_Compile PyCObject_AsVoidPtr PyCObject_FromVoidPtr PyCObject_FromVoidPtrAndDesc PyCObject_GetDesc PyCObject_Import PyCObject_SetVoidPtr PyCode_CheckLineNumber Py_CompileStringFlags PyEval_CallObject PyOS_ascii_atof PyOS_ascii_formatd PyOS_ascii_strtod PyThread_exit_prog PyThread__PyThread_exit_prog PyThread__PyThread_exit_thread PyUnicode_SetDefaultEncoding And the following were added to 3.2, of which only 2 are documented: PyArg_ValidateKeywordArguments PyAST_CompileEx Py_CompileString Py_CompileStringExFlags PyErr_NewExceptionWithDoc (documented) PyErr_SyntaxLocationEx PyErr_WarnFormat PyFrame_GetLineNumber PyImport_ExecCodeModuleWithPathnames PyImport_GetMagicTag PyLong_AsLongLongAndOverflow (documented) PyModule_GetFilenameObject Py_SetPath PyStructSequence_GetItem PyStructSequence_NewType PyStructSequence_SetItem PySys_AddWarnOptionUnicode PySys_AddXOption PySys_FormatStderr PySys_FormatStdout PySys_GetXOptions PyThread_acquire_lock_timed PyType_FromSpec PyUnicode_AsUnicodeCopy PyUnicode_AsWideCharString PyUnicode_EncodeFSDefault PyUnicode_FSDecoder Py_UNICODE_strcat Py_UNICODE_strncmp Py_UNICODE_strrchr PyUnicode_TransformDecimalToASCII For added confusion PySys_SetArgvEx is documented as new in 3.2, but exists in 3.1.3 Note that this only include functions. The API also includes a number of macros such as Py_False and Py_RETURN_FALSE, types , and data like PyBool_Type. ---------- assignee: docs@python components: Documentation messages: 128294 nosy: docs@python, lemburg priority: normal severity: normal status: open title: Undocumented public APIs in Python 3.2 versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11173> _______________________________________

5 7

[issue11726] linecache becomes specific to Python scripts in Python 3
by STINNER Victor 09 Feb '17

09 Feb '17

New submission from STINNER Victor <victor.stinner(a)haypocalc.com>: linecache document doesn't tell that the module reads the #coding:xxx cookie to get the encoding of the Python file. linecache reads this cookie since 41665 (May 09 2007). "The linecache module allows one to get any line from any file, ..." => "any file"! And the example uses /etc/passwd which is not a Python file. Not only it reads the #coding:xxx cookie, but updatecache() tries also a PEP 302 loader to read the file. linecache should be marked as very specific to Python scripts, or it should be patched to become more generic (don't read the cookie / use loader by default). Note: the locale encoding may change between to calls to the linecache module. ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 132641 nosy: docs@python, haypo priority: normal severity: normal status: open title: linecache becomes specific to Python scripts in Python 3 versions: Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11726> _______________________________________

8 16