[Python] Sharing docstrings between classes

[danepitkin]

Describe the enhancement requested

PyArrow duplicates a lot of documentation in order to provide explicit docstring examples. Let's reduce the duplication of docstrings by providing a way to share docstrings between classes. See the way pandas did this as an example: https://pandas.pydata.org/docs/development/contributing_docstring.html#sharing-docstrings

A good example of duplication in PyArrow are the classes Table and RecordBatch. They both provide similar, sometimes identical, top-level implementations and docstrings, while typically only differing in low-level C++ implementation.

Here is an example of duplicative docstring descriptions.
class RecordBatch:

    @property
    def nbytes(self):
        """
        Total number of bytes consumed by the elements of the record batch.

        In other words, the sum of bytes from all buffer ranges referenced.

        Unlike `get_total_buffer_size` this method will account for array
        offsets.

        If buffers are shared between arrays then the shared
        portion will only be counted multiple times.

        The dictionary of dictionary arrays will always be counted in their
        entirety even if the array only references a portion of the dictionary.

        Examples
        --------
        >>> import pyarrow as pa
        >>> n_legs = pa.array([2, 2, 4, 4, 5, 100])
        >>> animals = pa.array(["Flamingo", "Parrot", "Dog", "Horse", "Brittle stars", "Centipede"])
        >>> batch = pa.RecordBatch.from_arrays([n_legs, animals],
        ...                                     names=["n_legs", "animals"])
        >>> batch.nbytes
        116
        """
        ...

class Table:

    @property
    def nbytes(self):
        """
        Total number of bytes consumed by the elements of the table.

        In other words, the sum of bytes from all buffer ranges referenced.

        Unlike `get_total_buffer_size` this method will account for array
        offsets.

        If buffers are shared between arrays then the shared
        portion will only be counted multiple times.

        The dictionary of dictionary arrays will always be counted in their
        entirety even if the array only references a portion of the dictionary.

        Examples
        --------
        >>> import pyarrow as pa
        >>> import pandas as pd
        >>> df = pd.DataFrame({'n_legs': [None, 4, 5, None],
        ...                    'animals': ["Flamingo", "Horse", None, "Centipede"]})
        >>> table = pa.Table.from_pandas(df)
        >>> table.nbytes
        72
        """
        ...

Component(s)

Python

[danepitkin]

This won't work for Cython until this issue is fixed: python/cpython#91309