[issue7303] pkgutil lacks documentation for useful functions
New submission from ulrik : The module pkgutil has no documentation of functions added after its introduction, in the official python documentation collection. http://docs.python.org/dev/py3k/library/pkgutil.html The module is well documented with docstrings. I assume the module's exposed functions, some very useful, are open for public use, for example pkgutil.iter_modules and .walk_packages. Is all that is required copying the docstrings into the documentation? If someone believes only Python insight and knowledge of reST sytax is enough to make some passable documentation from the existing docstrings, I could submit a patch for that. -- assignee: georg.brandl components: Documentation messages: 95132 nosy: englabenny, georg.brandl severity: normal status: open title: pkgutil lacks documentation for useful functions type: feature request versions: Python 3.2 ___ Python tracker <http://bugs.python.org/issue7303> ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue7417] open builtin has no signature in docstring
New submission from ulrik : Python 3.1.1's open has no signature in the docstring so the documentation for this builtin function is unfortunately very confusing (IMO is missing the most important part). >>> help(open) open(...) Open file and return a stream. Raise IOError upon failure. ... This must be a regression from the C port of the io module. I'm keeping my eyes open for more issues like this. Python must be more friendly to newcomers, but I have seen tendencies of confusing documentation in Python 3. -- components: Library (Lib) messages: 95856 nosy: englabenny severity: normal status: open title: open builtin has no signature in docstring versions: Python 3.1 ___ Python tracker <http://bugs.python.org/issue7417> ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue38788] Inconsistent documentation of tell/seek on textiobase/textiowrapper
New submission from Ulrik Haugen : The class hierarchy suggests the only tell/seek implementations one needs to look up are in iobase and those have the semantics i was expecting: https://docs.python.org/3.8/library/io.html#class-hierarchy Plowing on one might discover that there are separate implementations of tell/seek for textiobase whose documentation probably explains the unexpected values tell returns. The documentation for tell available from the help() command still reflects the semantics i was expecting. The documentation for seek available from the help() command still reflects the semantics i was expecting. It does however suggest that the first argument has been renamed from offset to cookie which the online documentation has not yet caught up to at: https://docs.python.org/3.8/library/io.html#io.TextIOBase.seek The documentation body for seek from the help() command still refers to offset though there is now no argument of that name. >>> help(fh.tell) Help on built-in function tell: tell() method of _io.TextIOWrapper instance Return current stream position. >>> help(fh.seek) Help on built-in function seek: seek(cookie, whence=0, /) method of _io.TextIOWrapper instance Change stream position. Change the stream position to the given byte offset. The offset is interpreted relative to the position indicated by whence. Values for whence are: * 0 -- start of stream (the default); offset should be zero or positive * 1 -- current stream position; offset may be negative * 2 -- end of stream; offset is usually negative Return the new absolute position. -- components: Library (Lib) messages: 356534 nosy: qha priority: normal severity: normal status: open title: Inconsistent documentation of tell/seek on textiobase/textiowrapper versions: Python 3.8 ___ Python tracker <https://bugs.python.org/issue38788> ___ ___ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue7417] open builtin has no signature in docstring
Ulrik Sverdrup added the comment: import builtins; help(builtins) Looking around, the new suggestion is absolutely unconventional. The signature must be on the first line. One builtin function even uses two lines; min: min(iterable[, key=func]) -> value min(a, b, c, ...[, key=func]) -> value With a single iterable argument, return its smallest item. With two or more arguments, return the smallest argument. I would ack a two-line signature at the start of the docstring, however I will also suggest an alternative: Aligning open's signature description with the builtins module, this is the style that is most common: open(file[, mode[, buffering[, encoding[, errors[, newline[, closefd]]) -> file object perhaps even an abbreviation is allowed at the end? open(file[, mode[, buffering[, encoding[, errors[, newline[, closefd]..]) -> file object However that open has so many kwargs should almost be a bug in itself. -- ___ Python tracker <http://bugs.python.org/issue7417> ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
[issue16113] Add SHA-3 (Keccak) support
Ulrik Sverdrup added the comment: Please do not go forward until NIST publishes its SHA-3 specification document. We don't know yet what parameters they will finally choose when making Keccak SHA-3. -- nosy: +englabenny ___ Python tracker <http://bugs.python.org/issue16113> ___ ___ Python-bugs-list mailing list Unsubscribe: http://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
