Mailman 3 May 2011 - docs

[issue9938] Documentation for argparse interactive use
by Jay T 12 Sep '19

12 Sep '19

New submission from Jay T <jaytula(a)gmail.com>: I want to create a custom interactive shell where I continually do parse_args. Like the following: parser = argparse.ArgumentParser() command = raw_input() while(True): args = parser.parse_args(shlex.split(command)) # Do some magic stuff command = raw_input() The problem is that if I give it invalid input, it errors and exits with a help message. I learned from argparse-users group that you can override the exit method like the following: class MyParser(ArgumentParser): def exit(self, status=0, message=None): # do whatever you want here I would be nice to have this usage documented perhaps along with best practices for doing help messages in this scenario. ---------- assignee: docs@python components: Documentation messages: 117287 nosy: docs@python, jayt priority: normal severity: normal status: open title: Documentation for argparse interactive use type: feature request versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue9938> _______________________________________

16 28

[issue12077] Harmonizing descriptor protocol documentation
by Davide Rizzo 29 Aug '19

29 Aug '19

New submission from Davide Rizzo <sorcio(a)gmail.com>: There are three sources of information for the descriptor protocol: - Data model reference (Doc/reference/datamodel.rst) - Descriptor HowTo guide (Doc/howto/descriptor.rst) - PEP 252 A developer who already knows descriptor tipically reads the first one: object.__get__(self, instance, owner) "... owner is always the owner class ..." Reading a bit further there are the ways a descriptor can be called, and the "direct call" is x.__get__(a). That is, without the third argument (owner) specified. The how-to definition is slightly different: descr.__get__(self, obj, type=None) --> value Here the arguments have different names ("type" shadowing the type bultin) and it seems to be implied that the third argument is optional. The ClassMethod example at the end of the document seems to confirm this: def __get__(self, obj, klass=None): (though another example doesn't). And the method contains an explicit check on klass being None. Also it could be confusing that through the examples in the same document many different names are used for the same argument (type, objtype, klass), and all different than the name used in the reference. Lastly the PEP is more explicit: __get__(): a function callable with one or two arguments. [...] When X is None, the optional second argument, T, should be meta-object. [...] When both X and T are specified ... One more quirk: the reference explains the distinction between data and non-data descriptors, though says nothing about __set__ raising AttributeError for read-only data descriptors. My proposal: - use the same names for __get__ arguments throughout the documentation (both the reference and the tutorial), e.g. __get__(self, instance, owner) - decide whether the third argument should be optional, or state the common usage in the reference, and fix accordingly the examples in the howto - explain data, non-data and read-only descriptors in the __set__ reference, or more simply, how the defintion of __set__ affects these things. ---------- assignee: docs@python components: Documentation messages: 135974 nosy: davide.rizzo, docs@python priority: normal severity: normal status: open title: Harmonizing descriptor protocol documentation versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12077> _______________________________________

9 17

[issue11165] Document PyEval_Call* functions
by Nick Coghlan 08 Aug '19

08 Aug '19

New submission from Nick Coghlan <ncoghlan(a)gmail.com>: There are currently undocumented PyEval_Call* equivalents to a number of the PyObject_Call* functions. Since there are resources out there on the web that direct people to use the currently undocumented PyEval functions, it would be good to document those properly, and recommend people typically use the PyObject_Call* variants instead (as the latter include all the stack and interpreter state integrity protection code, while the PyEval variants assume that has all already been handled). ---------- assignee: docs@python components: Documentation keywords: easy messages: 128248 nosy: docs@python, ncoghlan priority: normal severity: normal stage: needs patch status: open title: Document PyEval_Call* functions versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11165> _______________________________________

9 12

[issue12217] Cross-link docs for faulthandler, traceback and pdb
by Éric Araujo 13 Jul '19

13 Jul '19

New submission from Éric Araujo <merwok(a)netwok.org>: haypo suggested linking between traceback.print_tb and faulthandler.dump_traceback(). See also links between pdb and faulthandler could also be nice, if they explain briefly how the modules differ. ---------- assignee: docs@python components: Documentation keywords: easy messages: 137298 nosy: docs@python, eric.araujo, haypo priority: normal severity: normal stage: needs patch status: open title: Cross-link docs for faulthandler, traceback and pdb versions: Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12217> _______________________________________

4 5

[issue10536] Enhancements to gettext docs
by Éric Araujo 10 May '19

10 May '19

New submission from Éric Araujo <merwok(a)netwok.org>: A patch made for #2504 revealed a bug in gettext.rst, and I’ve found a number of other things to change in the file. This is the first patch of a series of two or three. Barry, as the original author of the module and doc, I’d like your opinion on points 3, a, and b particularly. Patch is also uploaded to Rietveld for greater convenience: http://codereview.appspot.com/3333042/ (upload.py rocks) Summary: 1) Markup: Use modern class/method directives combo (yay DRY). Mark up variable parts in :file: constructs (e.g. :file:`{domain}.mo` will cause the HTML output to use var to indicate replaceable text). Also change some ``gettext`` to :program:`gettext` for consistency. 2) Fix a typo in lngettext doc (originally included in patch by Franz Glasner for #2504). 3) I had started to remove information about private attributes (_info, _charset), advertising public getter methods instead. Then I read the description of NullTranslations and realized the information was needed for subclasses. I’ve reverted my removals, but I still think the private attributes should be listed in a specific section for people writing subclasses and not in the rest of the text. If you’re okay, I’ll make a second patch. 4) Assorted wording changes, missing periods and hyphens, and other very small touch-ups: Turned a broken bare link into a working link with nice text; used the with statement in an example (we all love the with statement!); used two spaces after periods throughout (hello Fred Drake). Final note: lines have not been rewrapped, for diff clarity. When I commit part or all of this patch, I’ll make another commit to rewrap. Not addressed: a) The current docs is currently POSIX-specific. b) The docs take great care to explain that Unicode strings will be returned in different places, but this should not be so accented in 3.x docs IMO. I would just put a note somewhere near the top that all strings are str and remove the redundant sentences. Following that line of thought, I could group all l*gettext variants at the end of the list of methods, explaining that regular usage should just be happy with str objects and that l*gettext are available if people really want bytes. c) The file uses “built-in namespace” and “builtins namespace”, sometimes in neighbor paragraphs. :mod:`builtins` is not used, even in explanations of the install function/method. I don’t know if I should change that. d) Some capitalization patterns look strange to me: I have seen “I18N” and “L10N” in upper case nowhere else. Similarly, lower-case “id” looks stranger than “ID”. The latter is used for example in official GNU gettext docs. Am I going into foolish consistency territory or not? Thanks in advance for reviews and opinions. ---------- assignee: eric.araujo components: Documentation files: gettext-docs-1.diff keywords: needs review, patch messages: 122420 nosy: barry, docs@python, eric.araujo priority: normal severity: normal stage: patch review status: open title: Enhancements to gettext docs versions: Python 2.7, Python 3.1, Python 3.2 Added file: http://bugs.python.org/file19819/gettext-docs-1.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10536> _______________________________________

8 17

[issue12188] PEP 7, C style: add ++ policy and explanation
by Terry J. Reedy 09 May '19

09 May '19

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: In response to a discussion of a patch removing 'useless' post-increments, (which issue has apparently come up before) Guido posted "> Sorry to butt in here, but I agree with Eric that it was better > before. There is a common idiom, *pointer++ =<something>, and > whenever you see that you know that you are appending something to an > output buffer. Perhaps the most important idea here is that this > maintains the *invariant* "pointer points just after the last thing in > the buffer". Always maintaining the invariant is better than trying to > micro-optimize things so as to avoid updating dead values. The > compiler is better at that." A condensed version of the above added to PEP 7 would help new developers see the usage as local idiom rather than style bug. ---------- assignee: docs@python components: Documentation messages: 136991 nosy: docs@python, terry.reedy priority: normal severity: normal status: open title: PEP 7, C style: add ++ policy and explanation _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12188> _______________________________________

7 11

[issue11001] Various obvious errors in cookies documentation
by Luke Plant 07 May '19

07 May '19

New submission from Luke Plant <L.Plant.98(a)cantab.net>: Docs for SimpleCookie, BaseCookie.value_encode and BaseCookie.value_decode are obviously incorrect. Attempt at patch attached. The error has existed in every Python version I've seen, I've tagged the ones I believe can receive fixes, sorry if I've made a mistake. Thanks. ---------- assignee: docs@python components: Documentation files: http_cookies_doc_corrections.diff keywords: patch messages: 126962 nosy: docs@python, spookylukey priority: normal severity: normal status: open title: Various obvious errors in cookies documentation versions: Python 2.7, Python 3.1, Python 3.2 Added file: http://bugs.python.org/file20507/http_cookies_doc_corrections.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11001> _______________________________________

8 12

[issue10789] Lock.acquire documentation is misleading
by Jyrki Pulliainen 27 Apr '19

27 Apr '19

New submission from Jyrki Pulliainen <jyrki(a)dywypi.org>: In threading module, the Lock.acquire documentation is misleading. The signature suggests that the blocking can be given as a keyword argument but that would lead to an TypeError, as thread.lock.acquire does not accept keyword arguments. The signature in documentation should be formatted as in thread.lock.acquire. ---------- assignee: docs@python components: Documentation messages: 124861 nosy: Jyrki.Pulliainen, docs@python priority: normal severity: normal status: open title: Lock.acquire documentation is misleading versions: Python 2.7, Python 3.1 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10789> _______________________________________

6 9

[issue10048] urllib.request documentation confusing
by Antoine Pitrou 27 Apr '19

27 Apr '19

New submission from Antoine Pitrou <pitrou(a)free.fr>: The urllib.request documentation intermingles old 2.x urllib (FancyURLopener, etc.) with urllib2-inherited (*Handler, build_opener, etc.) primitives without making any distinction. This makes it rather confusing for the reader to figure out which ones to use. Ideally, the use of the old primitives should also be discouraged. ---------- assignee: docs@python components: Documentation messages: 118179 nosy: docs@python, orsenthil, pitrou priority: normal severity: normal stage: needs patch status: open title: urllib.request documentation confusing versions: Python 3.1, Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10048> _______________________________________

4 5

[issue11776] types.MethodType() params and usage is not documented
by anatoly techtonik 25 Feb '19

25 Feb '19

New submission from anatoly techtonik <techtonik(a)gmail.com>: types.MethodType(function, instance) is used as a replacement for new.instancemethod(function, instance, class), but this usage is not documented. ---------- assignee: docs@python components: Documentation messages: 133089 nosy: docs@python, techtonik priority: normal severity: normal status: open title: types.MethodType() params and usage is not documented versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11776> _______________________________________

13 31