This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Subclass of property doesn't preserve instance __doc__ when using doc= argument
Type: behavior Stage: patch review
Components: Interpreter Core Versions: Python 3.11
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: berker.peksag, erik.bray, ethan.furman, iritkatriel, r.david.murray, torsten
Priority: normal Keywords: patch

Created on 2015-07-31 17:02 by erik.bray, last changed 2022-04-11 14:58 by admin.

Files
File name Uploaded Description Edit
property-doc.patch erik.bray, 2015-07-31 17:02 Initial proposed patch review
property-doc-test.patch erik.bray, 2015-08-14 19:27 review
property-doc-test2.patch erik.bray, 2015-09-18 14:27 review
issue24766.diff berker.peksag, 2016-05-02 12:39 review
Pull Requests
URL Status Linked Edit
PR 2487 open erik.bray, 2017-06-29 08:46
Messages (12)
msg247756 - (view) Author: Erik Bray (erik.bray) * (Python triager) Date: 2015-07-31 17:02
This issue is directly related to http://bugs.python.org/issue5890, the solution to which I think was incomplete.

The examples below use a trivial subclass of property (but apply as well to a less trivial one):

>>> class myproperty(property): pass
...

When using myproperty with the decorator syntax, or simply without specifying a doc= argument, the docstring is properly inherited from the getter, as was fixed by issue5890:

>>> class A:
...     @myproperty
...     def foo(self):
...         """The foo."""
...         return 1
... 
>>> A.foo.__doc__
'The foo.'

However, when using the doc= argument, this behavior is broken:

>>> class B:
...     def _get_foo(self): return 1
...     foo = myproperty(_get_foo, doc="The foo.")
... 
>>> B.foo.__doc__
>>> B.foo.__doc__ is None
True


The attached patch resolves the issue by applying the special case for subclasses more generally.  If this looks good I'll add a test as well.

One thing I went back and forth on in the "if (Py_TYPE(self) != &PyProperty_Type)" block was whether or not to then deref prop->prop_doc and set it to NULL, since I don't think it's needed anymore at this point.  But I decided it was ultimately harmless to leave it.
msg247758 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2015-07-31 17:24
Looks good so far.  Let's get some tests in place.
msg248604 - (view) Author: Erik Bray (erik.bray) * (Python triager) Date: 2015-08-14 19:27
Sorry for the hold up.  Attached is another diff providing a test.  I think this is all that's really needed (since this is just a special case of the issue already tested for in this particular test class.
msg248606 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2015-08-14 19:32
Larry, can we get this into 3.5?  I'll create a pull-request in a couple days.
msg250937 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2015-09-18 05:46
ethan@code:~/source/python/issue25147$ ./python -m test.regrtest -R3:3 test_property
[1/1] test_property

Eggs  # from print() inside test

beginning 6 repetitions
123456

Spam  # the new value from the previous run seems stuck

test test_property failed -- Traceback (most recent call last):
  File "/home/ethan/source/python/issue25147/Lib/test/test_property.py", line 175, in test_property_decorator_doc_writable
    self.assertEqual(sub.__class__.spam.__doc__, 'Eggs')
AssertionError: 'Spam' != 'Eggs'
- Spam
+ Eggs


1 test failed:
    test_property
msg250990 - (view) Author: Erik Bray (erik.bray) * (Python triager) Date: 2015-09-18 14:08
Interesting--in fairness to myself, that test seems to fail without my patch too (without the -R it passes, but with -R3:3 it fails).  So it looks like a pre-existing issue.  But I'll see if I can do something about that while I'm at it.
msg250994 - (view) Author: Erik Bray (erik.bray) * (Python triager) Date: 2015-09-18 14:22
Actually, of course that test would fail when run repeatedly--it sets the property docstring from 'Eggs' to 'Spam' on the first run, but then doesn't set it back to its original value.  Since the PropertyWritableDocs class used in that test is module-level it doesn't get reset.

I'd just update that test to return the docstring to its original value if you want it to pass under such a condition.
msg250997 - (view) Author: Erik Bray (erik.bray) * (Python triager) Date: 2015-09-18 14:27
Attached an additional patch to test_property_decorator_doc_writable so that it can pass on repeated runs.
msg251006 - (view) Author: Ethan Furman (ethan.furman) * (Python committer) Date: 2015-09-18 15:31
Thanks for checking that out, Erik.  I was hoping it was a testing issue, but I ran out of time to verify.
msg264642 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-05-02 12:39
test_property_decorator_doc_writable fix has already been committed in cc1aa0e88626.

Here's an updated patch:

* Synced with the default branch
* Adapted the test from duplicate issue 25757 (written by Torsten Landschoff)
msg264646 - (view) Author: Erik Bray (erik.bray) * (Python triager) Date: 2016-05-02 12:57
Thanks for the updated patch. LGTM.
msg404608 - (view) Author: Irit Katriel (iritkatriel) * (Python committer) Date: 2021-10-21 15:30
Reproduced on 3.11.
History
Date User Action Args
2022-04-11 14:58:19adminsetgithub: 68954
2021-10-21 15:30:13iritkatrielsetnosy: + iritkatriel

messages: + msg404608
versions: + Python 3.11, - Python 3.5, Python 3.6
2017-06-29 08:46:16erik.braysetpull_requests: + pull_request2546
2016-05-02 12:57:26erik.braysetmessages: + msg264646
2016-05-02 12:39:26berker.peksagsetfiles: + issue24766.diff

nosy: + torsten, berker.peksag
messages: + msg264642

stage: test needed -> patch review
2016-05-02 12:37:30berker.peksaglinkissue25757 superseder
2015-09-18 15:31:22ethan.furmansetmessages: + msg251006
2015-09-18 14:27:11erik.braysetfiles: + property-doc-test2.patch

messages: + msg250997
2015-09-18 14:22:06erik.braysetmessages: + msg250994
2015-09-18 14:08:18erik.braysetmessages: + msg250990
2015-09-18 05:46:51ethan.furmansetmessages: + msg250937
2015-09-18 05:45:40ethan.furmansetnosy: - larry
2015-08-14 19:32:28ethan.furmansetnosy: + larry
messages: + msg248606
2015-08-14 19:27:00erik.braysetfiles: + property-doc-test.patch

messages: + msg248604
2015-08-01 14:13:35serhiy.storchakasetnosy: + r.david.murray
2015-07-31 17:24:01ethan.furmansettype: behavior
stage: test needed
messages: + msg247758
versions: + Python 3.5, Python 3.6
2015-07-31 17:22:03ethan.furmansetnosy: + ethan.furman
2015-07-31 17:02:03erik.braycreate