Mailman 3 June 2012 - docs

[issue11253] autodocument first appearance of ctypes.wintypes constants
by anatoly techtonik Nov. 8, 2017

Nov. 8, 2017

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

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

Aug. 24, 2017

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 Aug. 22, 2017

Aug. 22, 2017

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

[issue14345] Document socket.SOL_SOCKET
by anatoly techtonik Aug. 11, 2017

Aug. 11, 2017

New submission from anatoly techtonik <techtonik(a)gmail.com>: socket.get/setsockopt() docs can be improved by providing description for SOL_SOCKET constant, and link to source code for other level constants and socket level options. ---------- assignee: docs@python components: Documentation messages: 156140 nosy: docs@python, techtonik priority: normal severity: normal status: open title: Document socket.SOL_SOCKET _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue14345> _______________________________________

3 3

[issue11230] "Full unicode import system" not in 3.2
by John July 19, 2017

July 19, 2017

New submission from John <jh45dev(a)gmail.com>: A few months ago I read that in 3.2 it will be possible to import modules that are located on paths containing any unicode character. (more precisely, with chars not in the local code page) After an hour or two trying to get this to work in 3.2rc3, I went looking for clues, and found these 2 messages in which Victor Stinner says this feature is delayed until Python 3.3: http://bugs.python.org/issue3080#msg126514 http://bugs.python.org/issue10828#msg125787 Could you please make it clear in documentation and web pages, that this feature is not working yet. The Python 3.2 download page includes this: "countless fixes regarding bytes/string issues; among them full support for a bytes environment (filenames, environment variables)" and I guessed this must cover importing from any unicode path, as there was no mention that such importing had been abandoned for this version. -- jh ---------- assignee: docs@python components: Documentation messages: 128711 nosy: docs@python, jh45 priority: normal severity: normal status: open title: "Full unicode import system" not in 3.2 versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11230> _______________________________________

7 11

[issue10438] list an example for calling static methods from WITHIN classes
by Ian July 12, 2017

July 12, 2017

New submission from Ian <ifreecarve(a)gmail.com>: Concerning this section of the docs: http://docs.python.org/library/functions.html#staticmethod There is no example for calling a static method from another static method within the same class. As I discovered later, it's simple: C.f() -- from inside the class or outside it. A total newbie will accept this and move on... but in other programming languages, it's frowned upon to the class name from within the class. For example, in PHP you use the "self::" prefix and Java you don't need a prefix at all. So, even though I had it right the first time, it didn't SEEM right... so I went on a wild goose chase, for nothing. Googling "java call static method" will get you java documentation that lists both cases, as does "c++ call static method" and "php call static method". I feel that by adding "Note: you must also use the C.f() syntax when calling from within the class", the documentation will be more complete. ---------- assignee: docs@python components: Documentation messages: 121314 nosy: docs@python, ifreecarve priority: normal severity: normal status: open title: list an example for calling static methods from WITHIN classes type: feature request _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10438> _______________________________________

7 19

[issue11681] -b option undocumented
by Éric Araujo May 13, 2017

May 13, 2017

New submission from Éric Araujo <merwok(a)netwok.org>: Python 2 has a -b command-line option which is undocumented. It is used by the warnings machinery to decide to warn about (-b) or raise an error (-bb) if someone uses str(bytes) or str(buffer) (explanation courtesy of grep and Python/pythonrun.c). ---------- assignee: docs@python components: Documentation keywords: easy messages: 132195 nosy: docs@python, eric.araujo priority: normal severity: normal stage: needs patch status: open title: -b option undocumented versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11681> _______________________________________

11 22

[issue10938] Undocumented option for datetime.strftime: %s
by Humberto Diogenes Feb. 22, 2017

Feb. 22, 2017

New submission from Humberto Diogenes <humberto(a)digi.com.br>: On some systems, datetime.strftime() accepts a %s format string that returns epoch / UNIX timestamp, but this behavior is not documented at http://docs.python.org/library/datetime.html Python 2.7 (r27:82508, Jul 3 2010, 21:12:11) [GCC 4.0.1 (Apple Inc. build 5493)] on darwin Type "help", "copyright", "credits" or "license" for more information. >>> import datetime >>> datetime.datetime.now().strftime('%s') '1295376929' ---------- assignee: docs@python components: Documentation messages: 126481 nosy: docs@python, hdiogenes priority: normal severity: normal status: open title: Undocumented option for datetime.strftime: %s versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue10938> _______________________________________

7 9

[issue11924] Pickle and copyreg modules doesn't document the interface
by Jesús Cea Avión Feb. 18, 2017

Feb. 18, 2017

New submission from Jesús Cea Avión <jcea(a)jcea.es>: Python 3.2 here. "copyreg" module documentation says "See the pickle module for more details on the interface expected of function and constructor.", but I don't see any useful "copyreg" reference in pickle documentation. Some examples would be useful here, too. ---------- assignee: docs@python messages: 134416 nosy: docs@python, jcea priority: normal severity: normal status: open title: Pickle and copyreg modules doesn't document the interface versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11924> _______________________________________

5 6

[issue11173] Undocumented public APIs in Python 3.2
by Marc-Andre Lemburg Feb. 14, 2017

Feb. 14, 2017

New submission from Marc-Andre Lemburg <mal(a)egenix.com>: Mark Shannon on python-dev: The following API functions were removed from 3.1.3: PyAST_Compile PyCObject_AsVoidPtr PyCObject_FromVoidPtr PyCObject_FromVoidPtrAndDesc PyCObject_GetDesc PyCObject_Import PyCObject_SetVoidPtr PyCode_CheckLineNumber Py_CompileStringFlags PyEval_CallObject PyOS_ascii_atof PyOS_ascii_formatd PyOS_ascii_strtod PyThread_exit_prog PyThread__PyThread_exit_prog PyThread__PyThread_exit_thread PyUnicode_SetDefaultEncoding And the following were added to 3.2, of which only 2 are documented: PyArg_ValidateKeywordArguments PyAST_CompileEx Py_CompileString Py_CompileStringExFlags PyErr_NewExceptionWithDoc (documented) PyErr_SyntaxLocationEx PyErr_WarnFormat PyFrame_GetLineNumber PyImport_ExecCodeModuleWithPathnames PyImport_GetMagicTag PyLong_AsLongLongAndOverflow (documented) PyModule_GetFilenameObject Py_SetPath PyStructSequence_GetItem PyStructSequence_NewType PyStructSequence_SetItem PySys_AddWarnOptionUnicode PySys_AddXOption PySys_FormatStderr PySys_FormatStdout PySys_GetXOptions PyThread_acquire_lock_timed PyType_FromSpec PyUnicode_AsUnicodeCopy PyUnicode_AsWideCharString PyUnicode_EncodeFSDefault PyUnicode_FSDecoder Py_UNICODE_strcat Py_UNICODE_strncmp Py_UNICODE_strrchr PyUnicode_TransformDecimalToASCII For added confusion PySys_SetArgvEx is documented as new in 3.2, but exists in 3.1.3 Note that this only include functions. The API also includes a number of macros such as Py_False and Py_RETURN_FALSE, types , and data like PyBool_Type. ---------- assignee: docs@python components: Documentation messages: 128294 nosy: docs@python, lemburg priority: normal severity: normal status: open title: Undocumented public APIs in Python 3.2 versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue11173> _______________________________________

5 7