Mailman 3 October 2012 - docs

[issue11023] pep 227 missing text
by Alan Isaac 25 Jan '18

25 Jan '18

New submission from Alan Isaac <alan.isaac(a)gmail.com>: In PEP 227 missing text is marked with XXX. Most of this is just calls for examples and elaboration. However under the Implementation section XXX marks a substantive question about the documentation. Fixing this may be low priority, but a tracker search suggested it is currently not even being tracked ... ---------- assignee: docs@python components: Documentation messages: 127184 nosy: aisaac, docs@python priority: normal severity: normal status: open title: pep 227 missing text type: feature request _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11023> _______________________________________

4 3

[issue12706] timeout sentinel in ftplib and poplib
by Senthil Kumaran 24 Jan '18

24 Jan '18

New submission from Senthil Kumaran <senthil(a)uthcode.com>: - ftplib and poplib, has them as timeout=None, while they default to socket._GLOBAL_DEFAULT_TIMEOUT object. This is wrong; someone may pass None thinking it will trigger the default behaviour, and have nasty surprises. ---------- assignee: docs@python messages: 141740 nosy: docs@python, orsenthil priority: normal severity: normal stage: needs patch status: open title: timeout sentinel in ftplib and poplib type: behavior versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12706> _______________________________________

5 7

[issue15221] os.path.is*() may return False if path can't be accessed
by Giampaolo Rodola' 14 Jan '18

14 Jan '18

New submission from Giampaolo Rodola' <g.rodola(a)gmail.com>: It seems a doc fix is the best way to go, in which case I leave this one to a native English speaker: http://mail.python.org/pipermail/python-dev/2012-June/120788.html Alternatively a new 'strict' parameter has been proposed as a workaround: http://mail.python.org/pipermail/python-dev/2012-June/120800.html ---------- assignee: docs@python components: Documentation messages: 164307 nosy: christian.heimes, docs@python, eric.araujo, ezio.melotti, georg.brandl, giampaolo.rodola, ncoghlan priority: normal severity: normal status: open title: os.path.is*() may return False if path can't be accessed versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15221> _______________________________________

7 9

[issue11260] smtpd-as-a-script feature should be documented and should use argparse
by Xavier Morel 09 Jan '18

09 Jan '18

New submission from Xavier Morel <xavier.morel(a)masklinn.net>: argparse has been merged to the standard library in 3.2, and (tell me if I'm wrong) would therefore be the "best-practices" way to parse command-line arguments. Numerous stdlib modules can be used as scripts, but they tend to have ad-hoc documentation (if they are at all documented) and arguments parsing (using any of the 4 available methods in Python: straight from sys.argv, getopt, optparse and argparse). I picked smtpd as a first shot since it does something useful (SMTP proxy) and has a pretty good (if ad-hoc) command-line documentation. smtpd is currently using getopt for its options parsing and the argument parsing is very cleanly factored: the port only had to replace the implementation of the `parseargs` function (and add and remove some helpers). * The port keeps the existing arguments semantics (including the mandatory host:port syntax for the local and remote specs if overridden) * The port tries to maintain the old error messages, but due to the way argparse works (or the way I used it for the specs) the parity is not perfect when providing incorrect specs * The CLI help uses argparse's formatting, and the documentation for the local and remote specs was set on these arguments rather than as an epilog. The version string was also removed from the help screen * Because they are set by argparse's arguments validation, the status codes on incorrect arguments are slightly different: - running smtpd.py as a regular user without the `--nosetuid` flag still exits with status 1 - providing incorrect spec formats (missing or non-int port) or providing too many positional arguments (3 or more) now exits with status 2 (formerly 1) ---------- assignee: docs@python components: Documentation, Library (Lib) files: smtpd-to-argparse.diff keywords: patch messages: 128917 nosy: barry, docs@python, xmorel priority: normal severity: normal status: open title: smtpd-as-a-script feature should be documented and should use argparse versions: Python 3.3 Added file: http://bugs.python.org/file20812/smtpd-to-argparse.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11260> _______________________________________

8 18

[issue14124] _pickle.c comment/documentation improvement
by Merlijn van Deen 09 Nov '17

09 Nov '17

New submission from Merlijn van Deen <valhallasw(a)gmail.com>: As suggested by loewis in msg154233, I created some documentation to help people get started with _pickle.c. ---------- assignee: docs@python components: Documentation, Extension Modules files: _pickle_c_doc.diff keywords: patch messages: 154284 nosy: docs@python, valhallasw priority: normal severity: normal status: open title: _pickle.c comment/documentation improvement type: enhancement versions: Python 3.3 Added file: http://bugs.python.org/file24641/_pickle_c_doc.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14124> _______________________________________

3 4

[issue11253] autodocument first appearance of ctypes.wintypes constants
by anatoly techtonik 08 Nov '17

08 Nov '17

New submission from anatoly techtonik <techtonik(a)gmail.com>: I've just noticed that my application is incompatible with Python 2.5, because ctypes.wintypes is missing SHORT constants. However, I can't find the information when these symbols were introduced first. To prevent such confusion in future it would be nice to extract symbol information for each Python release and automatically include the version of the first appearance in documentation. ---------- assignee: docs@python components: Documentation messages: 128893 nosy: docs@python, techtonik priority: normal severity: normal status: open title: autodocument first appearance of ctypes.wintypes constants versions: Python 2.5, Python 2.6, Python 2.7, Python 3.1, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11253> _______________________________________

6 7

[issue15472] Itertools doc summary table misdocuments some arguments
by Éric Araujo 15 Sep '17

15 Sep '17

New submission from Éric Araujo <merwok(a)netwok.org>: In the tables near the top of http://docs.python.org/library/itertools , some functions like cycle have an example that uses “seq”, which is interpreted as “sequence” but the functions do work with any iterable. ---------- assignee: docs@python components: Documentation messages: 166594 nosy: docs@python, eric.araujo, rhettinger priority: normal severity: normal status: open title: Itertools doc summary table misdocuments some arguments versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15472> _______________________________________

4 7

[issue15427] Describe use of args parameter of argparse.ArgumentParser.parse_args
by Steven Bethard 09 Sep '17

09 Sep '17

New submission from Steven Bethard <steven.bethard(a)gmail.com>: >From http://bugs.python.org/issue14191#msg155202: ArgumentParser.parse_args(args=None, namespace=None) ... However, nowhere is the args= parameter explained. One example is given at the end of 15.4.4.6 showing the use of args= which apparently accepts a list of parameters, similar to the positional list of parameters that are used in all the other examples. It might be nice to clarify that. ---------- assignee: docs@python components: Documentation messages: 166174 nosy: bethard, docs@python priority: normal severity: normal status: open title: Describe use of args parameter of argparse.ArgumentParser.parse_args type: behavior versions: Python 2.7, Python 3.2, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue15427> _______________________________________

5 10

[issue12067] Doc: remove errors about mixed-type comparisons.
by Terry J. Reedy 24 Aug '17

24 Aug '17

New submission from Terry J. Reedy <tjreedy(a)udel.edu>: Current 3.2 doc, 5.9. Comparisons, has this paragraph about mixed-type comparisons. "The operators <, >, ==, >=, <=, and != compare the values of two objects. The objects need not have the same type. If both are numbers, they are converted to a common type. Otherwise, the == and != operators *always* consider objects of different types to be unequal, while the <, >, >= and <= operators raise a TypeError when comparing objects of different types that do not implement these operators for the given pair of types. You can control comparison behavior of objects of non-built-in types by defining rich comparison methods like __gt__(), described in section Basic customization." Sentence 3: "If both are numbers, they are converted to a common type." I suspect it would be more true to say 'common internal type' as I would not think it a language requirement to produce Python objects. In any case, I think it is only true for built-in number types, and I do not see that qualification anywhere previously. That aside, it does not appear to be true for Decimals and Fractions in 2.7.1. Sentence 4: first clause is only true for built-in types. That qualification is not obvious to everyone, as evidenced by a current python-list sub thread. For 2.7, which has a different continuation, I suggest adding 'built-in' before 'objects of'. For 3.2/3, I suggest deleting '*always*' and adding a comma after 'TypeError' so that the 'when' condition applies to equality comparisons also. After discussion about same-type comparisons, there is another paragraph about mixed-type comparison: "Comparison of objects of the differing types depends on whether either of the types provide explicit support for the comparison. Most numeric types can be compared with one another, but comparisons of float and Decimal are not supported to avoid the inevitable confusion arising from representation issues such as float('1.1') being inexactly represented and therefore not exactly equal to Decimal('1.1') which is. When cross-type comparison is not supported, the comparison method returns NotImplemented. This can create the illusion of non-transitivity between supported cross-type comparisons and unsupported comparisons. For example, Decimal(2) == 2 and 2 == float(2) but Decimal(2) != float(2)." I suggest deleting this entirely. The first sentence and first clause of the second repeat what was said above. The rest is obsolete as float/decimal comparisons *are* implemented in 2.7.1 and 3.2.0. ---------- assignee: docs@python components: Documentation keywords: easy messages: 135873 nosy: docs@python, rhettinger, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Doc: remove errors about mixed-type comparisons. versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12067> _______________________________________

15 71

[issue12887] Documenting all SO_* constants in socket module
by Sandro Tosi 22 Aug '17

22 Aug '17

New submission from Sandro Tosi <sandro.tosi(a)gmail.com>: spinning off msg142613 - it would be interesting to have in the socket module documentation also an explanation of all the several SO_ flags available; even a compact table could be ok; or even a link to a remote reference for them. ---------- assignee: docs@python components: Documentation messages: 143428 nosy: docs@python, eric.araujo, ezio.melotti, sandro.tosi priority: normal severity: normal stage: needs patch status: open title: Documenting all SO_* constants in socket module versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue12887> _______________________________________

5 5