classification
Title: Subclasses of property lose docstring
Type: behavior Stage: resolved
Components: Interpreter Core Versions: Python 3.6
process
Status: closed Resolution: duplicate
Dependencies: Superseder: Subclass of property doesn't preserve instance __doc__ when using doc= argument
View: 24766
Assigned To: Nosy List: abarry, berker.peksag, python-dev, rhettinger, torsten
Priority: normal Keywords: patch

Created on 2015-11-27 23:43 by torsten, last changed 2016-05-02 12:37 by berker.peksag. This issue is now closed.

Files
File name Uploaded Description Edit
subprop_doc.diff torsten, 2015-11-27 23:45 review
subprop_doc_r2.diff torsten, 2015-11-28 09:20 Updated patch (just added a link to this issue) review
fix_repetitions.diff torsten, 2015-11-28 09:42 Fix for running test_property with repetitions review
Messages (11)
msg255511 - (view) Author: Torsten Landschoff (torsten) * Date: 2015-11-27 23:43
I actually found this in Python2, but it is still unchanged in Python 3.6 dev. Namely, creating an instance of a class derived from property will drop the docstring passed explicitly to the constructor: 

torsten@defiant:~$ python3.6
Python 3.6.0a0 (default:9fcfdb53e8af, Nov 27 2015, 23:11:09) 
[GCC 4.8.4] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> property(doc="Hello world").__doc__
'Hello world'
>>> class SubProp(property): pass
... 
>>> SubProp(doc="Hello world").__doc__
>>>

This war surprising to me. I actually used a subclass of property to describe fields of configuration classes with extensive documentation, which disappeared during runtime.

In Python2 I work around this by assigning to __doc__ as the last thing in the constructor of my SubProp class.
msg255512 - (view) Author: Torsten Landschoff (torsten) * Date: 2015-11-27 23:45
Here is a proposed patch to correct this including regression tests.
msg255513 - (view) Author: Torsten Landschoff (torsten) * Date: 2015-11-27 23:47
Just a note about the patch: I changed the behaviour a bit in that the code does not ignore random exceptions while getting getter.__doc__.

I think that would be surprising for most users and it also does not match the application of the doc field to the subclass, where exceptions are propagated.
msg255517 - (view) Author: Anilyka Barry (abarry) * (Python triager) Date: 2015-11-28 01:30
Pointed out a refleak and a small nit.
msg255533 - (view) Author: Torsten Landschoff (torsten) * Date: 2015-11-28 09:42
Prompted by Emanuel's comment I ran the test with repetitions. This does not actually test his assertion that I missed a decref since he referred to the error case when setting the __doc__ key of the instance dict fails. But I was curious none the less.

I was shocked that this failed with

```
torsten@defiant:~/mirror/cpython$ make test TESTOPTS="-R 3:2 test_property"
...
test test_property failed -- Traceback (most recent call last):
  File "/home/torsten/mirror/cpython/Lib/test/test_property.py", line 172, in test_property_decorator_doc_writable
    self.assertEqual(sub.__class__.spam.__doc__, 'Eggs')
AssertionError: 'Spam' != 'Eggs'
```

But this was not introduced by my changes, rather it is an existing bug in the tests: test_property_decorator_doc_writable modifies a class created on module level so the second repetition sees the already updated class.

fix_repetitions.diff contains a fix for this problem (by defining the class locally in the test method).

While at it I introduced a refleak on purpose and this is correctly reported by the tests. Good to know how to test for this :-)
msg255538 - (view) Author: Anilyka Barry (abarry) * (Python triager) Date: 2015-11-28 12:20
Looking at it again, it appears you didn't have to decref it; my bad.

Both patches LGTM.
msg256237 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-12-11 21:48
New changeset cc1aa0e88626 by Berker Peksag in branch '3.5':
Issue #25755: Move PropertyWritableDoc into the test case
https://hg.python.org/cpython/rev/cc1aa0e88626

New changeset 8f52c9d72d9f by Berker Peksag in branch 'default':
Issue #25755: Move PropertyWritableDoc into the test case
https://hg.python.org/cpython/rev/8f52c9d72d9f
msg256240 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2015-12-11 21:52
Thanks for fix_repetitions.diff, Torsten. The test_property failure was discussed in issue 25755.
msg256246 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2015-12-11 23:32
Can this be closed now or is there work left to be done?
msg256247 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2015-12-11 23:39
fix_repetitions.diff was unrelated to this issue so subprop_doc_r2.diff still needs to be reviewed.
msg264641 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2016-05-02 12:37
Thanks for the patch, Torsten. This is a duplicate of issue 24766. Your patch is almost identical (except the behavior change) to the patch in issue 24766. I will adapt your test and attribute your name in commit message.
History
Date User Action Args
2016-05-02 12:37:30berker.peksagsetstatus: open -> closed
superseder: Subclass of property doesn't preserve instance __doc__ when using doc= argument
messages: + msg264641

resolution: duplicate
stage: patch review -> resolved
2015-12-11 23:39:00berker.peksagsetmessages: + msg256247
2015-12-11 23:32:08rhettingersetnosy: + rhettinger
messages: + msg256246
2015-12-11 21:52:25berker.peksagsetnosy: + berker.peksag
messages: + msg256240
2015-12-11 21:48:46python-devsetnosy: + python-dev
messages: + msg256237
2015-11-28 12:20:34abarrysetmessages: + msg255538
2015-11-28 09:42:34torstensetfiles: + fix_repetitions.diff

messages: + msg255533
2015-11-28 09:20:27torstensetfiles: + subprop_doc_r2.diff
2015-11-28 01:30:45abarrysetnosy: + abarry

messages: + msg255517
stage: patch review
2015-11-27 23:47:37torstensetmessages: + msg255513
2015-11-27 23:45:24torstensetfiles: + subprop_doc.diff
keywords: + patch
messages: + msg255512
2015-11-27 23:43:52torstencreate