Mailman 3 November 2015 - docs

[issue16544] Add external link to ast docs
by Andrew Svetlov 07 Jan '16

07 Jan '16

New submission from Andrew Svetlov: http://greentreesnakes.readthedocs.org/en/latest/index.html is excellent and comprehensive documentation for ast tree structures. It would be nice to incorporate that docs into stdlib documentation, but adding *see also* section is good enoigh as first step. ---------- assignee: docs@python components: Documentation keywords: easy messages: 176239 nosy: asvetlov, docs@python priority: normal severity: normal stage: needs patch status: open title: Add external link to ast docs versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue16544> _______________________________________

7 11

[issue18918] help('FILES') finds no documentation
by bussau 06 Jan '16

06 Jan '16

New submission from bussau: Calling for help() about the topic 'FILES' returns no documentation found for 'FILES' ------------------------------ Python 2.7.3 (default, Apr 14 2012, 08:58:41) [GCC] on linux2 Type "help", "copyright", "credits" or "license" for more information. >>> help('topics') Here is a list of available topics. Enter any topic name to get more help. ASSERTION DEBUGGING LITERALS SEQUENCEMETHODS2 ASSIGNMENT DELETION LOOPING SEQUENCES ATTRIBUTEMETHODS DICTIONARIES MAPPINGMETHODS SHIFTING ATTRIBUTES DICTIONARYLITERALS MAPPINGS SLICINGS AUGMENTEDASSIGNMENT DYNAMICFEATURES METHODS SPECIALATTRIBUTES BACKQUOTES ELLIPSIS MODULES SPECIALIDENTIFIERS BASICMETHODS EXCEPTIONS NAMESPACES SPECIALMETHODS BINARY EXECUTION NONE STRINGMETHODS BITWISE EXPRESSIONS NUMBERMETHODS STRINGS BOOLEAN FILES NUMBERS SUBSCRIPTS CALLABLEMETHODS FLOAT OBJECTS TRACEBACKS CALLS FORMATTING OPERATORS TRUTHVALUE CLASSES FRAMEOBJECTS PACKAGES TUPLELITERALS CODEOBJECTS FRAMES POWER TUPLES COERCIONS FUNCTIONS PRECEDENCE TYPEOBJECTS COMPARISON IDENTIFIERS PRINTING TYPES COMPLEX IMPORTING PRIVATENAMES UNARY CONDITIONAL INTEGER RETURNING UNICODE CONTEXTMANAGERS LISTLITERALS SCOPING CONVERSIONS LISTS SEQUENCEMETHODS1 >>> help('FILES') no documentation found for 'FILES' -------------------------------------------------------- best regards stephan ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 196888 nosy: docs@python, st.sempert(a)gmail.com priority: normal severity: normal status: open title: help('FILES') finds no documentation type: behavior versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue18918> _______________________________________

9 10

[issue17006] Warn users about hashing secrets?
by Christian Heimes 04 Jan '16

04 Jan '16

New submission from Christian Heimes: Lot's of people still think that something like sha512(secret + message), sha1(password + salt) or even sha1(password) is secure. Except it isn't. Most crypto hash functions like md5, sha1, sha2 family (sha256, sha384, sha512) use a Merkle–Damgård construction [1]. The construction is vulnerable to several attack vectors like length extension attacks. Passwords needs special care, too. I propose we add a warning to the documentation of hashlib. It's not the right place to teach cryptographics but it's a good place to raise attention. The warning should explain that you shouldn't solely hash secrets or messages containing a secret. For messages a MAC algorithm like HMAC should be used. For passwords a key stretching and key derivation function like PBKDF2, bcrypt or scrypt is much more secure. [1] http://en.wikipedia.org/wiki/Merkle%E2%80%93Damg%C3%A5rd_construction ---------- assignee: docs@python components: Documentation messages: 180330 nosy: christian.heimes, docs@python priority: normal severity: normal status: open title: Warn users about hashing secrets? type: enhancement versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue17006> _______________________________________

14 26

[issue25743] Clarify exactly what \w matches in UNICODE mode
by Zack Weinberg 04 Jan '16

04 Jan '16

New submission from Zack Weinberg: The `re` module documentation does not do a good job of explaining exactly what `\w` matches. Quoting https://docs.python.org/3.5/library/re.html : > \w > For Unicode (str) patterns: > Matches Unicode word characters; this includes most characters > that can be part of a word in any language, as well as numbers > and the underscore. Empirically, this appears to mean "everything in Unicode general categories L* and N*, plus U+005F (underscore)". That is a perfectly sensible definition and the documentation should state it in those terms. "Unicode word characters" could mean any number of different things; note for instance that UTS#18 gives a very different definition. (Further reading: https://gist.github.com/zackw/3077f387591376c7bf67 plus links therefrom). ---------- assignee: docs@python components: Documentation messages: 255463 nosy: docs@python, zwol priority: normal severity: normal status: open title: Clarify exactly what \w matches in UNICODE mode 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/issue25743> _______________________________________

3 3

[issue25381] Use old description of raise in Python3
by Xiang Zhang 04 Jan '16

04 Jan '16

New submission from Xiang Zhang: In the first paragraph of https://docs.python.org/3/extending/extending.html#intermezzo-errors-and-ex…, it is wrong to use the sentence "the second argument to raise" since the raise syntax has been changed in Python3. ---------- assignee: docs@python components: Documentation files: doc_extending.patch keywords: patch messages: 252848 nosy: docs@python, xiang.zhang priority: normal severity: normal status: open title: Use old description of raise in Python3 Added file: http://bugs.python.org/file40754/doc_extending.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25381> _______________________________________

7 15

[issue24898] Documentation for str.find() is confusing
by Ted Lemon 04 Jan '16

04 Jan '16

New submission from Ted Lemon: The documentation for str.find() on python.org, for all current versions, says: Return the lowest index in the string where substring sub is found, such that sub is contained in the slice s[start:end]. Optional arguments start and end are interpreted as in slice notation. Return -1 if sub is not found. I think that what is meant here is this: Return the lowest index in a string s where substring sub is found, such that if a is the returned index, and b == a + len(sub), sub is contained in the slice s[a:b]. Optional arguments start and end are interpreted as in slice notation. Return -1 if sub is not found. ---------- assignee: docs@python components: Documentation messages: 248872 nosy: Ted Lemon, docs@python priority: normal severity: normal status: open title: Documentation for str.find() is confusing versions: Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue24898> _______________________________________

5 6

[issue19576] "Non-Python created threads" documentation doesn't mention PyEval_InitThreads()
by STINNER Victor 03 Jan '16

03 Jan '16

New submission from STINNER Victor: While working on a unit test for the issue #14432, I hit a bug. My C thread got the GIL with PyGILState_Ensure(), but it was strange because the main Python thread also had the GIL... Then I saw that gil_created() returned false. The solution is to call PyEval_InitThreads() to create the GIL. I was reading "Non-Python created threads" documentation, but this section doesn't mention PyEval_InitThreads(). I don't know if it's something new in Python 3.2 with the new GIL. ---------- assignee: docs@python components: Documentation messages: 202787 nosy: christian.heimes, docs@python, haypo, pitrou priority: normal severity: normal status: open title: "Non-Python created threads" documentation doesn't mention PyEval_InitThreads() versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue19576> _______________________________________

5 7

[issue21221] Minor struct_time documentation bug
by Andrew Scheller 03 Jan '16

03 Jan '16

New submission from Andrew Scheller: The documentation for time.struct_time (in Doc/library/time.rst) explains tm_isdst as "0, 1 or -1; see below" but then doesn't really go into further detail below, other than to say "A -1 argument as the daylight savings flag, passed to mktime() will usually result in the correct daylight savings state to be filled in.". In Modules/timemodule.c there's a section which says: {"tm_isdst", "1 if summer time is in effect, 0 if not, and -1 if unknown"}, IMHO it would be nice if this more accurate info was also present in the HTML documentation. ---------- assignee: docs@python components: Documentation messages: 216158 nosy: docs@python, lurchman priority: normal severity: normal status: open title: Minor struct_time documentation bug type: enhancement versions: Python 2.7, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21221> _______________________________________

8 9

[issue25768] compileall functions do not document return values
by Nicholas Chammas 27 Dec '15

27 Dec '15

New submission from Nicholas Chammas: I'm using the public functions of Python's built-in compileall module. https://docs.python.org/3/library/compileall.html#public-functions There doesn't appear to be documentation of what each of these functions returns. I figured out, for example, that compileall.compile_file() returns 1 when the file compiles successfully, and 0 if not. If this is "official" behavior, it would be good to see it documented so that we can rely on it. I'd be happy to submit a patch to fix this if a committer is willing to shepherd a new contributor (me) through the process. Otherwise, this is probably a quick fix for experienced contributors. ---------- assignee: docs@python components: Documentation messages: 255600 nosy: Nicholas Chammas, docs@python priority: normal severity: normal status: open title: compileall functions do not document return values type: behavior versions: Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25768> _______________________________________

3 18

[issue12484] The Py_InitModule functions no longer exist, but remain in the docs
by Alejandro Santos 27 Dec '15

27 Dec '15

New submission from Alejandro Santos <alejolp(a)alejolp.com>: While the "Py_InitModule" does not exists on Py3k it is still mentioned on the docs: http://docs.python.org/py3k/extending/extending.html#keyword-parameters-for… http://docs.python.org/py3k/extending/windows.html#a-cookbook-approach http://docs.python.org/py3k/faq/extending.html#what-does-systemerror-pyimpo… ---------- assignee: docs@python components: Documentation messages: 139728 nosy: alejolp, docs@python priority: normal severity: normal status: open title: The Py_InitModule functions no longer exist, but remain in the docs versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12484> _______________________________________

8 16