Python: Override super-class docstring without function re-implementation

[rlanciloti]

I have a use-case where I have a generic super-class which provides standard functionality to all sub-classes. I would like the ability to overwrite the docstring for the super-class' functions in the subclass so they're more reflective of the sub-class.

from __future__ import annotations

import random

class Super:
    """
    This is a Super class.
    """
    def __init__(self, a: int, b: int) -> Super:
        """
        Super Constructor.

        Args:
            a (int): Val A
            b (int): Val B
            
        Returns:
            Super: New instance of the Super class.
        """
        self._a = a
        self._b = b
        
    def __eq__(self, __value: object) -> bool:
        """
        Overrides the `==` for the Super class.
        
        Examples:
            >>> Super(0, 1) == Super(0, 1)
                True
            >>> Super(0, 1) == Super(1, 0)
                False

        Args:
            __value (object): Object to compare to.

        Returns:
            bool: True if equivalent, else False.
        """
        if not isinstance(__value, Super):
            raise TypeError("Provided object is not comparable.")

        return self._a == __value._a and self._b == __value._b
    
    @classmethod
    def create_random(cls) -> Super:
        """
        Creates a new instance of Super with random values for A and B

        Returns:
            Super: New instance of the Super class with random values.
        """
        return cls(random.randint(0, 256), random.randint(0, 256))
        

class Sub(Super):
    """
    This is a Subclass.
    """
    def add(self) -> int:
        """
        Adds A and B together and returns the result.

        Returns:
            int: A + B
        """
        return self._a + self._b

If I were to generate the docs for the Sub class with inherited_members: true, I would see the Super docstring for __init__ as the Sub docstring for __init__, Super docstring for __eq__ as the Sub docstring for __eq__, as well as the Super docstring for create_random as the Sub docstring for create_random.

I would like to be able to add the following lines to the bottom of my file, and mkdocstrings would detect the overwritten docstrings and update the Sub docstrings accordingly.

Sub.__init__.__doc__ = """
Sub Constructor.

Args:
    a (int): Val A
    b (int): Val B
    
Returns:
    Sub: New instance of the Sub class.
"""

Sub.__eq__.__doc__ = """
Overrides the `==` for the Sub class.

Examples:
    >>> Sub(0, 1) == Sub(0, 1)
        True
    >>> Sub(0, 1) == Sub(1, 0)
        False

Args:
    __value (object): Object to compare to.

Returns:
    bool: True if equivalent, else False.
"""

Sub.create_random.__doc__ = """
Creates a new instance of Sub with random values for A and B

Returns:
    Sub: New instance of the Sub class with random values.
"""

If a better way could be found to overwrite the parent docstrings, then that would be sufficient.

[quattro]

+1. Having an example on how to handle this would be great. This is a common design pattern to handle programmatically adding documentation to __init__ functions for dataclasses (or equinox Modules) without having to implement the __init__ function itself.

[pawamoy]

Hello, thanks for the discussion/idea.

This is achievable with a Griffe extension. The extension would visit and handle attribute assignments (statements of the form a.b.c = x) to assign docstrings where relevant. Let me know if the documentation is clear enough. You can take inspiration from other extensions, for example by exploring the griffe-extension topic on GitHub: https://github.com/topics/griffe-extension