Mailman 3 August 2016 - docs

[issue23710] C API doc for PyObject_HEAD is outdated
by Tomi Pieviläinen Aug. 3, 2016

Aug. 3, 2016

New submission from Tomi Pieviläinen: https://docs.python.org/3/c-api/structures.html#c.PyObject_HEAD says that the macro should be used for creating new types and that it has ob_type. Unfortunately at some point (@61466 perhaps) that definition in object.h was changed. This affects other pages too (at least https://docs.python.org/3/extending/newtypes.html). I encountered this while checking if a C extension (imposm.parser) could be trivially ported for Python 3. Unfortunately not. I suppose self->ob_type should be replaced with Py_TYPE(self) but that isn't really clear from the docs. ---------- assignee: docs@python components: Documentation messages: 238530 nosy: docs@python, tpievila priority: normal severity: normal status: open title: C API doc for PyObject_HEAD is outdated _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue23710> _______________________________________

7 10

Re: [docs] UUID docs should say how to get "standard form" (issue 26267)
by berker.peksag＠gmail.com Aug. 3, 2016

Aug. 3, 2016

http://bugs.python.org/review/26267/diff/18046/Doc/library/uuid.rst File Doc/library/uuid.rst (right): http://bugs.python.org/review/26267/diff/18046/Doc/library/uuid.rst#newcode… Doc/library/uuid.rst:51: .. describe:: str(uuid) It would be better to be less verbose here. This can go after the "Exactly one of hex, bytes, bytes_le, fields [...]" paragraph in the uuid.UUID() documentation. http://bugs.python.org/review/26267/diff/18046/Doc/library/uuid.rst#newcode… Doc/library/uuid.rst:56: .. describe:: uuid1 == uuid2 Same as above. See datetime or decimal documentations for an example of how to document comparison operations. http://bugs.python.org/review/26267/

1 0

[issue26576] Tweak wording of decorator docos
by Chris Angelico Aug. 3, 2016

Aug. 3, 2016

New submission from Chris Angelico: The official documentation declares an unambiguous equivalence which is not true in some corner cases: @deco def f(x): pass is not quite the same as def f(x): pass f = deco(f) as the name is never bound to the undecorated function. This is what makes @property and @prop.setter work; otherwise, the undecorated setter function would overwrite the property, and the decoration would fail. Attached patch loosens the wording slightly to "broadly equivalent"; this permits corner cases to vary from the equivalence, while still retaining its simplicity for the 99% of cases where it's correct. (Think of explaining "yield from iter" as "for x in iter: yield x" and you have a similar near-equivalence.) Also, class decorators aren't required to return classes. Text removed saying that they do. ---------- assignee: docs@python components: Documentation files: deco-docos.patch keywords: patch messages: 261888 nosy: Rosuav, docs@python priority: normal severity: normal status: open title: Tweak wording of decorator docos Added file: http://bugs.python.org/file42181/deco-docos.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue26576> _______________________________________

6 12

Re: [docs] UUID docs should say how to get "standard form" (issue 26267)
by efmphone＠gmail.com Aug. 2, 2016

Aug. 2, 2016

Thanks for adding the comparison at 56:58, that's a significant thing to know. http://bugs.python.org/review/26267/

1 0

Re: [docs] UUID docs should say how to get "standard form" (issue 26267)
by efmphone＠gmail.com Aug. 2, 2016

Aug. 2, 2016

str() does not return the uuid within {}, line 53 should be changed to show that. http://bugs.python.org/review/26267/

1 0

Re: [docs] Clarify the use cases of NotImplemented in the docs (issue 27242)
by barry＠dadadata.net Aug. 2, 2016

Aug. 2, 2016

Reviewers: gvanrossum, stoneleaf, Jelle Zijlstra, SilentGhost, Message: A few typos and some nits. Mostly good otherwise. http://bugs.python.org/review/27242/diff/18040/Doc/library/constants.rst File Doc/library/constants.rst (right): http://bugs.python.org/review/27242/diff/18040/Doc/library/constants.rst#ne… Doc/library/constants.rst:50: even though they have similar purposes. See :exc:`NotImplementedError` Typo: Implented. Otherwise I'd use :exc:`NotImplementedError` on the above line instead of ``NotImplementedError`` Also s/similar purposes/similar names/ here too. http://bugs.python.org/review/27242/diff/18040/Doc/library/exceptions.rst File Doc/library/exceptions.rst (right): http://bugs.python.org/review/27242/diff/18040/Doc/library/exceptions.rst#n… Doc/library/exceptions.rst:244: even though they have similar purposes. See :data:`NotImplemented` for s/similar purposes/similar names/ IMO. I'd also use :data:`NotImplemented` instead of ``NotImplemented`` on the above line. Also, there's not really a need to reference NotImplementedError from within its own block; but if you do it, please also do this in NotImplemented. Typo: "Implented" on the above line. Please review this at http://bugs.python.org/review/27242/ Affected files: Doc/library/constants.rst Doc/library/exceptions.rst diff --git a/Doc/library/constants.rst b/Doc/library/constants.rst --- a/Doc/library/constants.rst +++ b/Doc/library/constants.rst @@ -26,30 +26,36 @@ A small number of constants live in the .. data:: NotImplemented Special value which should be returned by the binary special methods (e.g. :meth:`__eq__`, :meth:`__lt__`, :meth:`__add__`, :meth:`__rsub__`, etc.) to indicate that the operation is not implemented with respect to the other type; may be returned by the in-place binary special methods (e.g. :meth:`__imul__`, :meth:`__iand__`, etc.) for the same purpose. Its truth value is true. -.. note:: + .. note:: - When ``NotImplemented`` is returned, the interpreter will then try the - reflected operation on the other type, or some other fallback, depending - on the operator. If all attempted operations return ``NotImplemented``, the - interpreter will raise an appropriate exception. + When a binary (or in-place) method returns ``NotImplemented`` the + interpreter will try the reflected operation on the other type (or some + other fallback, depending on the operator). If all attempts return + ``NotImplemented``, the interpreter will raise an appropriate exception. + Incorrectly returning `NotImplemented` will result in a misleading + error message or the ``NotImplemented`` value being returned to Python code. - See - :ref:`implementing-the-arithmetic-operations` - for more details. + See :ref:`implementing-the-arithmetic-operations` for examples. + + .. note:: + + ``NotImplentedError`` and ``NotImplemented`` are not interchangeable, + even though they have similar purposes. See :exc:`NotImplementedError` + for details on when to use it. .. data:: Ellipsis The same as ``...``. Special value used mostly in conjunction with extended slicing syntax for user-defined container data types. .. data:: __debug__ diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst --- a/Doc/library/exceptions.rst +++ b/Doc/library/exceptions.rst @@ -221,23 +221,35 @@ The following exceptions are the excepti .. exception:: NameError Raised when a local or global name is not found. This applies only to unqualified names. The associated value is an error message that includes the name that could not be found. .. exception:: NotImplementedError This exception is derived from :exc:`RuntimeError`. In user defined base - classes, abstract methods should raise this exception when they require derived - classes to override the method. + classes, abstract methods should raise this exception when they require + derived classes to override the method, or while the class is being + developed to indicate that the real implementation still needs to be added. + .. note:: + + It should not be used to indicate that an operater or method is not + meant to be supported at all -- in that case either leave the operator / + method undefined or, if a subclass, set it to :data:`None`. + + .. note:: + + :exc:`NotImplentedError` and ``NotImplemented`` are not interchangeable, + even though they have similar purposes. See :data:`NotImplemented` for + details on when to use it. .. exception:: OSError([arg]) OSError(errno, strerror[, filename[, winerror[, filename2]]]) .. index:: module: errno This exception is raised when a system function returns a system-related error, including I/O failures such as "file not found" or "disk full" (not for illegal argument types or other incidental errors). @@ -429,20 +441,29 @@ The following exceptions are the excepti The exit status or error message that is passed to the constructor. (Defaults to ``None``.) .. exception:: TypeError Raised when an operation or function is applied to an object of inappropriate type. The associated value is a string giving details about the type mismatch. + This exception may be raised by user code to indicate that an attempted + operation on an object is not supported, and is not meant to. If an object + is meant to support a given operation but has not yet provided an + implementation, :exc:`NotImplementedError` is the proper exception to raise. + + Passing arguments of the wrong type (e.g. passing a :class:`list` when an + :class:`int` is expected) should result in a :exc:`TypeError`, but passing + arguments with the wrong value (e.g. a number outside expected boundaries) + should be a :exc:`ValueError`. .. exception:: UnboundLocalError Raised when a reference is made to a local variable in a function or method, but no value has been bound to that variable. This is a subclass of :exc:`NameError`. .. exception:: UnicodeError

1 0

locals dictionary in PyRun_String (issue 24637)
by stephane＠wirtel.be Aug. 2, 2016

Aug. 2, 2016

it's ok for me. http://bugs.python.org/review/24637/

1 0

Re: [docs] Clarify the use cases of NotImplemented in the docs (issue 27242)
by ghost.adh＠runbox.com Aug. 2, 2016

Aug. 2, 2016

https://bugs.python.org/review/27242/diff/17812/Doc/library/constants.rst File Doc/library/constants.rst (right): https://bugs.python.org/review/27242/diff/17812/Doc/library/constants.rst#n… Doc/library/constants.rst:38: When ``NotImplemented`` is returned, the interpreter will then try the Please, wrap everything to 80 columns. https://bugs.python.org/review/27242/diff/17812/Doc/library/constants.rst#n… Doc/library/constants.rst:44: :meth:`__lt__` or :meth:`__add__`. The appropriate way to signal that an Sentences should be separated by two spaces. Here and everywhere below. https://bugs.python.org/review/27242/diff/17812/Doc/library/constants.rst#n… Doc/library/constants.rst:47: calling the superclass' method with :func:`super`) or raising an exception superclass's https://bugs.python.org/review/27242/

1 0

Documentation Python 3.4.5
by man0fS0rr0w Aug. 2, 2016

Aug. 2, 2016

Hi. I'm trying to download the tar.bz2 files containing the documentation of Python 3.4.5. But I get a 404 on every links (html, txt...) I've checked for Python 3.5 and it works. French here: excuse me for spelling or grammar errors. Sent from [ProtonMail](https://protonmail.com), Swiss-based encrypted email.

1 0