Mailman 3 December 2015 - docs

[issue25756] asyncio WriteTransport documentation typo
by Марк Коренберг 02 Dec '15

02 Dec '15

New submission from Марк Коренберг: Here is the match against master. Doc/library/asyncio-protocol.rst: @@ -156,9 +156,9 @@ WriteTransport high-water limit is given, the low-water limit defaults to an implementation-specific value less than or equal to the high-water limit. Setting *high* to zero forces *low* to zero as - well, and causes :meth:`pause_writing` to be called whenever the + well, and causes :meth:`resume_writing` to be called whenever the buffer becomes non-empty. Setting *low* to zero causes - :meth:`resume_writing` to be called only once the buffer is empty. + :meth:`pause_writing` to be called only once the buffer is empty. Use of zero for either limit is generally sub-optimal as it reduces opportunities for doing I/O and computation concurrently. ---------- assignee: docs@python components: Documentation messages: 255508 nosy: docs@python, mmarkk priority: normal severity: normal status: open title: asyncio WriteTransport documentation typo type: enhancement versions: Python 3.2, Python 3.3, Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25756> _______________________________________

2 1

Re: [docs] Document that tp_setattro and tp_setattr are used for deleting attributes (issue 25701)
by vadmium+py＠gmail.com 02 Dec '15

02 Dec '15

http://bugs.python.org/review/25701/diff/16071/Doc/c-api/object.rst File Doc/c-api/object.rst (right): http://bugs.python.org/review/25701/diff/16071/Doc/c-api/object.rst#newcode… Doc/c-api/object.rst:71: object *o*. If *v* is *NULL*, delete the value (``del o.attr_name``), On 2015/12/01 16:50:59, storchaka wrote: > May be refer to PyObject_DelAttr if v is NULL? Good idea (if we decide not to deprecate this) http://bugs.python.org/review/25701/diff/16071/Doc/c-api/object.rst#newcode… Doc/c-api/object.rst:72: otherwise set it to *v* (``o.attr_name = v``). Raises an exception and On 2015/12/01 16:50:59, storchaka wrote: > It looks to me that "Return" and "Raise" are more preferable to "Returns" and > "Raises" in the documentation. Agreed. I was keeping the mood the same as the original, but now I see it would be better to agree with the first two sentences. http://bugs.python.org/review/25701/

1 0

[issue20503] super behaviour and abstract base classes (either implementation or documentation/error message is wrong)
by Martin Panter 02 Dec '15

02 Dec '15

Martin Panter added the comment: I am proposing some documentation changes in Issue 23674 which would address this. ---------- assignee: -> docs@python components: +Documentation -Interpreter Core dependencies: +super() documentation isn't very clear nosy: +docs@python, martin.panter versions: +Python 2.7, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue20503> _______________________________________

1 0

[issue25772] Misleading descriptions about built-in type `super.`
by Juchen Zeng 02 Dec '15

02 Dec '15

New submission from Juchen Zeng: A few days ago, I was learning built-in type `super` through [python official doc](https://docs.python.org/2/library/functions.html#super). And I was mislead by its documentation, in the part of how `__mro__` resolution works. Below is the part which confuse me: """ super(type[, object-or-type]) # ISSUE IRRELEVANT DOC OMITTED The __mro__ attribute of the type lists the method resolution search order used by both getattr() and super(). The attribute is dynamic and can change whenever the inheritance hierarchy is updated. """ >From the description of the doc we can see that `super()` takes two arguments, the first is `type` and the second is an optional `object-or-type`. So, when I saw the doc statement: `The __mro__ attribute of the type lists the method resolution search order used by both getattr() and super(). `, I naturally thought here the `type` refers to the compulsory first `type` argument. But after doing a series of [experiments][EXP_REF]. It turns out in `super()` was using the second `type`'s `__mro__` attribute! And if the second argument is an object, it will use `object.__class__.__mro__` as its resolution order. Unless a learner experimented it throughly like me, he will have lots of difficulty to figured out that `type` mentioned in the doc refers to the second optional argument. I think here the doc should be clearly specified that the second argument's `__mro__` is what super relies on. I suggest to add distinctions on arguments name or add more clarification informations in the doc here. By the way, the python3 document has the same issue. If you decided to fix this, maybe you want to fix its python3 version, too. [EXP_REF]: http://stackoverflow.com/questions/33890918/how-does-super-interacts-with-a… ---------- assignee: docs@python components: Documentation messages: 255643 nosy: Juchen Zeng, docs@python, eric.araujo, ezio.melotti, georg.brandl priority: normal severity: normal status: open title: Misleading descriptions about built-in type `super.` versions: Python 2.7 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25772> _______________________________________

4 4

Re: [docs] Document that tp_setattro and tp_setattr are used for deleting attributes (issue 25701)
by storchaka＠gmail.com 01 Dec '15

01 Dec '15

Reviewers: haypo, vadmium, http://bugs.python.org/review/25701/diff/16071/Doc/c-api/object.rst File Doc/c-api/object.rst (right): http://bugs.python.org/review/25701/diff/16071/Doc/c-api/object.rst#newcode… Doc/c-api/object.rst:71: object *o*. If *v* is *NULL*, delete the value (``del o.attr_name``), May be refer to PyObject_DelAttr if v is NULL? http://bugs.python.org/review/25701/diff/16071/Doc/c-api/object.rst#newcode… Doc/c-api/object.rst:72: otherwise set it to *v* (``o.attr_name = v``). Raises an exception and It looks to me that "Return" and "Raise" are more preferable to "Returns" and "Raises" in the documentation. Please review this at http://bugs.python.org/review/25701/ Affected files: Doc/c-api/object.rst Doc/c-api/sequence.rst Doc/c-api/typeobj.rst Include/abstract.h # HG changeset patch # Parent ebec1a98ab81d19245e4bde2da03ccb489b9eb5f Issue #25701: Document C API functions that both set and delete objects diff -r ebec1a98ab81 Doc/c-api/object.rst --- a/Doc/c-api/object.rst Mon Nov 23 16:44:30 2015 +0200 +++ b/Doc/c-api/object.rst Mon Nov 30 05:38:20 2015 +0000 @@ -67,26 +67,29 @@ .. c:function:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v) - Set the value of the attribute named *attr_name*, for object *o*, to the value - *v*. Returns ``-1`` on failure. This is the equivalent of the Python statement - ``o.attr_name = v``. + Set or delete the value of the attribute named *attr_name*, for + object *o*. If *v* is *NULL*, delete the value (``del o.attr_name``), + otherwise set it to *v* (``o.attr_name = v``). Raises an exception and + returns ``-1`` on failure; returns ``0`` on success. .. c:function:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v) - Set the value of the attribute named *attr_name*, for object *o*, to the value - *v*. Returns ``-1`` on failure. This is the equivalent of the Python statement - ``o.attr_name = v``. + Set or delete the value of the attribute named *attr_name*, for + object *o*. If *v* is *NULL*, delete the value (``del o.attr_name``), + otherwise set it to *v* (``o.attr_name = v``). Raises an exception and + returns ``-1`` on failure; returns ``0`` on success. .. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value) - Generic attribute setter function that is meant to be put into a type + Generic attribute setter and deleter function that is meant to be put into a type object's ``tp_setattro`` slot. It looks for a data descriptor in the dictionary of classes in the object's MRO, and if found it takes preference - over setting the attribute in the instance dictionary. Otherwise, the - attribute is set in the object's :attr:`~object.__dict__` (if present). - Otherwise, an :exc:`AttributeError` is raised and ``-1`` is returned. + over setting or deleting the attribute in the instance dictionary. Otherwise, the + attribute is set or deleted in the object's :attr:`~object.__dict__` (if present). + On success, ``0`` is returned, otherwise an :exc:`AttributeError` + is raised and ``-1`` is returned. .. c:function:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name) @@ -378,7 +381,8 @@ .. c:function:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v) - Map the object *key* to the value *v*. Returns ``-1`` on failure. This is the + Map the object *key* to the value *v*. Raises an exception and + returns ``-1`` on failure; returns ``0`` on success. This is the equivalent of the Python statement ``o[key] = v``. diff -r ebec1a98ab81 Doc/c-api/sequence.rst --- a/Doc/c-api/sequence.rst Mon Nov 23 16:44:30 2015 +0200 +++ b/Doc/c-api/sequence.rst Mon Nov 30 05:38:20 2015 +0000 @@ -62,8 +62,10 @@ .. c:function:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v) - Assign object *v* to the *i*\ th element of *o*. Returns ``-1`` on failure. This - is the equivalent of the Python statement ``o[i] = v``. This function *does + Assign object *v* to the *i*\ th element of *o*, or delete the + element if *v* is *NULL*. Raises an exception and returns ``-1`` on + failure; returns ``0`` on success. This is the equivalent of the + Python statements ``o[i] = v`` and ``del o[i]``. This function *does not* steal a reference to *v*. diff -r ebec1a98ab81 Doc/c-api/typeobj.rst --- a/Doc/c-api/typeobj.rst Mon Nov 23 16:44:30 2015 +0200 +++ b/Doc/c-api/typeobj.rst Mon Nov 30 05:38:20 2015 +0000 @@ -208,7 +208,7 @@ .. c:member:: setattrfunc PyTypeObject.tp_setattr - An optional pointer to the set-attribute-string function. + An optional pointer to the function for setting and deleting attributes. This field is deprecated. When it is defined, it should point to a function that acts the same as the :c:member:`~PyTypeObject.tp_setattro` function, but taking a C string @@ -351,7 +351,7 @@ .. c:member:: setattrofunc PyTypeObject.tp_setattro - An optional pointer to the set-attribute function. + An optional pointer to the function for setting and deleting attributes. The signature is the same as for :c:func:`PyObject_SetAttr`. It is usually convenient to set this field to :c:func:`PyObject_GenericSetAttr`, which @@ -724,7 +724,7 @@ typedef struct PyGetSetDef { char *name; /* attribute name */ getter get; /* C function to get the attribute */ - setter set; /* C function to set the attribute */ + setter set; /* C function to set or delete the attribute */ char *doc; /* optional doc string */ void *closure; /* optional additional data for getter and setter */ } PyGetSetDef; @@ -775,7 +775,8 @@ .. c:member:: descrsetfunc PyTypeObject.tp_descr_set - An optional pointer to a "descriptor set" function. + An optional pointer to a function for setting and deleting + a descriptor's value. The function signature is :: @@ -1171,9 +1172,11 @@ .. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript - This function is used by :c:func:`PyObject_SetItem` and has the same - signature. If this slot is *NULL*, the object does not support item - assignment. + This function is used by :c:func:`PyObject_SetItem` and + :c:func:`PyObject_DelItem`. It has the same signature as + :c:func:`PyObject_SetItem`, but *v* can also be set to *NULL* to delete + an item. If this slot is *NULL*, the object does not support item + assignment and deletion. .. _sequence-structs: @@ -1222,7 +1225,7 @@ This function is used by :c:func:`PySequence_SetItem` and has the same signature. This slot may be left to *NULL* if the object does not support - item assignment. + item assignment and deletion. .. c:member:: objobjproc PySequenceMethods.sq_contains diff -r ebec1a98ab81 Include/abstract.h --- a/Include/abstract.h Mon Nov 23 16:44:30 2015 +0200 +++ b/Include/abstract.h Mon Nov 30 05:38:20 2015 +0000 @@ -191,9 +191,10 @@ int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v); - Set the value of the attribute named attr_name, for object o, - to the value, v. Returns -1 on failure. This is - the equivalent of the Python statement: o.attr_name=v. + Set or delete the value of the attribute named attr_name, for object o. + If v is NULL, delete the value (del o.attr_name), otherwise set it to v + (o.attr_name=v). Raises an exception and returns -1 on failure; returns + 0 on success. */ @@ -201,9 +202,10 @@ int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v); - Set the value of the attribute named attr_name, for object o, - to the value, v. Returns -1 on failure. This is - the equivalent of the Python statement: o.attr_name=v. + Set or delete the value of the attribute named attr_name, for object o. + If v is NULL, delete the value (del o.attr_name), otherwise set it to v + (o.attr_name=v). Raises an exception and returns -1 on failure; returns + 0 on success. */ @@ -993,9 +995,10 @@ PyAPI_FUNC(int) PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v); /* - Assign object v to the ith element of o. Returns - -1 on failure. This is the equivalent of the Python - statement: o[i]=v. + Assign object v to the ith element of o, or delete the element if v is + NULL. Raises an exception and returns -1 on failure; returns 0 on + success. This is the equivalent of the Python statements: "o[i]=v" and + "del o[i]". */ PyAPI_FUNC(int) PySequence_DelItem(PyObject *o, Py_ssize_t i);

1 0

https://docs.python.org/3/library/os.html?highlight=os#module-os
by 吃錯藥的waox 01 Dec '15

01 Dec '15

Hi,I found confuse when I learn it os.rename(src, dst, *, src_dir_fd=None, dst_dir_fd=None) Rename the file or directory src to dst. If dst is a directory, OSError will be raised. but rename can deal with dir well(of course) my mother language is not english so maybe I just made a joke but can you explain the mean If dst is a directory, OSError will be raised. to me? THX!

1 0

[issue25767] asyncio documentation section 18.5.2.3.1. (Windows) links to French Wikipedia in English docs
by Elizabeth Myers 01 Dec '15

01 Dec '15

New submission from Elizabeth Myers: The link for HPET in the asyncio documentation (18.5.2.3.1 Windows, final paragraph, see https://docs.python.org/3/library/asyncio-eventloops.html#windows) links to https://fr.wikipedia.org/wiki/High_Precision_Event_Timer for the HPET link even though the document is in English (it should link to the English Wikipedia version instead). ---------- assignee: docs@python components: Documentation messages: 255598 nosy: Elizacat, docs@python priority: normal severity: normal status: open title: asyncio documentation section 18.5.2.3.1. (Windows) links to French Wikipedia in English docs type: enhancement versions: Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25767> _______________________________________

3 2