Mailman 3 October 2015 - docs

Wrong function calls and referring to not removed concepts in descriptor HowTo (documentation) (issue 25435)
by vadmium+py＠gmail.com 19 Oct '15

19 Oct '15

http://bugs.python.org/review/25435/diff/15789/Doc/howto/descriptor.rst File Doc/howto/descriptor.rst (right): http://bugs.python.org/review/25435/diff/15789/Doc/howto/descriptor.rst#new… Doc/howto/descriptor.rst:283: self.f = f I reckon leave this bit out. It is meant to represent the actual function class, not a wrapper. http://bugs.python.org/review/25435/diff/15789/Doc/howto/descriptor.rst#new… Doc/howto/descriptor.rst:287: if obj is Null: None not Null http://bugs.python.org/review/25435/diff/15789/Doc/howto/descriptor.rst#new… Doc/howto/descriptor.rst:289: return self.f return self http://bugs.python.org/review/25435/diff/15789/Doc/howto/descriptor.rst#new… Doc/howto/descriptor.rst:292: return types.MethodType(self.f, obj) MethodType(self, obj) http://bugs.python.org/review/25435/diff/15789/Doc/howto/descriptor.rst#new… Doc/howto/descriptor.rst:303: >>> D.f # Get from a class becomes a function as well Get from a class returns the same function http://bugs.python.org/review/25435/diff/15789/Doc/howto/descriptor.rst#new… Doc/howto/descriptor.rst:308: The output suggests that bound and unbound methods are two different types. This whole paragraph could be removed IMO. In Python 3, “self” is not allowed to be None, and unbound methods are the original function object. http://bugs.python.org/review/25435/diff/15789/Doc/howto/descriptor.rst#new… Doc/howto/descriptor.rst:315: field. If set (meaning bound), the original function (stored in the The only Python 3 relevant bit is the second sentence I think. The rest could be dropped. http://bugs.python.org/review/25435/diff/15789/Doc/howto/descriptor.rst#new… Doc/howto/descriptor.rst:318: function. The actual C implementation of :func:`instancemethod_call()` is only instancemethod_call seems to be a method of PyInstanceMethod_Type, which is part of the C API, but doesn’t seem to be used at all. Don’t think it is worth mentioning. http://bugs.python.org/review/25435/

1 0

[issue25434] Fix typo in whatsnew/3.5
by Louis Sautier 18 Oct '15

18 Oct '15

New submission from Louis Sautier: Hi, I noticed a typo in the doc for What’s New In Python 3.5, here's a patch. ---------- assignee: docs@python components: Documentation files: fixtypo.patch keywords: patch messages: 253155 nosy: docs@python, omelette priority: normal severity: normal status: open title: Fix typo in whatsnew/3.5 versions: Python 3.5 Added file: http://bugs.python.org/file40811/fixtypo.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25434> _______________________________________

4 4

[issue25415] I can create instances of io.IOBase
by Terry J. Reedy 17 Oct '15

17 Oct '15

Terry J. Reedy added the comment: Martin, I agree with changing the doc. Gerrit misunderstood because 'no public constructors' is either meaningless or wrong. We do not usually talk about public versus private constructors. This sounds more like C++ than Python. For Python namespaces, names that start with '_' are private by convention unless documented otherwise. Special names (__x__) are private in the sense that they are not usually used except by methods of the class; special methods are usually accessed by syntax or public names. For class C, the default constructor is C.__new__, accessed by calling C. (Let us not worry about other methods here.) If C is a public name, with no '_', as is 'IOBase', then to me it has/is a public constructor. Like other classes, IOBase has .__new__ and calling it produces an instance, as Gerrit discovered. In that sense, it is not truly abstract. I believe 'has no public constructor' is intended to mean 'has no documented signature and should not be *directly* called." (If subclasses do call the base, then the signature should be documented.) ---------- nosy: +terry.reedy _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25415> _______________________________________

1 0

[issue25418] Minor markup issue in reference/datamodel docs
by TAKASE Arihiro 16 Oct '15

16 Oct '15

New submission from TAKASE Arihiro: https://docs.python.org/3/reference/datamodel.html#object.__hash__ The closing parenthesis of "isinstance(obj, collections.Hashable)" is outside the markup. The attached patch fixes it. ---------- assignee: docs@python components: Documentation files: datamodel.patch keywords: patch messages: 253068 nosy: artakase, docs@python priority: normal severity: normal status: open title: Minor markup issue in reference/datamodel docs type: behavior versions: Python 3.4, Python 3.5, Python 3.6 Added file: http://bugs.python.org/file40792/datamodel.patch _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25418> _______________________________________

3 2

[issue25415] I can create instances of io.IOBase
by Gerrit Holl 15 Oct '15

15 Oct '15

Gerrit Holl added the comment: When the documentation says there is no public constructor, I expected it would be impossible to create instances, as in: TypeError: cannot create 'builtin_function_or_method' instances Perhaps I misunderstand the documentation. ---------- _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25415> _______________________________________

1 0

[issue25415] I can create instances of io.IOBase
by Martin Panter 15 Oct '15

15 Oct '15

Martin Panter added the comment: “No public constructor” to me means that it is not defined how or if you can construct instances other than by the public subclasses. What do you expect to happen? How do you expect the public subclasses such as FileIO and BufferedReader to work if the base constructor does not work? The other three base classes (RawIOBase, BufferedIOBase, TextIOBase) also say “there is no public constructor”. However allowing custom subclasses of these is very useful, so I would actually be for removing these restrictions from the documentation, and instead saying that each constructor accepts no arguments. ---------- assignee: -> docs@python components: +Documentation, IO -Library (Lib) nosy: +docs@python, martin.panter _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25415> _______________________________________

1 0

[issue8952] Doc/c-api/arg.rst: fix documentation of number formats
by STINNER Victor 14 Oct '15

14 Oct '15

New submission from STINNER Victor <victor.stinner(a)haypocalc.com>: The documentation of PyArg_Parse*() number formats specify that only int / float / complex are accepted, whereas any int / float / complex compatible object is accepted. "compatible" means that it has an __int__() / __float__() / __complex__() method, or nb_int / nb_float of Py_TYPE(obj)->tp_as_number->nb_int is defined (tp_as_number has no nb_complex). I suppose that the following paragraph is also outdated: "It is possible to pass "long" integers (integers whose value exceeds the platform's :const:`LONG_MAX`) however no proper range checking is done --- the most significant bits are silently truncated when the receiving field is too small to receive the value (actually, the semantics are inherited from downcasts in C --- your mileage may vary)." Moreover, "without overflow checking" should be explained (Mark told me that the number is truncated to a power of 2). ---------- assignee: docs@python components: Documentation, Interpreter Core messages: 107379 nosy: docs@python, haypo, mark.dickinson priority: normal severity: normal status: open title: Doc/c-api/arg.rst: fix documentation of number formats versions: Python 3.2 _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue8952> _______________________________________

3 6

Possible exceptions not clearly detailed in Python 2.7.10 documentation
by Wood, Connor 12 Oct '15

12 Oct '15

Hi, Today, I had difficulty outfitting my code with error detection and handling, owing primarily to the fact that, in the documentation, there is little indication of what the possible errors, and sub-error codes, can be thrown with each function. In many circumstances, I had to resort to various tidbits of knowledge around the Web. I appreciate that, in many cases, the errors thrown are common sense (file doesn't exist, directory is read only, etc.), however there are a lot of cases where this is not immediately clear, and there is no clear place wherein the common errors are clearly detailed. I do not know the state of more recent versions of the documentation, as I was solely working with the 2.7.10 version. That said, fixes with Python 3+ docs aren't as useful to myself and many others, as I am using version 2.7, and am unable to switch. Many thanks, Connor Wood Software Engineering Intern Rolls-Royce Controls and Data Services Limited York Road Hall Green Birmingham B28 8LN This e-mail and any attachments may contain confidential or privileged information. If you are not the intended recipient or have received this e-mail in error, please notify the sender immediately by reply of e-mail and destroy all paper and electronic copies of the message. If assistance is required please contact it.security(a)controlsdata.com. Please note distribution, disclosure of content or copying of this e-mail is prohibited. Rolls-Royce Controls and Data Services Limited may intercept or monitor email traffic, data and also the content of email for operational reasons or for lawful business practices. Registered office at Moor Lane, PO Box 31, Derby, DE24 8BJ. Company number 6686268. Registered in England.

2 1

Learning Python
by Ahmad Shrif 11 Oct '15

11 Oct '15

Hi Python I would like to learn programming and I was advised to start with Python. I started with your documentation but I find it difficult to grasp the information since I am non programmer and most of your documentation are for high level programmers. Kindly, please advise the best documentation to start with as non programmer. Your prompt reply is highly appreciated. Regards, Ahmad Shrif

2 1

[issue25374] Deficiencies in type hint usage in Python standard libraries
by John Michael Lafayette 11 Oct '15

11 Oct '15

New submission from John Michael Lafayette: I love the new type hint feature in Jetbrains IDE (PEP 0484). Now when my user defined methods return a value, I can press (Crtl+space) and see the type of that value and all its methods. Also, when I pass the wrong type in, I get a warning. Oddly, this does not happen with Python standard library functions. I can't get the auto-complete on objects returned by the Python standard library. The Python standard library doesn't warn me in advance if I put the wrong type in a method. How does that make sense? Please support PEP 0484 by using it in the Python standard library where appropriate. ---------- assignee: docs@python components: Documentation messages: 252758 nosy: John Michael Lafayette, docs@python priority: normal severity: normal status: open title: Deficiencies in type hint usage in Python standard libraries type: behavior _______________________________________ Python tracker <report(a)bugs.python.org> <http://bugs.python.org/issue25374> _______________________________________

2 1