[issue23984] Documentation error: Descriptors
New submission from bjonnh: in https://docs.python.org/3.5/howto/descriptor.html#static-methods-and-class-m... (same problem in all python 3.x documentations) There is this example where the return of f function is printed and there is already a print in the function: """
class E(object): def f(x): print(x) f = staticmethod(f)
print(E.f(3)) 3 print(E().f(3)) 3 """
It should probably be: """ def f(x): return(x) """ or """
E.f(3) 3 E().f(3) """
---------- assignee: docs@python components: Documentation messages: 241312 nosy: bjonnh, docs@python priority: normal severity: normal status: open title: Documentation error: Descriptors type: enhancement versions: Python 3.2, Python 3.3, Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23984> _______________________________________
Changes by Ned Deily <nad@acm.org>: ---------- nosy: +rhettinger versions: +Python 2.7 -Python 3.2, Python 3.3, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23984> _______________________________________
Changes by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- assignee: docs@python -> rhettinger _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23984> _______________________________________
Raymond Hettinger added the comment: In addition to being broken, the code is a crummy example that gives no hint of why one might want to use a staticmethod. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23984> _______________________________________
Changes by Roundup Robot <devnull@psf.upfronthosting.co.za>: ---------- pull_requests: +1189 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue23984> _______________________________________
Change by Carl Bordum Hansen <carl@bordum.dk>: ---------- keywords: +patch pull_requests: +12356 stage: -> patch review _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue23984> _______________________________________
Carl Bordum Hansen <carl@bordum.dk> added the comment: I submitted a PR that addresses this and the next example, which also uses print unnecessarily. To answer your last comment rhettinger; the preceding text tells you /why/ one might want to use a staticmethod: """ Good candidates for static methods are methods that do not reference the ``self`` variable. For instance, a statistics package may include a container class for experimental data. The class provides normal methods for computing the average, mean, median, and other descriptive statistics that depend on the data. However, there may be useful functions which are conceptually related but do not depend on the data. For instance, ``erf(x)`` is handy conversion routine that comes up in statistical work but does not directly depend on a particular dataset. It can be called either from an object or the class: ``s.erf(1.5) --> .9332`` or ``Sample.erf(1.5) --> .9332``. Since staticmethods return the underlying function with no changes, the example calls are unexciting:: """ ---------- nosy: +carlbordum versions: +Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue23984> _______________________________________
Cheryl Sabella <cheryl.sabella@gmail.com> added the comment: @carlbordum, thank you for the PR, but the original PR already addresses the issues. In a code review message on that PR (https://github.com/python/cpython/pull/1034#pullrequestreview-32006381), @rhettinger commented on the removal of the print statement in the method call, which was addressed by the creator of that PR. PR1034 was just waiting for final review and approval. The difference between this and the print in the classmethod example is that having to two prints in this example resulted in output of:
E.f(3) 3 print(E.f(3)) 3 None
whereas the classmethod example doesn't have the issue of printing `None`. I don't think the second PR is necessary. ---------- nosy: +cheryl.sabella versions: -Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue23984> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: FWIW, I'm in the middle of a major update to this howto add will address this example there. ---------- resolution: -> postponed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue23984> _______________________________________
miss-islington <mariatta.wijaya+miss-islington@gmail.com> added the comment: New changeset abbdd1fc5c2017683da8d2ed3e8843e8c159bc8c by Miss Islington (bot) (Shubham Aggarwal) in branch 'master': bpo-23984: Improve descriptor documentation (GH-1034) https://github.com/python/cpython/commit/abbdd1fc5c2017683da8d2ed3e8843e8c15... ---------- nosy: +miss-islington _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue23984> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +12412 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue23984> _______________________________________
Raymond Hettinger <raymond.hettinger@gmail.com> added the comment: New changeset cb2d71b28e5cac04bbd59b8b6dbec220c4da7beb by Raymond Hettinger (Miss Islington (bot)) in branch '3.7': bpo-23984: Improve descriptor documentation (GH-1034) (GH-12459) https://github.com/python/cpython/commit/cb2d71b28e5cac04bbd59b8b6dbec220c4d... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue23984> _______________________________________
Irit Katriel <iritkatriel@yahoo.com> added the comment: This seems complete, can it be closed? ---------- nosy: +iritkatriel _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue23984> _______________________________________
Change by Raymond Hettinger <raymond.hettinger@gmail.com>: ---------- stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue23984> _______________________________________
participants (8)
-
bjonnh -
Carl Bordum Hansen
-
Cheryl Sabella
-
Irit Katriel
-
miss-islington
-
Ned Deily
-
Raymond Hettinger
-
Roundup Robot