Mailman 3 January 2011 - docs

tuple or struct_time
by Alexander Belopolsky 03 Jan '11

03 Jan '11

Functions in the time module that expect broken down time are currently documented as accepting "tuple or struct_time". For example, http://docs.python.org/py3k/library/time.html#time.strftime However, in recent versions, ".. or struct_time" is redundant because >>> issubclass(time.struct_time, tuple) True I think it would be more informative for a reader to change "tuple or struct_time" to "9-tuple".

2 3

[issue10818] pydoc: refactorize duplicate DocHandler and DocServer classes
by STINNER Victor 03 Jan '11

03 Jan '11

New submission from STINNER Victor <victor.stinner(a)haypocalc.com>: The pydoc module has two DocHandler classes and two DocServer classes. I think that they can be easily factorized. DocServer may also use serve_forever()+shutdown() instead of serve_until_quit()+quit flag, to be able to wait the server (with shutdown()). ---------- assignee: docs@python components: Documentation, Library (Lib) messages: 125190 nosy: docs@python, haypo priority: normal severity: normal status: open title: pydoc: refactorize duplicate DocHandler and DocServer classes versions: Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10818> _______________________________________

1 1

http://docs.python.org/library/random.html
by Kristoffer Lundgren 03 Jan '11

03 Jan '11

Hi, I suspect I've found a documentation error in the above mentioned link ( http://docs.python.org/library/random.html); regarding random.randint(a, b), the documentation says "Return a random integer N such that a <= N <= b", however when actually using the function, it does seem to be a <= N < b. Running Python 2.6, the built-in help returns Type: builtin_function_or_method Base Class: <type 'builtin_function_or_method'> String Form: <built-in method randint of mtrand.RandomState object at 0x01466 340> Namespace: Interactive Docstring: randint(low, high=None, size=None) Return random integers from `low` (inclusive) to `high` (exclusive). Return random integers from the "discrete uniform" distribution in the "half-open" interval [`low`, `high`). If `high` is None (the default), then results are from [0, `low`). which kind of hints that it should be "<". Best regards Kristoffer Lundgren

3 2

[issue1665333] Documentation missing for OptionGroup class in optparse
by Georg Brandl 02 Jan '11

02 Jan '11

Georg Brandl <georg(a)python.org> added the comment: Looks good, applied in r87627 (after removing stray tabs). ---------- nosy: +georg.brandl resolution: -> fixed status: open -> closed _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue1665333> _______________________________________

1 0

[issue1665333] Documentation missing for OptionGroup class in optparse
by Sandro Tosi 02 Jan '11

02 Jan '11

Sandro Tosi <sandro.tosi(a)gmail.com> added the comment: Could someone give a look to this patch? I can work on fixing the missing stuff (if any :)). ---------- stage: -> patch review _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue1665333> _______________________________________

1 0

[issue8350] Document lack of support for keyword arguments in C functions
by Georg Brandl 02 Jan '11

02 Jan '11

Georg Brandl <georg(a)python.org> added the comment: Hmm, it may indeed be the best option to add a new directive option to say "this function does not take keyword args". It would result in some form of unobtrusive but noticeable output in HTML. It is a bit of an effort to add it everywhere it's necessary, but the most important instances (e.g. string methods) can be covered quickly, and it's fairly easy to grep the other instances (namely, grepping for METH_O and METH_VARARGS without METH_KEYWORDS). ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8350> _______________________________________

3 2

[issue8350] Document lack of support for keyword arguments in C functions
by Terry J. Reedy 02 Jan '11

02 Jan '11

Terry J. Reedy <tjreedy(a)udel.edu> added the comment: If there is no indication in the lib manual as to which parameter names and defaults are real and which are fake, then the safe guideline is to never use keywards for library functions and methods and always pass everything positionally. Slightly more complicated is to be aware of which classes and modules are Python versus C coded. (If needed, change for module.py in /Lib.) For some modules, one can take a cue from doc examples that use keywords. Otherwise, each person has to experiment for himself and check each TypeError messages to determine whether it arises from a misspelling or a hidden limitation. And maybe go through the same process a year later after forgetting. >"We've lived without this spec for almost twenty years," Yes, and people have been stumbling on this and complaining for probably just as long. Since []s are no longer used in the doc to indicate 'optional', they can and are being used to indicate 'position-only'. Specify in the introduction, where notation should be explained, that the limitation is only for current CPython and may be changed in the future or be different for other implementations. However.... In my opinion, the real solution is to remove the limitation. Since the language spec says args can be passed by keyword as well as by position, make it be that way for everything we distribute. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8350> _______________________________________

1 0

[issue8350] Document lack of support for keyword arguments in C functions
by Terry J. Reedy 02 Jan '11

02 Jan '11

Terry J. Reedy <tjreedy(a)udel.edu> added the comment: I think that the warning that things are not always as they seem should be repeated in the front of the library manual where the pseudo-arg names are actual used, so the library manual stands on its own. In any case, I believe a lot of people use the lib ref without reading and remembering every detail of the language ref. ---------- nosy: +terry.reedy versions: -Python 2.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8350> _______________________________________

1 0

[issue8350] Document lack of support for keyword arguments in C functions
by Raymond Hettinger 02 Jan '11

02 Jan '11

Raymond Hettinger <rhettinger(a)users.sourceforge.net> added the comment: This is an implementation detail specific to CPython and subject to change. I'm -1 on documenting it for every function/method and thereby making it part of the language spec. We've lived without this spec for almost twenty years, so I'm inclined to think it is truly unimportant. It is sufficient to mention just once in the docs that CPython functions/methods sometimes don't take keywords. ---------- nosy: +rhettinger _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8350> _______________________________________

1 0

[issue8350] Document lack of support for keyword arguments in C functions
by Georg Brandl 02 Jan '11

02 Jan '11

Georg Brandl <georg(a)python.org> added the comment: Yes. It's still an important detail; the explanation could say, "In CPython, this function does not take keyword args" and furthermore it's not really clear to me how much of the library reference applies to all Python implementations anyway. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8350> _______________________________________

1 0

docs January 2011