changeset: 96010:1e8a768fa0a5 user: Raymond Hettinger date: Wed May 13 01:09:59 2015 -0700 files: Doc/library/collections.rst Doc/whatsnew/3.5.rst Lib/test/test_collections.py Lib/test/test_descr.py Lib/test/test_property.py Misc/NEWS Objects/descrobject.c description: Issue #24064: Property() docstrings are now writeable. (Patch by Berker Peksag.) diff -r 4cf37a50d91a -r 1e8a768fa0a5 Doc/library/collections.rst --- a/Doc/library/collections.rst Wed May 13 01:22:54 2015 -0500 +++ b/Doc/library/collections.rst Wed May 13 01:09:59 2015 -0700 @@ -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 -r 4cf37a50d91a -r 1e8a768fa0a5 Doc/whatsnew/3.5.rst --- a/Doc/whatsnew/3.5.rst Wed May 13 01:22:54 2015 -0500 +++ b/Doc/whatsnew/3.5.rst Wed May 13 01:09:59 2015 -0700 @@ -234,6 +234,10 @@ * New Kazakh :ref:`codec ` ``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 ` ``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 -r 4cf37a50d91a -r 1e8a768fa0a5 Lib/test/test_collections.py --- a/Lib/test/test_collections.py Wed May 13 01:22:54 2015 -0500 +++ b/Lib/test/test_collections.py Wed May 13 01:09:59 2015 -0700 @@ -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 -r 4cf37a50d91a -r 1e8a768fa0a5 Lib/test/test_descr.py --- a/Lib/test/test_descr.py Wed May 13 01:22:54 2015 -0500 +++ b/Lib/test/test_descr.py Wed May 13 01:09:59 2015 -0700 @@ -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 -r 4cf37a50d91a -r 1e8a768fa0a5 Lib/test/test_property.py --- a/Lib/test/test_property.py Wed May 13 01:22:54 2015 -0500 +++ b/Lib/test/test_property.py Wed May 13 01:09:59 2015 -0700 @@ -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 -r 4cf37a50d91a -r 1e8a768fa0a5 Misc/NEWS --- a/Misc/NEWS Wed May 13 01:22:54 2015 -0500 +++ b/Misc/NEWS Wed May 13 01:09:59 2015 -0700 @@ -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 -r 4cf37a50d91a -r 1e8a768fa0a5 Objects/descrobject.c --- a/Objects/descrobject.c Wed May 13 01:22:54 2015 -0500 +++ b/Objects/descrobject.c Wed May 13 01:09:59 2015 -0700 @@ -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} };