cpython: 1e8a768fa0a5 (original) (raw)

Mercurial > cpython

changeset 96010:1e8a768fa0a5

Issue #24064: Property() docstrings are now writeable. (Patch by Berker Peksag.) [#24064]

Raymond Hettinger python@rcn.com
date	Wed, 13 May 2015 01:09:59 -0700
parents	4cf37a50d91a
children	79c884cc9625
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
diffstat	7 files changed, 63 insertions(+), 2 deletions(-)[+] [-] 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

line wrap: on

line diff

--- a/Doc/library/collections.rst +++ b/Doc/library/collections.rst @@ -924,6 +924,15 @@ create a new named tuple type from the : >>> 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:

--- a/Doc/whatsnew/3.5.rst +++ b/Doc/whatsnew/3.5.rst @@ -234,6 +234,10 @@ Some smaller changes made to the core Py

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 @@ code 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 ----------

--- a/Lib/test/test_collections.py +++ b/Lib/test/test_collections.py @@ -199,6 +199,14 @@ class TestNamedTuple(unittest.TestCase): 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")[](#l3.8)

def test_doc_writable(self):

   Point = namedtuple('Point', 'x y')[](#l3.10)

   self.assertEqual(Point.x.__doc__, 'Alias for field number 0')[](#l3.11)

   Point.x.__doc__ = 'docstring for Point.x'[](#l3.12)

   self.assertEqual(Point.x.__doc__, 'docstring for Point.x')[](#l3.13)

+ def test_name_fixer(self): for spec, renamed in [ [('efg', 'g%hi'), ('efg', '_1')], # field with non-alpha char

--- a/Lib/test/test_descr.py +++ b/Lib/test/test_descr.py @@ -2022,7 +2022,7 @@ order (MRO) for bases """ self.assertIs(raw.fset, C.dict['setx']) self.assertIs(raw.fdel, C.dict['delx'])

   for attr in "__doc__", "fget", "fset", "fdel":[](#l4.7)

   for attr in "fget", "fset", "fdel":[](#l4.8)
       try:[](#l4.9)
           setattr(raw, attr, 42)[](#l4.10)
       except AttributeError as msg:[](#l4.11)

@@ -2033,6 +2033,9 @@ order (MRO) for bases """ self.fail("expected AttributeError from trying to set readonly %r " "attr on a property" % attr)

```
   raw.__doc__ = 42[](#l4.16)
```

   self.assertEqual(raw.__doc__, 42)[](#l4.17)

+ class D(object): getitem = property(lambda s: 1/0)

--- a/Lib/test/test_property.py +++ b/Lib/test/test_property.py @@ -76,6 +76,13 @@ class PropertyNewGetter(object): """new docstring""" return 8 +class PropertyWritableDoc(object): +

@property
def spam(self):
```
   """Eggs"""[](#l5.11)
```
```
   return "eggs"[](#l5.12)
```

+ class PropertyTests(unittest.TestCase): def test_property_decorator_baseclass(self): # see #1620 @@ -150,6 +157,21 @@ class PropertyTests(unittest.TestCase): foo = property(foo) C.foo.isabstractmethod

@unittest.skipIf(sys.flags.optimize >= 2,

                "Docstrings are omitted with -O2 and above")[](#l5.22)

def test_property_builtin_doc_writable(self):
```
   p = property(doc='basic')[](#l5.24)
```

   self.assertEqual(p.__doc__, 'basic')[](#l5.25)

```
   p.__doc__ = 'extended'[](#l5.26)
```

   self.assertEqual(p.__doc__, 'extended')[](#l5.27)

@unittest.skipIf(sys.flags.optimize >= 2,

                "Docstrings are omitted with -O2 and above")[](#l5.30)

def test_property_decorator_doc_writable(self):

   sub = PropertyWritableDoc()[](#l5.32)

   self.assertEqual(sub.__class__.spam.__doc__, 'Eggs')[](#l5.33)

   sub.__class__.spam.__doc__ = 'Spam'[](#l5.34)

   self.assertEqual(sub.__class__.spam.__doc__, 'Spam')[](#l5.35)

Issue 5890: subclasses of property do not preserve method doc strings

class PropertySub(property):

--- a/Misc/NEWS +++ b/Misc/NEWS @@ -45,6 +45,9 @@ Library

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.

--- a/Objects/descrobject.c +++ b/Objects/descrobject.c @@ -1313,7 +1313,7 @@ static PyMemberDef property_members[] = {"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} };