Inherit property getter documentation

Question

The decorator proposed here is able to inherit the docstring for methods but not for properties and getters.

I have tried to naively expand it but it seems that docstrings of properties are read-only. Is there any way to inherit those?

import types

def fix_docs(cls):
    for name, func in vars(cls).items():
        if isinstance(func, (types.FunctionType, property)) and not func.__doc__:
            print func, 'needs doc'
            for parent in cls.__bases__:
                parfunc = getattr(parent, name, None)
                if parfunc and getattr(parfunc, '__doc__', None):
                    func.__doc__ = parfunc.__doc__
                    break
    return cls


class X(object):
    """
    some doc
    """

    angle = 10
    """Not too steep."""

    def please_implement(self):
        """
        I have a very thorough documentation
        :return:
        """
        raise NotImplementedError

    @property
    def speed(self):
        """
        Current speed in knots/hour.
        :return:
        """
        return 0

    @speed.setter
    def speed(self, value):
        """

        :param value:
        :return:
        """
        pass

@fix_docs
class SpecialX(X):
    angle = 30

    def please_implement(self):
        return True

    @property
    def speed(self):
        return 10

    @speed.setter
    def speed(self, value):
        self.sp = value



help(X.speed)
help(X.angle)
help(SpecialX.speed)
help(SpecialX.ange)

This only gets me

Traceback (most recent call last):
<function please_implement at 0x036101B0> needs doc
<property object at 0x035BE930> needs doc
  File "C:\Program Files (x86)\JetBrains\PyCharm Community Edition 2016.2\helpers\pydev\pydevd.py", line 1556, in <module>
    globals = debugger.run(setup['file'], None, None, is_module)
  File "C:\Program Files (x86)\JetBrains\PyCharm Community Edition 2016.2\helpers\pydev\pydevd.py", line 940, in run
    pydev_imports.execfile(file, globals, locals)  # execute the script
  File "C:/Users/RedX/.PyCharm2016.2/config/scratches/scratch.py", line 48, in <module>
    class SpecialX(X):
  File "C:/Users/RedX/.PyCharm2016.2/config/scratches/scratch.py", line 10, in fix_docs
    func.__doc__ = parfunc.__doc__
TypeError: readonly attribute

Answer 1

Yeah, property docstrings are read-only. You'd have to make a new property:

replacement = property(fget=original.fget,
                       fset=original.fset,
                       fdel=original.fdel,
                       __doc__=parentprop.__doc__)

and replace the original with that.

It might be slightly better to replace the original function's docstring and then regenerate the property to automatically pass that through:

original.fget.__doc__ = parentprop.__doc__
replacement = property(fget=original.fget,
                       fset=original.fset,
                       fdel=original.fdel)

Answer 2

This version supports multiple inheritance and copying the documentation from a base's base by using __mro__ instead of __bases__.

def fix_docs(cls):
    """
    This will copy all the missing documentation for methods from the parent classes.

    :param type cls: class to fix up.
    :return type: the fixed class.
    """
    for name, func in vars(cls).items():
        if isinstance(func, types.FunctionType) and not func.__doc__:
            for parent in cls.__bases__:
                parfunc = getattr(parent, name, None)
                if parfunc and getattr(parfunc, '__doc__', None):
                    func.__doc__ = parfunc.__doc__
                    break
        elif isinstance(func, property) and not func.fget.__doc__:
            for parent in cls.__bases__:
                parprop = getattr(parent, name, None)
                if parprop and getattr(parprop.fget, '__doc__', None):
                    newprop = property(fget=func.fget,
                                       fset=func.fset,
                                       fdel=func.fdel,
                                       parprop.fget.__doc__)
                    setattr(cls, name, newprop)
                    break

    return cls

Tests:

import pytest


class X(object):

    def please_implement(self):
        """
        I have a very thorough documentation
        :return:
        """
        raise NotImplementedError

    @property
    def speed(self):
        """
        Current speed in knots/hour.
        :return:
        """
        return 0

    @speed.setter
    def speed(self, value):
        """

        :param value:
        :return:
        """
        pass


class SpecialX(X):

    def please_implement(self):
        return True

    @property
    def speed(self):
        return 10

    @speed.setter
    def speed(self, value):
        self.sp = value


class VerySpecial(X):

    def speed(self):
        """
        The fastest speed in knots/hour.
        :return: 100
        """
        return 100

    def please_implement(self):
        """
        I have my own words!
        :return bool: Always false.
        """
        return False

    def not_inherited(self):
        """
        Look at all these words!
        :return:
        """


class A(object):

    def please_implement(self):
        """
        This doc is not used because X is resolved first in the MRO.
        :return:
        """
        pass


class B(A):
    pass


class HasNoWords(SpecialX, B):
    def please_implement(self):
        return True

    @property
    def speed(self):
        return 10

    @speed.setter
    def speed(self, value):
        self.sp = value


def test_class_does_not_inhirit_works():
    fix_docs(X)


@pytest.mark.parametrize('clazz', [
    SpecialX,
    HasNoWords
])
def test_property_and_method_inherit(clazz):
    x = fix_docs(clazz)
    assert x.please_implement.__doc__ == """
        I have a very thorough documentation
        :return:
        """

    assert x.speed.__doc__ == """
        Current speed in knots/hour.
        :return:
        """


def test_inherited_class_with_own_doc_is_not_overwritten():
    x = fix_docs(VerySpecial)
    assert x.please_implement.__doc__ == """
        I have my own words!
        :return bool: Always false.
        """

    assert x.speed.__doc__ == """
        The fastest speed in knots/hour.
        :return: 100
        """