From 370883675aea08289ce58757c93ed8333688bcf3 Mon Sep 17 00:00:00 2001 From: ftnext Date: Thu, 26 Oct 2023 02:38:09 +0900 Subject: [PATCH] [feat] Doctest Japanese transcript --- source/pyconapac/doctest.rst.txt | 88 ++++++++++++++++++++++++++++---- 1 file changed, 79 insertions(+), 9 deletions(-) diff --git a/source/pyconapac/doctest.rst.txt b/source/pyconapac/doctest.rst.txt index b080977..ac3bbe3 100644 --- a/source/pyconapac/doctest.rst.txt +++ b/source/pyconapac/doctest.rst.txt @@ -6,6 +6,10 @@ doctest 対話的な実行例をテストする +.. doctestは標準ライブラリにあります。 + 私は好きなライブラリです。 + どんなライブラリかというと「Test interactive Python examples」 + 関数のdocstring ============================================================ @@ -15,17 +19,38 @@ doctest https://docs.python.org/ja/3/glossary.html#term-docstring +.. 関数にはdocstringというものがありますよね。 + 用語集を引くと、 + A string literal which appears as the first expression in a function. + it(docstring) is the canonical place for documentation of the object. + ドキュメンテーション文字列 とも -------------------------------------------------- * https://docs.python.org/ja/3/tutorial/controlflow.html#tut-docstrings * **三連引用符** を用い、複数行にまたがった文字列リテラルとすることがほとんど +.. docstringはドキュメンテーション文字列(Documentation Strings)とも呼ばれます。 + クォートを3つ連続させた文字列にします。 + 改行を含められるので、複数行にまたがった文字列がほとんどです（TODO スライド組み換え？） + 百聞は一見にしかずです。 + .. https://docs.python.org/ja/3/tutorial/introduction.html#text docstringの例 -------------------------------------------------- +.. code-block:: python + + def fizzbuzz(number: int) -> str: + """FizzBuzzゲームを解く関数（：1行要約） + + ...（後述）... + """ + +.. fizzbuzz関数にdocstringを書きました。 + 関数定義（def）の直後に三連引用符を使った文字列を書いています + .. テストを通すための定義 >>> def fizzbuzz(number: int) -> str: ... if number % 3 == 0 and number % 5 == 0: @@ -37,14 +62,6 @@ docstringの例 ... else: ... return str(number) -.. code-block:: python - - def fizzbuzz(number: int) -> str: - """FizzBuzzゲームを解く関数（：1行要約） - - ...（後述）... - """ - Python対話モードの **実行例をdocstringに書く** -------------------------------------------------- @@ -52,6 +69,9 @@ Python対話モードの **実行例をdocstringに書く** :language: python :lines: 1-3,6-9,14 +.. docstringの続きには、Pythonの対話モードでfizzbuzz関数を実行したときの実行例を書きます。 + 1のときは文字列1、3のときはFizz + 対話モードの実行例を **テストとして実行** ============================================================ @@ -62,6 +82,9 @@ Python対話モードの **実行例をdocstringに書く** * :command:`python -m doctest fizzbuzz.py` +.. docstringに実行例を書いたファイルだけを作り、python -m doctestに相対パスを渡してテストを実行します。 + passするときは何もいいません + 実行結果の確認（:command:`-v` オプション） -------------------------------------------------- @@ -77,6 +100,9 @@ Python対話モードの **実行例をdocstringに書く** 4 passed and 0 failed. Test passed. +.. -vオプションを付けてdoctestを実行すると、実行結果が詳細に出力されます。 + テスト4つが通り、失敗はなし。テスト全体はpassしました + 関数のdocstringに限らず使えます -------------------------------------------------- @@ -85,6 +111,9 @@ nikkieはテキストファイル（特にreStructuredText）で頻繁に使用 * 書籍執筆 * **発表資料** 作成（本資料含む） +.. 私はPythonファイルに限らずdoctestを使います。 + このスライドのPythonの対話例はdoctestが通っているので、不安を感じずに登壇できています + 利用シーン：ライブラリのドキュメントにも -------------------------------------------------- @@ -98,9 +127,16 @@ nikkieはテキストファイル（特にreStructuredText）で頻繁に使用 https://scikit-learn.org/stable/modules/generated/sklearn.metrics.f1_score.html +.. doctestは有名なライブラリのドキュメントでも使われています。 + これはscikit-learnの例です（TODO ソースコード？） + ？PyTorch + doctestの注意点 ============================================================ +.. doctestには気をつけなければならない点があります。 + 先ほどのコードとの違いは文字列がダブルクォートという点だけです + .. 以下のコードのdoctestを通すだけのコード（doctest: +SKIPがtrimされないため） >>> def fizzbuzz(number): ... print('"Fizz"') @@ -141,6 +177,10 @@ doctestの注意点 ***Test Failed*** 1 failures. +.. このテストは落ちてしまいます。 + 期待値はダブルクォートで囲まれたFizz、実際の値はシングルクォートで囲まれたFizz。 + doctestはこの2つを別物として扱うので、テストが落ちます + 焦点：対話モードの出力結果として一致するか -------------------------------------------------- @@ -153,6 +193,10 @@ doctestの注意点 * doctestでも文字列はシングルクォートにする必要がある +.. ポイントとしては、doctestは対話モードの出力結果として一致するかを見ているので、それを念頭に考えるということです。 + 対話モードでダブルクォートで囲んだ文字列を入力しても、出力はシングルクォート囲みですね。 + doctestでは文字列はシングルクォートにする必要がある + 対話モードは ``repr`` 関数の返り値 -------------------------------------------------- @@ -160,6 +204,11 @@ doctestの注意点 https://docs.python.org/ja/3/tutorial/inputoutput.html#fancier-output-formatting +.. reprという組み込み関数があります。 + 対話例の出力は、reprの返り値と思っていただければと思います + +.. TODO? __repr__ + doctestから見るテストコードの書き方 ============================================================ @@ -170,6 +219,10 @@ doctestから見るテストコードの書き方 * 実行例を書くだけで、関数に **ある値を入力したときの出力** を検証できた * *3A* という見方を導入 +.. 別の話題、doctestから見るテストコードの書き方 + 実行例を書くだけで、関数にある値を入力したときの出力を検証できましたが、 + ここで3A(three A)という見方を導入します + 3A -------------------------------------------------- @@ -179,10 +232,12 @@ doctestから見るテストコードの書き方 https://xp123.com/articles/3a-arrange-act-assert/ +.. 3つのAでして、Arrange・Act・Assertです。 + 3Aで見るdoctest -------------------------------------------------- -コメントを使った説明のため、対話モードで示します +※コメントを使って説明するため、対話モードで示します .. code-block:: pycon @@ -190,6 +245,8 @@ https://xp123.com/articles/3a-arrange-act-assert/ >>> fizzbuzz(number) 'Fizz' +.. docstringではなく対話モードを使って、3Aとは何かを示していきます + Arrange -------------------------------------------------- @@ -202,6 +259,8 @@ Arrange >>> fizzbuzz(number) 'Fizz' +.. Arrangeはテストの準備です。ここでは簡単ですが、number変数に3を代入しました + Act -------------------------------------------------- @@ -214,6 +273,9 @@ Act >>> fizzbuzz(number) 'Fizz' +.. テスト対象の関数の実行がAct + numberをfizzbuzz関数に渡す + Assert -------------------------------------------------- @@ -226,9 +288,17 @@ Assert >>> fizzbuzz(number) 'Fizz' +.. 返り値が期待値と一致するかを検証するのがAssert + この3Aをテストを書くときに意識しています。 + 🥟doctest まとめ ============================================================ * 対話モードの **実行例を、docstringに書くだけ**！ * :command:`python -m doctest` にPythonファイルを渡してテスト実行 * テストコードの一歩目として非常にオススメです + +.. doctestをまとめますと + 対話モードの実行例を、docstringに書くだけで、テストできちゃう！ + コマンドはpython -m doctestです。 + テストコードを書いてみようと思ったらdoctestが一番書きやすいと思います