チュートリアルの全体の流れの詳細を詰める

[hrsano645]

チュートリアルのイベントページに記載されている内容をさらに深堀して、扱う内容を決めていく 細かい時間の流れまではここでは扱わず、別issueにします。

現在想定している流れ

• Pythonのローカル環境の状態確認
• VSCodeでのセットアップ状況確認
• Slackbot/pytest/sphinxを扱う開発環境のファイルをDL: Githubリポジトリにて用意
  • DL or git cloneなどで
• Slackbot編
  • ローカル環境で動作させる
  • チュートリアルで動作するSlackbotの概要説明: （API利用は今のところの想定です）
    • 挨拶を返すbot: （国ごとの言葉で返したらその国ごとに返す機能）
    • Livedoor天気API で天気を聞いたら答えるbot
    • connpass API でオンラインイベント検索を行うbot（予定）
• 休憩予定（お昼？
• pytestによる、bot機能のユニットテスト
  • pytestコマンドの使い方
  • pytestを扱ったテストの書き方
  • parametrizeを扱った、テストパラメータの導入 Parametrizing fixtures and test functions — pytest documentation
  • fixtureによるテストデータの共通化（予定、使わないかも）pytest fixtures: explicit, modular, scalable — pytest documentation
  • 挨拶bot: 各国の挨拶を正しく返すかのテスト
  • （API利用のテストは、利用APIの負荷を考慮して行わない, モックの検討）
• 休憩予定
• sphinxによるドキュメンテーション: slackbotの使い方と、テストで利用した関数のリファレンスを乗せる予定）
  • sphinxのシステムの紹介
  • 用意したdocsフォルダの構造
  • sphinxでドキュメントの生成
  • ドキュメントの編集: slackbotの使い方についての足らない部分を書いてドキュメントのビルドを行う
  • docstringからリファレンスの生成: sphinx.ext.autodoc -- docstringからのドキュメントの取り込み — Sphinx 4.0.0+/6d5478b04 ドキュメント

[hrsano645]

Python(3.7)のローカル環境の状態確認: 各参加者のローカル開発環境の状況をチェック

• OSの種類確認

  • Win, macOSのみサポート。
  • そのほかのOSは基本的にサポート無し

• Pythonをどのようにセットアップしたか

  • Python.org 公式
  • パッケージマネージャー(Win:MSストア, macOS:Homebrewとか）
  • それ以外はサポート無し

• Pythonのバージョンの確認

  • 3.7~ を推奨
  • 2系, 3.6以下は対応せず

• Pythonが正しく動くかの確認

  • win10
  • PATHが通っているかのチェック: Powershell上で python --version でインストール済みのバージョンチェック
  • macOS
  • PATHが通っているかのチェック: ターミナルアプリで python --version でインストール済みのバージョンチェック

• 他の留意点

  • pyenv, pipenv, などの最近扱われている環境構築に使うツールは扱わない
  • ただpipenvはPyPAで扱うので、そろそろ使ってもよいかもしれない？ Pipfile同梱させておいてご自由にでもあり
  • anaconda系は検討しない
  • python.orgの提供物でないバイナリは
  • （講師が慣れていないからというのもある）
  • anacondaがインストールされている環境で、公式のPythonを入れると混乱してしまうので、その場合の対処法を考える必要あり。PATHの優先度を変えてもらう, 利用していない場合はanacondaのアンインストールを検討してもらう

• チュートリアルの資料のDL

  • GitHubで開発してる。
  • git cloneか zipでDLしてください。

• 必要なサービスの登録

  • slackワークスペース
  • ngrok: オプショナル、登録しなくても一時的にurl発行が可能（8時間期限付き）なので、それを使えば問題ない。登録したほうがサービスとして使いやすい話として、登録して、ngrokコマンドの認証方法も記載する

[hrsano645]

VSCode Liveshareはオプションになるので、VSCodeのセットアップ, Live shareの設定は別のファイルにする

VSCodeでのセットアップ状況確認: 特にLive Shareを使うので、そのセットアップができているかのチェック

• Live Shareを行うため、各自のGitHubアカウント/MSアカウントが必要。なるべくGitHubアカウントでの説明にする予定
  • GitHubアカウントが必須とチュートリアルのconnpassページに記載が必要 ,<- 別issueを立てる
• VSCodeのPython拡張をインストール

[hrsano645]

Slackbot編

• ローカル環境の準備

  • venvで仮想環境を作る
  • venv -> pip requiments.txt でのインストール
  • ngrokを使える状況か: winはDL先を記載して、DLして配置。macosもzipDL or homebrew
  • https://ngrok.com/download
  • https://formulae.brew.sh/cask/ngrok

• Slackアプリとしてのセットアップをする

  • 権限回りはセットアップを先にして、あとで説明する（順番通りに進めて、その順番で解説する）
  • 動作確認をして、正しく動くかの確認: 最初に扱うサンプルコードを動かして、botの意思疎通ができるかをチェックしてもらう

• チュートリアルで動作するSlack botの概要説明

  • slack botのシステム概要を説明: どんな技術が利用されているか。ざっくりで。(pysuruga-13-handsonの資料流用）

• wgreet 挨拶を返すbot:

  • -> 目的:人口無能をまずは試してもらう
  • 国旗、挨拶の言葉、のテーブルを用意してテーブルからランダムに挨拶をかえす
  • 英語、中国、など5つぐらいの言語の挨拶をコメントアウトで用意。参加者に選んで実装してもらう
  • もちろん自由に言葉を変えてもらっても良し

• 挨拶botの実装ステップ

  1. まずslackevetsapiのexampleをそのまま乗せておいて、そのbotで受け答えできるか調べてみる
  2. 次に、その中でテーブルを作って、ランダムで返す関数を用意
  3. 最後に挨拶をかえす部分をモジュール化する -> 伏線:テストとレファレンスを書きやすくする

• connpass [yyyymm] connpass API でオンラインイベント検索を行うbot:

  • -> 目的:ITエンジニアに身近なサービス（少なくとも参加者全員知っているはず）で体験する
  • connpass 202008 と打つと、8月のイベントの20件分を取得可能
  • requests + jsonでAPIから取得したjsonのパースを体験する
  • 検索ワードはハードコートしている。検索結果も20件でハードコード

• connpassbotの実装ステップ

  1. 共通化した手法を元に、connpassbotを作る。最初は1関数にすべてのせる
  2. APIリクエストとbotの答えを返す関数を別途作り、分離していく

• tenki [地域名] 気象庁電文XMLを使って週間天気予報を答える天気bot

  • -> 目的:最後に実用的なbotを作成する
  • 説明的にはxmlのパース周りに絞る（気象庁のサービスとしての話はプログラムの流れ説明の時ぐらいに絞る）
  • requests + bs4を使ってxmlのパースをする
  • 対応地域は絞っておいて（減らしておいて）追加してbotの拡張をしてもらう

• 天気botの実装ステップ

  1. （既にxmlのDLはやっておいた状態）
  2. xmlのパースを進める

• QA:

  • 実はプラグイン的なことができるのでは？ -> inspect/importlibライブラリ+アダプターパターン（デザインパターン）を使うことで、特定のパッケージフォルダにいれたbotのモジュールを動的に読み込める、プラグイン的な扱いが可能

[hrsano645]

pytestによる、bot機能のユニットテスト

botの実際に機能を関数にして、テストをする。botが返答する部分（Slackとのインターフェイス的な部分）は共通の処理で行えるのが理想、その予定で進める

• pytestコマンドの使い方
  • vオプション
  • テストを実行する場所の位置指定
• pytestを扱ったテストの書き方
  • assertを使う: シンプルに扱える。
• parametrizeを扱った、テストパラメータの導入 Parametrizing fixtures and test functions — pytest documentation
  • botのin / outのデータをここで指定することを予定
• fixtureによるテストデータの共通化（予定、使わないかも）pytest fixtures: explicit, modular, scalable — pytest documentation
• monkeypatch: オブジェクトの置き換えを行う: Monkeypatching/mocking modules and environments — pytest documentation
  • テストデータを用意するとき便利。関数の挙動をテスト用に置き換える
  • APIのモックを用意してみる？: monkeypatchで外部から取得するデータ類をテストデータに置き換える方法を提案
• テストのステップ
  • 実行して失敗した状態からスタート。faild=>pass
  • parametrizeでサンプルを書いてみる: リスト>タプルで作ったパラメーターをassert
  • fixtureでjson(文字列)をロードして、複数のテストを書いてみる（適合する/適合しないレベル）
  • monkeypatch: 公式にあるホームを返す機能を元にテストをしてみる -> https://docs.pytest.org/en/latest/monkeypatch.html#simple-example-monkeypatching-functions
  • 挨拶bot: 各国の挨拶を正しく返すかのテスト
  • connpass bot: jsonの取得をmonkeypatchで置き換え
  • 気象庁xmlの取得をmonkeypatchで置き換え、parametarizeで地域の追加

[hrsano645]

sphinxによるドキュメンテーション: slackbotの使い方と、テストで利用した関数のリファレンスを乗せる予定）

• sphinxのシステムの紹介: ドキュメントの構造を作る, pythonのdocstringからAPIリファレンス生成できる, プラグイン（扱う予定があれば）
• sphinx-quickstartでひな形的なドキュメントの構成を用意する
• 今回のチュートリアルで用意したdocsフォルダの構造の紹介
  • slackbotの使い方: ビルド、生成したhtmlファイルを見る, テーマの変更
  • slackbot内のテスト可能な関数のリファレンス -> slackbotの開発者向け情報として
• 用意したドキュメントひな形の紹介: 構造の作り方
• ドキュメントの編集: slackbotの使い方についての足らない部分を書いてドキュメントのビルドを行う
  • 挨拶や天気の追加した情報を、各自思いのままに入れてもらう or いくつかパターンを用意する？
• docstringからリファレンスの生成: sphinx.ext.autodoc -- docstringからのドキュメントの取り込み — Sphinx 4.0.0+/70d521ad9 ドキュメント
  • apidocの設定(conf.pyでextentionsやsys.pathにpythonのモジュールパスを入れる）
  • sphinx-apidoc コマンド
  • docstringの足らない部分を書いていく
  • 挨拶bot: ランダムに天気情報を返す関数
  • connpassbot: jsonの取得関数, botが答える文字列生成の関数
  • 天気bot: xml取得関数, botが答える文字列生成の関数
  • botrunのメッセージハンドル（botの登録方法を記載する）
  • type annotationの組み合わせで行う。(python3.7を必須にしたので問題ないはず）
  • docstringはGoogleスタイルで行うのでnapoleonの導入も必要: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html?highlight=google#type-annotations
  • オプショナル: doc-cov · PyPIの話も余裕があったら入れてもいいかも -> カバレッジの話をしないといけないから、必要性とか時間が心配

[hrsano645]

悩んでる部分

• 模範解答を同梱させて、手打ちが大変な方向けにショートカットを提供する https://github.com/py-suruga/pycon-jp-2020-tutorial/issues/1#issuecomment-663559490 がどのタイミングで、どのように紹介するべきか
• LiveShareの運用方法がまだ定まってない。PyConJP側とも相談したほうがいいかな？

[hrsano645]

12 も追記できた。

[hrsano645]

tutorial_docs側に一通り項目を用意したので終了