classification
Title: Documentation error: Descriptors
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7, Python 2.7
process
Status: closed Resolution: postponed
Dependencies: Superseder:
Assigned To: rhettinger Nosy List: bjonnh, carlbordum, cheryl.sabella, docs@python, iritkatriel, miss-islington, rhettinger
Priority: normal Keywords: patch

Created on 2015-04-17 04:42 by bjonnh, last changed 2020-10-08 23:53 by rhettinger. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 1034 merged python-dev, 2017-04-07 18:38
PR 12401 closed carlbordum, 2019-03-18 10:38
PR 12459 merged miss-islington, 2019-03-20 02:56
Messages (8)
msg241312 - (view) Author: bjonnh (bjonnh) Date: 2015-04-17 04:42
in
https://docs.python.org/3.5/howto/descriptor.html#static-methods-and-class-methods

(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)
"""
msg241458 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2015-04-18 20:45
In addition to being broken, the code is a crummy example that gives no hint of why one might want to use a staticmethod.
msg338193 - (view) Author: Carl Bordum Hansen (carlbordum) * Date: 2019-03-18 10:38
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::
"""
msg338210 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2019-03-18 12:23
@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.
msg338260 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-03-18 16:58
FWIW, I'm in the middle of a major update to this howto add will address this example there.
msg338438 - (view) Author: miss-islington (miss-islington) Date: 2019-03-20 02:56
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/abbdd1fc5c2017683da8d2ed3e8843e8c159bc8c
msg338589 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2019-03-22 08:04
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/cb2d71b28e5cac04bbd59b8b6dbec220c4da7beb
msg378279 - (view) Author: Irit Katriel (iritkatriel) * (Python triager) Date: 2020-10-08 19:18
This seems complete, can it be closed?
History
Date User Action Args
2020-10-08 23:53:03rhettingersetstatus: open -> closed
stage: patch review -> resolved
2020-10-08 19:18:18iritkatrielsetnosy: + iritkatriel
messages: + msg378279
2019-03-22 08:04:26rhettingersetmessages: + msg338589
2019-03-20 02:56:51miss-islingtonsetpull_requests: + pull_request12412
2019-03-20 02:56:08miss-islingtonsetnosy: + miss-islington
messages: + msg338438
2019-03-18 16:58:20rhettingersetresolution: postponed
messages: + msg338260
2019-03-18 12:23:34cheryl.sabellasetnosy: + cheryl.sabella

messages: + msg338210
versions: - Python 3.4, Python 3.5, Python 3.6
2019-03-18 10:38:58carlbordumsetnosy: + carlbordum

messages: + msg338193
versions: + Python 3.6, Python 3.7, Python 3.8
2019-03-18 10:38:18carlbordumsetkeywords: + patch
stage: patch review
pull_requests: + pull_request12356
2017-04-07 18:38:07python-devsetpull_requests: + pull_request1189
2015-04-18 20:45:48rhettingersetmessages: + msg241458
2015-04-18 17:00:33rhettingersetassignee: docs@python -> rhettinger
2015-04-17 04:52:48ned.deilysetnosy: + rhettinger

versions: + Python 2.7, - Python 3.2, Python 3.3, Python 3.6
2015-04-17 04:42:07bjonnhcreate