Mailman 3 March 2016 - docs

[issue26483] docs unclear on difference between str.isdigit() and str.isdecimal()
by Julien 12 Mar '16

12 Mar '16

Julien added the comment: To dig further, the DIGIT_MASK and DECIMAL_MASK used in `unicodeobject.c` are from `unicodectype.c` and they match values from `unicodetype_db.h` witch is generated by `Tools/unicode/makeunicodedata.py` which built those masks this way: # decimal digit, integer digit decimal = 0 if record[6]: flags |= DECIMAL_MASK decimal = int(record[6]) digit = 0 if record[7]: flags |= DIGIT_MASK digit = int(record[7]) if record[8]: flags |= NUMERIC_MASK numeric.setdefault(record[8], []).append(char) Those "record"s are documented in ftp://unicode.org/Public/3.2-Update/UnicodeData-3.2.0.html in which fields 6, 7, and 8 are: - 6 Decimal digit value N This is a numeric field. If the character has the decimal digit property, as specified in Chapter 4 of the Unicode Standard, the value of that digit is represented with an integer value in this field - 7 Digit value N This is a numeric field. If the character represents a digit, not necessarily a decimal digit, the value is here. This covers digits which do not form decimal radix forms, such as the compatibility superscript digits - 8 Numeric value N This is a numeric field. If the character has the numeric property, as specified in Chapter 4 of the Unicode Standard, the value of that character is represented with an integer or rational number in this field. This includes fractions as, e.g., "1/5" for U+2155 VULGAR FRACTION ONE FIFTH Also included are numerical values for compatibility characters such as circled numbers. Which is very close of the actual documentation. Yet the documentation is misleading using "This category includes digit characters" in the "isdecimal" documentation. Posssible rewriting: isdecimal: Return true if all characters in the string are decimal characters and there is at least one character, false otherwise. Decimal characters are those that can be used to form decimal-radix numbers, e.g. U+0660, ARABIC-INDIC DIGIT ZERO. Formally a decimal character is a character in the Unicode General Category "Nd". isdigit: Return true if all characters in the string are digits and there is at least one character, false otherwise. Digits include decimal characters and digits that need special handling, such as the compatibility superscript digits. This covers digits which do not form decimal radix forms. Formally, a digit is a character that has the property value Numeric_Type=Digit or Numeric_Type=Decimal. I don't think we can refactor more than this without rewriting documentation for isnumeric which mentions the Unicode standard the same way. ---------- nosy: +sizeof _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26483> _______________________________________

1 0

[issue26483] docs unclear on difference between str.isdigit() and str.isdecimal()
by Anna Koroliuk 12 Mar '16

12 Mar '16

Anna Koroliuk added the comment: Hi, all! At Helsinki Python sprint I with the kind help of Ezio found two things. 1) This code gives results which are attached in the file. I will just now show some interesting cases where isdigit() and isdecimal() give different results. for c in map(chr, range(0x10FFFF)): if unicodedata.digit(c, None) is not None: print(c, c.isdigit(), c.isdecimal()) ... 0 True True 1 True True 2 True True ² True False ³ True False ¹ True False ፩ True False ፪ True False ፫ True False ፬ True False ① True False ② True False ③ True False So it's different commands, although for usual digits 0-9 in usual typewriting without those upper indexes etc they give same results. Full file command_comparison.txt is attached. 2) Both commands isdigit() and isdecimal() are traced back that symbol is compared to a certain tables (masks), but masks are different. For isdigit() it is DIGIT_MASK = 0x04 and for isdecimal() is DECIMAL_MASK 0x02. Here is how all the commands are traced to the mask. A) isdecimal() ./Objects/unicodeobject.c: {"isdecimal", (PyCFunction) unicode_isdecimal, METH_NOARGS, isdecimal__doc__}, ./Objects/unicodeobject.c: static PyObject* unicode_isdecimal(PyObject *self) .... if (length == 1) return PyBool_FromLong( Py_UNICODE_ISDECIMAL(PyUnicode_READ(kind, data, 0))); ./Include/unicodeobject.h:#define Py_UNICODE_ISDECIMAL(ch) _PyUnicode_IsDecimalDigit(ch) ./Objects/unicodectype.c: int _PyUnicode_IsDecimalDigit(Py_UCS4 ch) { if (_PyUnicode_ToDecimalDigit(ch) < 0) return 0; return 1; } int _PyUnicode_ToDecimalDigit(Py_UCS4 ch) { const _PyUnicode_TypeRecord *ctype = gettyperecord(ch); return (ctype->flags & DECIMAL_MASK) ? ctype->decimal : -1; } ./Objects/unicodectype.c:#define DECIMAL_MASK 0x02 B) isdigit() ./Objects/unicodeobject.c: {"isdigit", (PyCFunction) unicode_isdigit, METH_NOARGS, isdigit__doc__}, ./Objects/unicodeobject.c: static PyObject* unicode_isdigit(PyObject *self) ... if (length == 1) { const Py_UCS4 ch = PyUnicode_READ(kind, data, 0); return PyBool_FromLong(Py_UNICODE_ISDIGIT(ch)); } ./Include/unicodeobject.h:#define Py_UNICODE_ISDIGIT(ch) _PyUnicode_IsDigit(ch) ./Objects/unicodectype.c: int _PyUnicode_IsDigit(Py_UCS4 ch) { if (_PyUnicode_ToDigit(ch) < 0) return 0; return 1; } int _PyUnicode_ToDigit(Py_UCS4 ch) { const _PyUnicode_TypeRecord *ctype = gettyperecord(ch); return (ctype->flags & DIGIT_MASK) ? ctype->digit : -1; } ./Tools/unicode/makeunicodedata.py:DIGIT_MASK = 0x04 BR, Anna ---------- nosy: +Anna Koroliuk Added file: http://bugs.python.org/file42149/command_comparison.txt _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26483> _______________________________________

1 0

[issue26250] no document for sqlite3.Cursor.connection
by Varpu Rantala 12 Mar '16

12 Mar '16

Varpu Rantala added the comment: The sentencing was complicated. I changed the formulation and added an example of connection. ---------- nosy: +Varpu Rantala Added file: http://bugs.python.org/file42146/issue26250.diff _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26250> _______________________________________

1 0

[issue13305] datetime.strftime("%Y") not consistent for years < 1000
by Roundup Robot 12 Mar '16

12 Mar '16

Roundup Robot added the comment: New changeset e54224e8d6a9 by Victor Stinner in branch 'default': Revert change 291d47954618 https://hg.python.org/cpython/rev/e54224e8d6a9 ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13305> _______________________________________

1 0

[issue13305] datetime.strftime("%Y") not consistent for years < 1000
by STINNER Victor 12 Mar '16

12 Mar '16

STINNER Victor added the comment: Elena's issue13305.diff: "Zero padding can be forced on some platforms by using e.g. ``%4Y``" Sorry, I still doesn't understand the change. %4Y doesn't work with strptime() and it only work with strftime() on very few platforms. Can you explain when %4Y should be used? strftime() and/or strptime()? Which platform? To me, it looks wrong to document %4Y since it almost never works... ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13305> _______________________________________

1 0

[issue13305] datetime.strftime("%Y") not consistent for years < 1000
by STINNER Victor 12 Mar '16

12 Mar '16

STINNER Victor added the comment: >> About Elena Oat's patch issue13305.diff: I'm not sure that >> strftime("%4Y") works on all platforms > It doesn't, that's what the patch is trying to document. Oh. I confirm: %4Y gives "4Y" for any year on FreeBSD and Mac OS X, it raises ValueError("Invalid format string") on Windows, etc. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13305> _______________________________________

1 0

[issue13305] datetime.strftime("%Y") not consistent for years < 1000
by Ezio Melotti 12 Mar '16

12 Mar '16

Ezio Melotti added the comment: > About Elena Oat's patch issue13305.diff: I'm not sure that > strftime("%4Y") works on all platforms It doesn't, that's what the patch is trying to document. AFAICT it works on my Linux (but not on yours), it gives '4Y' on Mac, and raises an error on Windows. This should depend on the libc used by system, so the same OS can give different results depending on which libc it uses, and the only sure thing is that %4Y is not a portable solution. FWIW the patch LGTM (except a couple minor nits -- zero-pad should be hyphenated and there should be a double space after the dot), but I'm not sure if it's better mentioning platforms at all or just being vague and say that it works on some platforms but not others and leave up to the user figuring out where. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13305> _______________________________________

1 0

[issue21910] File protocol should document if writelines must handle generators sensibly
by Jan Kanis 12 Mar '16

12 Mar '16

New submission from Jan Kanis: The resolution of issue 5445 should be documented somewhere properly, so people can depend on it or not. IOBase.writelines handles generator arguments without problems, i.e. without first draining the entire generator and then writing the result in one go. That would require large amounts of memory if the generator is large, and fail entirely if the generator is infinite. codecs.StreamWriter.writelines uses self.write(''.join(argument)) as implementation, which fails on very large or infinite arguments. According to issue 5445 it is not part of the file protocol that .writelines must handle (large/infinite) generators, only list-like iterables. However as far as I know this is not documented anywhere, and sometimes people assume that writelines is meant for this case. E.g. jinja (https://github.com/mitsuhiko/jinja2/blob/master/jinja2/environment.py#L1153, the dump method is explicitly documented to stream). The guarantees that .writelines makes or does not make in this regard should be documented somewhere, so that either .writeline implementations that don't handle large generators can be pointed out as bugs, or code that makes assumptions on .writeline handling large generators can be. I personally think .writelines should handle large generators, since in the python 3 world a lot of apis were iterator-ified and it is wat a lot of people would probably expect. But having a clear and documented decision on this is more important. (note: I've copied most of the nosy list from #5445) ---------- assignee: docs@python components: Documentation, IO messages: 222165 nosy: JanKanis, benjamin.peterson, dlesco, docs@python, hynek, lemburg, pitrou, stutzbach, terry.reedy priority: normal severity: normal status: open title: File protocol should document if writelines must handle generators sensibly versions: Python 2.7, Python 3.1, Python 3.2, Python 3.3, Python 3.4, Python 3.5 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue21910> _______________________________________

5 4

[issue26500] Document of star operator missing. It must be documented for better understanding.
by Jaivish Kothari 11 Mar '16

11 Mar '16

New submission from Jaivish Kothari: Star operator in python for unpacking could be documented for better understanding. ---------- assignee: docs@python components: Documentation messages: 261288 nosy: docs@python, janonymous priority: normal severity: normal status: open title: Document of star operator missing. It must be documented for better understanding. versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26500> _______________________________________

3 2

[issue13305] datetime.strftime("%Y") not consistent for years < 1000
by STINNER Victor 11 Mar '16

11 Mar '16

STINNER Victor added the comment: acucci's patch doc.patch suggests to use format "%4Y". Problem: I tried it on Linux, and it looks like it doesn't work. >>> datetime.datetime.strptime("1980", "%Y") datetime.datetime(1980, 1, 1, 0, 0) >>> datetime.datetime.strptime("1980", "%4Y") Traceback (most recent call last): ... ValueError: '4' is a bad directive in format '%4Y' Or maybe I misunderstood the doc change. Do you suggest to use %4Y format with strptime(), with strftime() or with both? ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue13305> _______________________________________

1 0