MacにPython venv - VSCode - GitHub連携環境をインストールする記録です。
再インストールしてみたのを契機に、元記事を一般化しました。

環境は、MacOS Catalina、Python 3.8.7、VSCode1.52.1です。

1. Pythonのインストール

現時点（2021年1月）の最新版はPython3.9ですが、機械学習ライブラリの多くがやっとPython3.8対応になった段階ですので、Python3.9の利用はおすすめしません。Python3.8（の最新マイナー版）をインストールしましょう。

Python3.8.7のBig Sur対応は"not yet fully"という状態です。よって、Big SurへのOSアップデートは、次のPython3.8.8の登場（2021年2月頃）を待った方がよいです。

2021/8/12追記: Python3.9対応に時間がかかっていたTensorflowも、v2.5で対応しましたので、そろそろPython3.9解禁だと思います。

Python3.8のインストールには以下のようにいろいろな方法があります。（なお、Python3.7はhomebrewに先立つxcodeコマンドラインツールのインストールに含まれているはずです）

(1) homebrewによるインストール
(2) Python公式からGUIでのインストール
(3) Anaconda公式からGUIでのインストール
(4) pyenvによるインストール

今回は、VSCode公式にて推奨されている項1をおすすめします。また、この記事では、仮想環境としてpyenvやanacondaは使わない前提であり、それらを利用したインストール方法は採用しません。仮想環境の選択に関しては、項4も参照ください。

単純にbrew install pythonだとPython3.9がインストールされてしまうため、brew install python@3.8でインストールします。途中、brewの指示にしたがってください。最後に、brewの指示に出てくるecho 'export PATH="/usr/local/opt/python@3.8/bin:$PATH"' >> ~/.zshrcを実行してパスを有効にし、コマンドプロンプトアプリを再起動します。

コマンドラインから、python3.8というバージョン付きのpythonが動作することを確認ください。なお、pythonとだけ打つと、通常はpython2系が立ち上がるため注意してください。

2. GitHubリモートリポジトリの作成

GitHubリモートリポジトリとMacのローカルリポジトリを連携させるわけですが、いろいろ試してみて、「リモートを先に作る」方法が、最も簡単で間違わないように思います。

GitHubのサインアップ（アカウント作成）がまだであれば、しておきます。2FA（二段階認証）を設定しておくとよいでしょう。

GitHubのGUIで新規のリポジトリを作成します。以下のような画面が出ます。

リポジトリ名を入力して、Create repositoryをクリックすることで、リポジトリが作成されます。オプションは好みでつけてください。私はREADME fileと、license（MIT）を指定するのが慣しです。.gitignoreについては、ここで自動作成するとかなり冗長な内容のファイルが作られますので、後で自分で作ることにします。

次にリポジトリの画面からdevelopブランチを新規作成します。

下の画面写真を参考に、Switch branches/tagsに新たなリポジトリ名developを入れて、Create branchをクリックすることで、developブランチが作成できます。

2020年のBLM運動の影響で、GitHubのデフォルトブランチ名がmasterからmainに変更されました。

3. ローカルリポジトリの作成とリモートリポジトリとの連携

GitHubと連携するためにgitコマンドをインストールします。gitは、最新バージョンにこだわらなければ、xcodeコマンドラインツールに含まれており、homebrew導入済であれば原理的に既にインストールされているはずです。which gitで確認しましょう。万一無ければbrew install gitでインストールしますが、使うためにはパスを通す必要があると思われます。

gitコマンドの初期設定を済ませておきます。

% git config --global user.name あなたのGitアカウント名
% git config --global user.email あなたのメールアドレス

VSCodeはGUIからインストールしておきます。VSCodeはバージョン更新が頻繁で、操作も頻繁に変更されます。

VSCodeを起動して、初期のようこそページでガイドされている「開始」で、リポジトリのクローン...を選択します。「GitHubから複製」を選択すると、なにやら複製のためのアプリ連携許可を与える画面を行き来し、結果として、自分のリポジトリ名の一覧が出ますので、先ほど作成したリポジトリ名を選択します。

新規作成フォルダの選択画面では、作りたいリポジトリの1つ上のフォルダを選択します。クローンしたリポジトリを開きます。

下の画面写真を参考に、画面左のソース管理アイコンをクリックし、画面左上のアイコンメニューから・・・をクリックして、チェックアウト先...を選択します。出できた一覧から、origin/developを選択することで、developブランチのローカルコピーが、カレントの編集状態になります。

以降、ローカルのリポジトリ名ディレクトリ直下を、「プロジェクトホーム」と呼びます。

4. venvでPython仮想環境を構築

仮想環境としてvenvをセットアップします。

Pythonの開発には、さまざまなライブラリをインストールする必要があり、環境がどんどん複雑になっていきます。さまざまな環境セットを併用したり、環境を壊してしまったなどの理由で再セットアップするといった場面が多く発生します。そのため、開発環境において、仮想環境のインストールは必須です。

仮想環境としては、初心者の方には、pyenvやanacondaなどは使わないことを強くお勧めします。pyenvは日本で良く使われ、ネット検索すると多くの利用例がヒットし、独学だとついつい使ってしまいま。しかし、利用例が多いのは、過去にPython公式の仮想環境の使い勝手が悪かった時代の名残りです。また、anacondaは、パッケージ追加インストール不要な簡易な利用を求めてのものですので、パッケージを柔軟に追加したい開発環境には、そもそも不向きです。現在は、資格試験やトレーニングコースなど、公式もしくは公式に近いコンテンツの多くが、Python公式のvenv対応になっています。そのため、まずvenvを使えるようになってから、好みによって他の仮想環境に切り替えるようにしましょう。

なお、上記の主張については、別に独立記事を作成しましたので、あわせてご参照ください。

プロジェクトホームで、python3.8 -m venv .venv とします。3.8とバージョン付きでvenvコマンドを実行することで、複数バージョンのPythonがインストールされていても、狙ったバージョンのpython仮想環境を作ることができます。.venvは他の名前でもよいですが、後で作成する.gitignoreの対象になるように .で始まる名前がよいです。venv環境には様々な共通ライブラリがインストールされますので、.gitignoreにヒットしないと、大変なことになります。

5. VSCodeのセットアップ

初期のようこそページでガイドされているカスタマイズで、Pythonサポートを有効にします。

次に先ほど作成したvenv環境を、VSCodeのデフォルトの実行環境にします。

ファイル-開く...でプロジェクトホームを開きます。次に、表示-コマンドパレット...でコマンドパレットの「Python:インタープリターを選択」から先ほど作成したvenv環境を選択します。ここで選択しておくと、VSCodeの様々なメニュー操作にあわせて、venvのactivateをVSCodeが自動でやってくれます。

VSCodeのターミナルメニューから新しいターミナルを選択し、venvが有効になったプロンプトが出でくるか確認してください。

VSCodeを立ち上げ直して、pythonファイル以外を選択したまま「新しいターミナル」を実行すると、Python環境であることが認識されずに、venvが有効になったプロンプトにならない場合があります。（VSCode1.52.1の挙動）

また、以下のように、ターミナルでpython -V、which python, pip -Vを実行して、pythonバージョンとpipバージョンが、venv環境のものになっているか、確認ください。

(.venv) プロジェクトホーム % python -V
Python 3.8.7
(.venv) プロジェクトホームe % which python
プロジェクトホーム/.venv/bin/python
(.venv) プロジェクトホーム % pip -V
pip 20.2.3 from プロジェクトホーム/.venv/lib/python3.8/site-packages/pip (python 3.8)

Pythonインストール直後のpipは最新版ではないことがありますので、適宜、venv環境下でpip install -U pipで最新化してください。最新化後にも、pip -Vを実行してpipがvenv環境のものになっているか、確認ください。

なお、ここまでの間に、Python関係の何かをインストールするように促されたら、指示に従ってください。

また、コマンドパレットのPython:Enable Linting on、Python:Select Linter で、flake8を選択しましょう。使っているうちにflake8をインストールするように促されますので、指示に従ってください。

6. .gitignoreによるコミット除外ファイルの設定

いろいろなツールのワークディレクトリやファイル、開発用のワークや、公開したくない情報（自分自身で取得したAPIキーなど）を、リモートリポジトリにPUSHしないようにします。そのためのしくみが、.gitignoreです。

VSCodeのGUIを使ってプロジェクトホームに.gitignoreファイルを作成します。中身は以下で十分で、個別に気になることがあれば追記してください。

.gitignore

.*
*cache*

設定した直後に、未コミット状態になっていた.venv配下の大量のシステムファイルやpython仮想環境の共通ライブラリなどが、グレーアウトされて未コミット扱いから除外されたことがわかります。

逆に上記の2つが無いと、大量のファイルがPUSHされてしまいますので、注意してください。

なお、この設定をすることで、.gitignore自身もコミットされません。既存の公開されているGitHubリポジトリにgitignoreが含まれていることは見かけませんので、.gitignoreはコミットしない方がよいでしょう。

7. リモートリポジトリへのPUSH操作の確認

テスト用に、プロジェクトホームにsample.pyファイルを作成します。なお、最後に改行のみの行を入れないと、flake8がエラーを吐きますので注意してください。（flake8、うるさいです・・・）

sample.py

print('Hello world')

左のソース管理のアイコンをクリックすると、以下のような画面が出ます。

緑のUが、新規ファイルを示します。+をクリックすると、変更がステージング状態になります。メッセージを入れて、その上のチェックマーク（コミットボタン）を押します。エラーなくステージング状態のファイルが無くなれば、ローカルリポジトリへのコミットが完了します。

さらに、・・・ボタンで出るメニューから「プッシュ」を選択します。初回は、VSCodeで以下の画面が出てきます。許可を押下し、出てくるWeb画面やVSCodeに素直に応対していくと、連携が完了します。

初回以降で認証有効期限が切れたあとは、同じ場面でキーチェーンのパスワードを聞いてきますので、Macのログインパスワードを入れます。エラーが出なければ、無事にリモートリポジトリへプッシュが完了です。

GitHubを見てみると、以下のように、リポジトリが更新されていることがわかります。

これで完成です。なお途中でうまくいかなくて回復不能になった場合は、いさぎよく、プロジェクトホーム以下を全て削除して、やりなおしてください。