Reply-To set to python-ideas@python.org. Terry Reedy writes:
For data attributes, which are usually mutable, it should be attached to the attribute *concept*, which is represented by the name, rather than the current but usually changeable value. Values are usually already documented either by a value representation or a docstring. This could be done with a string subclass that is used as needed.
For methods, the value is nearly always constant. When multiple methods share the same function, they usually also share the same name, and represent the same concept.
Aside: Properties are which? Data, or method? It's also not clear to me that "def first (self): return self.values[0]" is unlikely to be used for completely different purposes than getting the head of a list. I conclude the considerations above are mostly red herrings. The important thing, I suppose, is that the names of attributes defined in a class are not mutable. This means that their docstrings can be kept in a completely separate dict (or other string -> string mapping), which could even be stored in a separate file. (Emacs Lisp uses this to good effect. The DOC file for XEmacs is 1.6MB; for GNU Emacs it's 2.4MB.) Of course it has its problems, but they're pretty minor.