Mailman 3 February 2017 - docs

[issue22702] to improve documentation for join() (str method)
by Serhiy Storchaka Feb. 18, 2017

Feb. 18, 2017

Serhiy Storchaka added the comment: Current documentation looks good to me and not needing changes (except fixing the doubled "iterable"). Proposed change looks incorrect to me. No parameter named "str" is provided in this method. See also the docstring of str.join. ---------- nosy: +serhiy.storchaka _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22702> _______________________________________

1 0

[issue22702] to improve documentation for join() (str method)
by Sanyam Khurana Feb. 18, 2017

Feb. 18, 2017

Changes by Sanyam Khurana <sanyam.khurana01(a)gmail.com>: ---------- pull_requests: +120 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue22702> _______________________________________

1 0

[issue29481] 3.6.0 doc describes 3.6.1 feature - typing.Deque
by Guy Arad Feb. 18, 2017

Feb. 18, 2017

New submission from Guy Arad: See: - https://docs.python.org/3.6/library/typing.html#typing.Deque - https://docs.python.org/3.5/library/typing.html#typing.Deque `typing.Deque` is expected to be included in 3.6.1: https://docs.python.org/3/whatsnew/changelog.html#python-3-6-1-release-cand… Please remove or specify the version in which it's going to be included. ---------- assignee: docs@python components: Documentation messages: 287313 nosy: Guy Arad, docs@python priority: normal severity: normal status: open title: 3.6.0 doc describes 3.6.1 feature - typing.Deque versions: Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29481> _______________________________________

8 18

Slice Example in Documentation
by Ryan Noonan Feb. 17, 2017

Feb. 17, 2017

Hello, In the Python documentation for slice the following definition is given: slice - An object usually containing a portion of a sequence. A slice is created using the subscript notation, [] with colons between numbers when several are given, such as in variable_name[1:3:5]. The bracket (subscript) notation uses slice objects internally. If variable_name[1:3:5] = [start:stop:step] How can you step or stride by 5 through a smaller number (slice of 1:3)? Maybe this is a documentation error. If not, I apologize. I could not make sense of it. Thanks, Ryan Sent from my iPad

1 1

A rather Odd error..
by Waqar Ahmad Feb. 17, 2017

Feb. 17, 2017

Hi folks at Python.org, Thank you so much for looking at my screenshot here. I'm seeing this odd error whenever I try to run my new program (Hitting F5) it just doesnt run it and highlights the 3.*6.*0 in the error screen in red. Please see screenshot attached. Id' really appreciate some guidance on this. I googled and it looked like Windows 10 doesnt like Python 3.6.0.. perhaps this could be the reason? Or I may be a complete noob I just started programming 3 weeks ago! Thanks so much Cheers! Waqar[image: Inline image 1]

1 0

[issue29563] Update Devguide about building documentation.
by Jim DeLaHunt Feb. 15, 2017

Feb. 15, 2017

New submission from Jim DeLaHunt: The Devguide section 7.5.1 "Building the documentation" / "Using make / make.bat" is out of date. The document lists 10 documentation targets for `make`. The Doc/Makefile lists 17. One important omission is `make check`, which looks for errors in reStructuredText syntax, using `rstlint.py`. It's important for contributors to know about and to run `make check`, because with the move to GitHub, the project is running make check after pulling in new code. If contributors haven't cleaned up their submissions, the build fails. I suggest that the following improvements be made: 1. rewrite the bullet list "Available make targets are:" in 7.5.1 https://cpython-devguide.readthedocs.io/documenting.html#using-make-make-bat to match the list of targets in Doc/Makefile:21-38. 2. add a comment that `make help` will give the most up-to-date list of targets from the makefile, which might be better than the list in the Devguide. 3. add `make help` to both Doc/Makefile:21-38 and Devguide 7.5.1. 4. add to Devguide 6.3. "Helping with the Developer’s Guide" an instruction to run `make check` before submitting a pull request to the Devguide. ---------- assignee: docs@python components: Documentation messages: 287808 nosy: JDLH, docs@python priority: normal severity: normal status: open title: Update Devguide about building documentation. type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29563> _______________________________________

3 4

[issue29531] Update Doc/README.txt to README.rst
by Roger Sachan Feb. 15, 2017

Feb. 15, 2017

New submission from Roger Sachan: I have simply updated the document and its references to README.rst (thanks to whoever formatted it). ---------- assignee: docs@python components: Documentation messages: 287590 nosy: Roger Sachan, docs@python priority: normal pull_requests: 29 severity: normal status: open title: Update Doc/README.txt to README.rst type: enhancement versions: Python 3.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue29531> _______________________________________

1 5

[issue23109] French quotes in the documentation are often ungrammatical
by Clément Feb. 15, 2017

Feb. 15, 2017

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 Feb. 14, 2017

Feb. 14, 2017

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 Feb. 14, 2017

Feb. 14, 2017

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