コードに言及する時にdocstringではなくsummaryを表示するようにした

python pyinspect meta

github.com

前回の記事であげた気になっていた点のうち１つを直した。それはdocstringが長すぎるという問題。

長いdocstringは引用したい部分自体の意図を弱めてしまう。完全に使い方の問題だけどdocstringとかが長いコードが嫌いになるかも。

今回のような表示でのdocstringの位置付けの問題ではある。ある全体のうちの一部分に目を向けてほしいという文脈での表示なのだけどdocstringは全体について語った全文。summaryとdescriptionは分かれてほしいという感じかも（summaryは雰囲気を掴めるので良い）。

以前はdocstringを全部表示していた

以前はdocstringを全部表示していた。例えば、argparseの1900行目に言及しようとした時にdocstringの方が長くなってしまう。

# 古いコードの場合
$ pyinspect quote argparse:L1900

こんなかんじに。長い。

class ArgumentParser(_AttributeHolder, _ActionsContainer):
    """Object for parsing command line strings into Python objects.

    Keyword Arguments:
        - prog -- The name of the program (default: sys.argv[0])
        - usage -- A usage message (default: auto-generated from arguments)
        - description -- A description of what the program does
        - epilog -- Text following the argument descriptions
        - parents -- Parsers whose arguments should be copied into this one
        - formatter_class -- HelpFormatter class for printing help messages
        - prefix_chars -- Characters that prefix optional arguments
        - fromfile_prefix_chars -- Characters that prefix files containing
            additional arguments
        - argument_default -- The default value for all arguments
        - conflict_handler -- String indicating how to handle conflicts
        - add_help -- Add a -h/-help option
        - allow_abbrev -- Allow long options to be abbreviated unambiguously
    """
# ...

    def _parse_known_args(self, arg_strings, namespace):
        # replace arg strings that are file references
        if self.fromfile_prefix_chars is not None:

# ...

        def consume_optional(start_index):

# ...

                    # successfully matched the option; exit the loop
                    elif arg_count == 1:
                        stop = start_index + 1
                        args = [explicit_arg]
                        action_tuples.append((action, args, option_string))

これを辞めた。

今度からはsummaryだけを表示する

今度からはsummaryを取り出す。今度はdocstringがうるさくない。

$ pyinspect quote argparse:L1900

/usr/lib/python3.7/argparse.py

class ArgumentParser(_AttributeHolder, _ActionsContainer):
    """Object for parsing command line strings into Python objects."""
# ...

    def _parse_known_args(self, arg_strings, namespace):
        # replace arg strings that are file references
        if self.fromfile_prefix_chars is not None:

# ...

        def consume_optional(start_index):

# ...

                    # successfully matched the option; exit the loop
                    elif arg_count == 1:
                        stop = start_index + 1
                        args = [explicit_arg]
                        action_tuples.append((action, args, option_string))

(ちょっと余白が多すぎるかもしれない？ (# ... のあとに改行を入れるのを辞める？))

ちなみに、今までと同様（古い形式）で表示したい場合には --show-fulldoc を付ければ良い。

$ pyinspect quote --show-fulldoc argparse:L1900

はい。

summary

summaryの決め方の詳細。

幾つかのライブラリなどのコードのdocstringをいろいろ見てみた所、概ね以下のような形になっているようだった。必ずきれいに空行を設けているものが多い。

"""
<summary>

<description>
<description>
<description>....
"""

あとこの辺のページなども見ても大丈夫そう。かならずsummaryのあとに改行が存在していそう。

そんなわけで "\n\n" で区切った先頭をsummaryとして取り扱うことにした。

ちなみに

ちなみに動的にも静的にもdocstringを取り出してそこからsummaryを抽出するようなコードを書いて試したりしていた。そのgist。