Patch #1434038: property() now uses the getter's docstring if there is

no "doc" argument given. This makes it possible to legitimately use
property() as a decorator to produce a read-only property.

Doc/lib/libfuncs.tex

@@ -771,7 +771,12 @@ class C(object):
     x = property(getx, setx, delx, "I'm the 'x' property.")
 \end{verbatim}
 
+  If given, \var{doc} will be the docstring of the property attribute.
+  Otherwise, the property will copy \var{fget}'s docstring (if it
+  exists).
+
   \versionadded{2.2}
+  \versionchanged[Use \var{fget}'s docstring if no \var{doc} given]{2.5}
 \end{funcdesc}
 
 \begin{funcdesc}{range}{\optional{start,} stop\optional{, step}}

Lib/test/test_descr.py

@@ -2008,6 +2008,18 @@ def properties():
     else:
         raise TestFailed, "expected ZeroDivisionError from bad property"
 
+    class E(object):
+        def getter(self):
+            "getter method"
+            return 0
+        def setter(self, value):
+            "setter method"
+            pass
+        prop = property(getter)
+        vereq(prop.__doc__, "getter method")
+        prop2 = property(fset=setter)
+        vereq(prop2.__doc__, None)
+
 def supers():
     if verbose: print "Testing super..."
 

Misc/NEWS

@@ -12,6 +12,10 @@ What's New in Python 2.5 alpha 1?
 Core and builtins
 -----------------
 
+- Patch #1434038: property() now uses the getter's docstring if there is
+  no "doc" argument given. This makes it possible to legitimately use
+  property() as a decorator to produce a read-only property.
+
 - PEP 357, patch 1436368: add an __index__ method to int/long and a matching
   nb_index slot to the PyNumberMethods struct.  The slot is consulted instead
   of requiring an int or long in slicing and a few other contexts, enabling

Objects/descrobject.c

@@ -1081,6 +1081,8 @@ PyWrapper_New(PyObject *d, PyObject *self)
     class property(object):
 
         def __init__(self, fget=None, fset=None, fdel=None, doc=None):
+            if doc is None and fget is not None and hasattr(fget, "__doc__"):
+                doc = fget.__doc__
             self.__get = fget
             self.__set = fset
             self.__del = fdel
@@ -1182,6 +1184,7 @@ static int
 property_init(PyObject *self, PyObject *args, PyObject *kwds)
 {
 	PyObject *get = NULL, *set = NULL, *del = NULL, *doc = NULL;
+	PyObject *get_doc = NULL;
 	static char *kwlist[] = {"fget", "fset", "fdel", "doc", 0};
 	propertyobject *gs = (propertyobject *)self;
 
@@ -1196,6 +1199,15 @@ property_init(PyObject *self, PyObject *args, PyObject *kwds)
 	if (del == Py_None)
 		del = NULL;
 
+	/* if no docstring given and the getter has one, use that one */
+	if ((doc == NULL || doc == Py_None) && get != NULL && 
+	    PyObject_HasAttrString(get, "__doc__")) {
+		if (!(get_doc = PyObject_GetAttrString(get, "__doc__")))
+			return -1;
+		Py_DECREF(get_doc); /* it is INCREF'd again below */
+		doc = get_doc;
+	}
+
 	Py_XINCREF(get);
 	Py_XINCREF(set);
 	Py_XINCREF(del);