[Python-Dev] One-line abstractmethod function?

[Terry Reedy]

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