[Python-checkins] cpython: Issue #24064: Property() docstrings are now writeable.
raymond.hettinger
python-checkins at python.org
Wed May 13 10:10:22 CEST 2015
https://hg.python.org/cpython/rev/1e8a768fa0a5
changeset: 96010:1e8a768fa0a5
user: Raymond Hettinger <python at rcn.com>
date: Wed May 13 01:09:59 2015 -0700
summary:
Issue #24064: Property() docstrings are now writeable.
(Patch by Berker Peksag.)
files:
Doc/library/collections.rst | 9 +++++++++
Doc/whatsnew/3.5.rst | 16 ++++++++++++++++
Lib/test/test_collections.py | 8 ++++++++
Lib/test/test_descr.py | 5 ++++-
Lib/test/test_property.py | 22 ++++++++++++++++++++++
Misc/NEWS | 3 +++
Objects/descrobject.c | 2 +-
7 files changed, 63 insertions(+), 2 deletions(-)
diff --git a/Doc/library/collections.rst b/Doc/library/collections.rst
--- a/Doc/library/collections.rst
+++ b/Doc/library/collections.rst
@@ -924,6 +924,15 @@
>>> Point3D = namedtuple('Point3D', Point._fields + ('z',))
+Docstrings can be customized by making direct assignments to the ``__doc__``
+fields:
+
+ >>> Book = namedtuple('Book', ['id', 'title', 'authors'])
+ >>> Book.__doc__ = 'Hardcover book in active collection'
+ >>> Book.id = '13-digit ISBN'
+ >>> Book.title = 'Title of first printing'
+ >>> Book.author = 'List of authors sorted by last name'
+
Default values can be implemented by using :meth:`_replace` to
customize a prototype instance:
diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst
--- a/Doc/whatsnew/3.5.rst
+++ b/Doc/whatsnew/3.5.rst
@@ -234,6 +234,10 @@
* New Kazakh :ref:`codec <standard-encodings>` ``kz1048``. (Contributed by
Serhiy Storchaka in :issue:`22682`.)
+* Property docstrings are now writable. This is especially useful for
+ :func:`collections.namedtuple` docstrings.
+ (Contributed by Berker Peksag in :issue:`24064`.)
+
* New Tajik :ref:`codec <standard-encodings>` ``koi8_t``. (Contributed by
Serhiy Storchaka in :issue:`22681`.)
@@ -283,6 +287,18 @@
the full chained traceback, just like the interactive interpreter.
(Contributed by Claudiu Popa in :issue:`17442`.)
+collections
+-----------
+
+* You can now update docstrings produced by :func:`collections.namedtuple`::
+
+ Point = namedtuple('Point', ['x', 'y'])
+ Point.__doc__ = 'ordered pair'
+ Point.x.__doc__ = 'abscissa'
+ Point.y.__doc__ = 'ordinate'
+
+ (Contributed by Berker Peksag in :issue:`24064`.)
+
compileall
----------
diff --git a/Lib/test/test_collections.py b/Lib/test/test_collections.py
--- a/Lib/test/test_collections.py
+++ b/Lib/test/test_collections.py
@@ -199,6 +199,14 @@
Point = namedtuple('Point', 'x y')
self.assertEqual(Point.__doc__, 'Point(x, y)')
+ @unittest.skipIf(sys.flags.optimize >= 2,
+ "Docstrings are omitted with -O2 and above")
+ def test_doc_writable(self):
+ Point = namedtuple('Point', 'x y')
+ self.assertEqual(Point.x.__doc__, 'Alias for field number 0')
+ Point.x.__doc__ = 'docstring for Point.x'
+ self.assertEqual(Point.x.__doc__, 'docstring for Point.x')
+
def test_name_fixer(self):
for spec, renamed in [
[('efg', 'g%hi'), ('efg', '_1')], # field with non-alpha char
diff --git a/Lib/test/test_descr.py b/Lib/test/test_descr.py
--- a/Lib/test/test_descr.py
+++ b/Lib/test/test_descr.py
@@ -2022,7 +2022,7 @@
self.assertIs(raw.fset, C.__dict__['setx'])
self.assertIs(raw.fdel, C.__dict__['delx'])
- for attr in "__doc__", "fget", "fset", "fdel":
+ for attr in "fget", "fset", "fdel":
try:
setattr(raw, attr, 42)
except AttributeError as msg:
@@ -2033,6 +2033,9 @@
self.fail("expected AttributeError from trying to set readonly %r "
"attr on a property" % attr)
+ raw.__doc__ = 42
+ self.assertEqual(raw.__doc__, 42)
+
class D(object):
__getitem__ = property(lambda s: 1/0)
diff --git a/Lib/test/test_property.py b/Lib/test/test_property.py
--- a/Lib/test/test_property.py
+++ b/Lib/test/test_property.py
@@ -76,6 +76,13 @@
"""new docstring"""
return 8
+class PropertyWritableDoc(object):
+
+ @property
+ def spam(self):
+ """Eggs"""
+ return "eggs"
+
class PropertyTests(unittest.TestCase):
def test_property_decorator_baseclass(self):
# see #1620
@@ -150,6 +157,21 @@
foo = property(foo)
C.foo.__isabstractmethod__
+ @unittest.skipIf(sys.flags.optimize >= 2,
+ "Docstrings are omitted with -O2 and above")
+ def test_property_builtin_doc_writable(self):
+ p = property(doc='basic')
+ self.assertEqual(p.__doc__, 'basic')
+ p.__doc__ = 'extended'
+ self.assertEqual(p.__doc__, 'extended')
+
+ @unittest.skipIf(sys.flags.optimize >= 2,
+ "Docstrings are omitted with -O2 and above")
+ def test_property_decorator_doc_writable(self):
+ sub = PropertyWritableDoc()
+ self.assertEqual(sub.__class__.spam.__doc__, 'Eggs')
+ sub.__class__.spam.__doc__ = 'Spam'
+ self.assertEqual(sub.__class__.spam.__doc__, 'Spam')
# Issue 5890: subclasses of property do not preserve method __doc__ strings
class PropertySub(property):
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -45,6 +45,9 @@
- Issue #22486: Added the math.gcd() function. The fractions.gcd() function now is
deprecated. Based on patch by Mark Dickinson.
+- Issue #24064: Property() docstrings are now writeable.
+ (Patch by Berker Peksag.)
+
- Issue #22681: Added support for the koi8_t encoding.
- Issue #22682: Added support for the kz1048 encoding.
diff --git a/Objects/descrobject.c b/Objects/descrobject.c
--- a/Objects/descrobject.c
+++ b/Objects/descrobject.c
@@ -1313,7 +1313,7 @@
{"fget", T_OBJECT, offsetof(propertyobject, prop_get), READONLY},
{"fset", T_OBJECT, offsetof(propertyobject, prop_set), READONLY},
{"fdel", T_OBJECT, offsetof(propertyobject, prop_del), READONLY},
- {"__doc__", T_OBJECT, offsetof(propertyobject, prop_doc), READONLY},
+ {"__doc__", T_OBJECT, offsetof(propertyobject, prop_doc), 0},
{0}
};
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list