ノートブックをキレイにするためのTips

https://2023-apac.pycon.jp/poster

Transcript

1. ノートブックをキレイにするためのTips 桂川大輝 セル内の冪等性を担保した変数の扱い方 後続処理への影響を避けるバリデーション その他 特定のセルを複数回実行した場合であっても、後続処理に意図した値を伝えるため に、セル内の冪等性を担保した変数の扱い方をすると良いです。例えば、変数を使い まわさない（変数の再代入をしない）ことが挙げられます。 後続処理が期待していない値を検知するために、可能な限り早期にバリデーションを すると良いです。また、データのバリデーションを実現するライブラリであるpydanticを 活用することで、パラメータや変数（定数）を容易かつ早期に検知することが可能で す。 • テキスト（Markdown）のセルによる説明の追加 • 適度なセルの分割 • 適度なファイルへの分割 • フォーマッターの導入 • リンターの導入 • Gitの導入 • 「すべてのセルを実行」で問題なく実行されることを確認 • CI（継続的インテグレーション）の導入 • コードレビューの実施（意図が伝えられていない箇所の洗い出し） • 「出力をすべて消去」した上で管理（オプション） 変数を使いまわさない（変数の再代入をしない） 早期のバリデーション 早期のバリデーション（pydantic） # year = year + 1 next_year = year + 1 # 冪等 year = 2023 FIRST_YEAR = 2010 assert conference_year > FIRST_YEAR from pydantic.dataclasses import dataclass, Field FIRST_YEAR = 2010 @dataclass class Conference: name: str year: int = Field(ge=FIRST_YEAR) conference = Conference(name="PyCon APAC", year=2023) 関数の振る舞いを伝える簡易なテスト doctestを使うことで、関数の振る舞い伝える簡易なテストの実現ができます。それに 加えて、テストであることによって関数が意図した振る舞いであることを担保できま す。 doctestを使った簡易なテスト def add_year(year): ''' >>> add_year(2023) 2024 ''' return year + 1 import doctest doctest.run_docstring_examples(add_year, globals()) 管理コストの低いパラメータの扱い方 コードに残さないセキュアな情報の扱い方 マジックナンバーの防止 意図を伝えるための変数と定数の定義 調整の可能性があるパラメータは、様々なセルに記述するのではなく、可能な限り少 ないセルに集約すると、見通しが良く、管理コストが低くなります。そして、ノートブック の冒頭にあると、さらに見通しが良いです。実行毎に指定する値は、実行者が入力す る仕組みにすると、その旨を伝えられます。 他者への共有が望ましくないパスワードなどのセキュアな情報は、漏洩するリスクか ら、コードでの管理が望ましくありません。実行者に入力させる仕組みにするか、環境 変数として管理をすると、その旨を伝えられます。 変数や定数を定義する際は、型ヒントやデータクラスにより、どんな内容を意図してい るのかを示すことができます。 マジックナンバーになり得る値は列挙型で定義をしておくことで、以降のコードにおい てマジックナンバーを防止することができます。 from getpass import getpass password = getpass("パスワードを入力してください: ") パスワードを入力してください: import os password = os.environ.get("PASSWORD") 実行者が入力する仕組み（入力内容をマスク） 環境変数として管理 パラメータの集約 実行者が入力する仕組み email_address = input("Eメールアドレスを入力してください: ") Eメールアドレスを入力してください: # 乱数の種 RANDOM_SEED = 2023 # PyCon APAC 2023のセッション数 NUMBER_OF_SESSIONS = 5 from enum import Enum, unique @unique # 重複を防止 class Prefecture(Enum): # ※一部省略 TOKYO = 13 OSAKA = 27 型ヒントによる意図の表現 データクラスによる意図の表現 conference_name: str = "PyCon APAC" conference_year: int = 2023 from dataclasses import dataclass @dataclass class Conference: name: str year: int print(f"PyCon APAC 2023の開催地：{Prefecture(13).name}") conference = Conference(name="PyCon APAC", year=2023) 列挙型によるマジックナンバーになり得る値の定義 Jupyter NotebookやGoogle Colaboratoryなどのノートブックは、データ分析などの目的で使用されるインタラクティブにコードの記述や実行が可能な開発環境です。作成した ノードブックを他者や未来の自分が改めて閲覧や実行をする可能性がある場合、実装の意図を伝えるために可読性を高く、意図した振る舞いを担保するために堅牢性を高くす ることが大事です。ただし、ノートブックはそれ自体がソフトウェアとして実装されるものではないことから、可読性や堅牢性を向上させるメリットとコストのトレードオフを特に注意 する必要があります。本発表では、ノートブックの可読性や堅牢性を向上させる（キレイにする）ために、可能な限りコストをかけずにメリットを得る方法（Tips）を紹介します。ご自 身の管理されているノートブックの状況に合わせて、採用を検討してください。 # print(year) print(next_year) = year + 1 # 冪等