inherit-docstring: Pythonでdocstringの一部を継承するdecorator

Pythonでクラスを継承する際にdocstringにあるパラメーターの説明などに関して、親クラスのものを継承しつつ必要な部分を変更したり追加したりしたい、ということを実現するライブラリを作りました。

Pythonのdocstringをクラス間で継承する
既存のライブラリでうまくいかないところ
作ったもの: inherit-docstring
inherit-docstringで対応しているセクション
例
やってみて

Pythonのdocstringをクラス間で継承する

Pythonでクラスや関数を定義した最初の行からコメントを書くと docstring(PEP 8, PEP 257) という形で処理され、helpで見る際にその説明が表示されるようになります。

クラス継承した際にはクラスの属性値や関数の変数などは同じものがあるのでそれらは親クラスの説明をそのまま使いたいことが多いです。

ただ、通常のPythonのクラス継承ではdocstringは継承されないので子クラスでは説明をすべて各必要があります。

特にdataclassを使うと__init__に渡せるパラメーターとして子クラスで変数を追加したい場合は追加分だけ書けば済むので、その際にdocstringだけ親の方で定義されたものも全部書くのはちょっと微妙です。

多くの重複を産んでしまい、ちょっとした説明変更でも全部変更しようにも大変なことになるのでできればdocstringもいい感じに継承して欲しいところ。

というわけで以前ちょっと色々調べてみました。

Pythonでdocstringの一部を継承する方法

いくつか既存のライブラリもあるわけですが、結局完全に自分のやりたいことを満たせるものがなかったので自分で作ってみることに。

既存のライブラリでうまくいかないところ

親のクラスにメタクラスとして与えることでそれを継承したクラスではdocstringを自動的に継承できるようにしたもの。

上で調べてから上のポストにも書いたようにこれにちょっと手を加えてこれを主に使ってました。

ただ手を入れたとこに加えて色々とうまく行かない部分もあり、更に手を加えようとすると自分用に一から作った方が良いのでは、と。

また、メタクラスだと、中身を全部理解してれば良いのですがライブラリとして使うと何かしら副作用が出たときに分かりづらいのが辛いところ。

なのでシンプルにデコレーターで使いたいときに与えるだけ、の形の方が管理はしやすいです。

他のものはデコレーターのものでも使い方がちょっと面倒だったり関数のみでクラスのものは引き継げなかったり。

作ったもの: inherit-docstring

pipを使って

$ pip3 install inherit-docstring

とかでインストールできます。

対応しているのは Numpy Style のdocstringになります。

使い方は継承した子クラス側に@inherit-docstringというデコレーターをつけるだけです。

inherit-docstringで対応しているセクション

Numpy StyleのdocstringではParametersなどセクションに区切ってドキュメントが書かれています。

基本的にセクションは-で下線を引かれたセクション名で始まります。

例外として、ヘッダー部分(最初の書き出し部分、セクション名なし)と、廃止をお知らせする.. deprecated:: x.y.zで始まるセクションがあります。

また、Parametersなどは値の名前とその型、及びその説明、といった形式になっています。 inherit-docstringでは以下のセクションに関してはパラメーターセクションとして値、型、説明に分ける解析を行います。

Attributes
Parameters
Returns
Yields
Receives
Raises
Warns
Warnings

これらのセクションでは子クラス側同じセクションを定義した場合、親クラスで定義したものをすべて引き継いだ上で新たな値があればそれを加え、同じ値がある場合は説明を子クラスで定義したものに置き換えます。[

パラメーターセクションではないセクションに関しては親クラスにのみあるものはそのまま引き継ぎ、子クラスで追加したものはそのまま追加し、両方に存在する場合は小クラスのものにセクション全体を置き換えます。

例

例として以下のような親クラス(Parent)とそれを継承した子クラス(Child)がある場合に使ってみます。

from inherit_docstring import inherit_docstring

class Parent:
    """Parent class.

    This is an explanation.

    Attributes
    ----------
    name: str
        The name of
        the parent.
    age:
        The age. w/o type.

    Notes
    -----
    This is parent's note.
    """

    name: str = 'parent'
    age: int = 40

    def func1(self, param1: int, param2: int) -> int:
        """Parent's func1.

        Parameters
        ----------
        param1: int
            First input.
        param2: int
            Second input.

        Returns
        -------
        ret: int
            param1 + param2
        """

        return param1 + param2

    def func2(self) -> None:
        """Parent's func2.

        Returns
        -------
        ret: str
            something
        """

        return 'Something'

@inherit_docstring
class Child(Parent):
    """Child class.

    Attributes
    ----------
    sex: str
        Additional attributes.
        girl or boy.
    """

    sex: str = "boy"

    def func1(self, param1: int, param2: int) -> int:
        """Child's func1.

        Returns
        -------
        ret: int
            param1 - param2
        """

        return param1 - param2

これの子クラスの方のをhelp(Child)で見てみると以下のような出力になります。

class Child(Parent)
 |  Child class.
 |
 |  Attributes
 |  ----------
 |  name: str
 |      The name of
 |      the parent.
 |  age:
 |      The age. w/o type.
 |  sex: str
 |      Additional attributes.
 |      girl or boy.
 |
 |  Notes
 |  -----
 |  This is parent's note.
 |
 |  Method resolution order:
 |      Child
 |      Parent
 |      builtins.object
 |
 |  Methods defined here:
 |
 |  func1(self, param1: int, param2: int) -> int
 |      Child's func1.
 |
 |      Parameters
 |      ----------
 |      param1: int
 |          First input.
 |      param2: int
 |          Second input.
 |
 |      Returns
 |      -------
 |      ret: int
 |          param1 - param2
 ...