[Python-Dev] One-line abstractmethod function?
tjreedy at udel.edu
Sat Dec 7 00:44:59 CET 2013
On 12/6/2013 5:46 AM, Steven D'Aprano wrote:
> On Fri, Dec 06, 2013 at 07:28:57AM +0100, Gregory Salvan wrote:
>> class MyObject(metaclass=ObjectSpec):
>> ''' MyObject doc'''
>> 'attr1 contains something'
>> attr1 = None
>> 'attr2 contains something'
>> attr2 = str
>> 'method1 do something'
>> method1 = NotImplementedMethod('self', 'arg1', kwarg1=str)
> I really don't like the idea of extending the docstring syntax to
> arbitrary objects.
> Another issue is that many objects (particularly built-ins) cannot take
> additional attributes. So where are you going to attach the docstrings?
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.
A half-way measure would be to extend help() (pydoc, I guess) to
recognize the same attribute comment conventions as Sphinx autodoc when
source is available, as it usually is. If we do this, I think the
conventions should be 'blessed' in an info pep. Docstrings are seldom
needed for runtime execution, which is why we have an option to remove them.
Terry Jan Reedy
More information about the Python-Dev