Windows  で Poetry を使った Python 環境の構築方法。

Windows で Python の仮想環境を作るにあたり、悩みに悩んだ結果、 Poetry が最善じゃね？と思い、記事にまとめることにしました。

# 環境

- OS：Windows 11 Pro
- CPU：Intel Core i7-9750H
- メモリ：64GB
- GPU：NVIDIA GeForce RTX 2070 Max-Q

# セットアップ

まずは、 Python 環境などのセットアップをしていきます。
なお、この記事では、 PowerShell での操作を前提としています。

PowerShell については、ちょっと違う記事になりますが、下記が参考になるかもしれません。

https://qiita.com/IoriGunji/items/db2141884c107b458c89

> **補足**
> Python のバージョン管理は pyenv-win で行います。
> Python のパッケージ管理は Poetry で行います。

## 【pyenv-win】ディレクトリの作成

pyenv-win を保存するために %USERPROFILE% ディレクトリに移動し、「.pyenv」ディレクトリを作成します。

```powershell
mkdir $env:USERPROFILE\.pyenv
```

## 【pyenv-win】git clone

「%USERPROFILE%\.pyenv」ディレクトリをターミナルで開き、git clone を実行します。

> なお、Git のインストールについては、下記を参考にしてください。
> https://www.curict.com/item/60/60bfe0e.html

> 末尾のドット(.)は親フォルダを作らずに Clone することを意味します。

```PowerShell
cd $env:USERPROFILE\.pyenv; git clone https://github.com/pyenv-win/pyenv-win.git .
```

## 【Python】アプリ実行エイリアスの設定

Windows 11 では、 **アプリ実行エイリアス** が色々と邪魔をしてくるので、設定を変更します。

下記の手順で、アプリ実行エイリアスを開きます。
`スタート` > `設定` > `アプリ` > `アプリの詳細設定` > `アプリ実行エイリアス`

次のアプリをオフにします。	
- python.exe
- python3.exe

## 【pyenv-win】環境変数へ PYENV と PYENV_HOME の追加

pyenv-win を環境変数に追加します。

```PowerShell
[System.Environment]::SetEnvironmentVariable('PYENV',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
[System.Environment]::SetEnvironmentVariable('PYENV_HOME',$env:USERPROFILE + "\.pyenv\pyenv-win\","User")
```

## 【pyenv-win】環境変数へ Path の追加

pyenv-win を環境変数に追加します。

```PowerShell
[System.Environment]::SetEnvironmentVariable('path', $env:USERPROFILE + "\.pyenv\pyenv-win\bin;" + $env:USERPROFILE + "\.pyenv\pyenv-win\shims;" + [System.Environment]::GetEnvironmentVariable('path', "User"),"User")
```

## 【pyenv-win】pyenv のバージョン確認

動作確認も兼ねて、 pyenv のバージョンを確認します。

```PowerShell
pyenv --version
```

## ポリシーエラーが出る場合	

上記のコマンド実行時にポリシーエラーが出る場合は、 PowerShell を管理者権限で起動し、下記のコマンドを実行します。

```PowerShell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned	
```

## 【Python / pyenv-win】セット可能な Python のバージョン確認

利用可能な Python のバージョンを確認します。

```PowerShell
pyenv versions
```

## 【Python / pyenv-win】インストール可能な Python のバージョン確認
インストール可能な Python のバージョン一覧を確認します。
必要なバージョンの Python がインストールされていない場合のみ行います。

```PowerShell
pyenv install --list
```

## 【Python / pyenv-win】Python のインストール	

Python のインストールを行います。
上記のコマンドで出力された Python バージョンの中から必要なものを指定して、インストールしてください。

GUI が表示される場合は指示に従ってインストールを行ってください。
必要なバージョンの Python がインストールされていない場合のみ行います。

```PowerShell
pyenv install [バージョン]
```

## 【Python / pyenv-win】Pyenv の shims を再構成

Pyenv の shims を再構成します。

```PowerShell
pyenv rehash
```

## 【Python / pyenv-win】セット可能な Python のバージョン確認

利用可能な Python のバージョンを確認します。

```PowerShell
pyenv versions
```

## 【Python / pyenv-win】指定したバージョンの Python をセット	

Python のバージョン切り替えを行います。
Python のバージョンの切り替えが必要な場合のみ行います。	

```PowerShell
pyenv local [バージョン]
pyenv global [バージョン]
```

> **補足**
> local：現在のディレクトリに対してセット
> global：システム全体にセット

## 【Poetry】Poetry のインストール

Poetry のインストールを行います。
`%APPDATA%\pypoetry` ディレクトリ配下にインストールされます。	
うまくいかない場合は、コマンドプロンプトを管理者権限で起動し、再実行してください。

```PowerShell
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python -	
```

## 【Poetry】Poetry を環境変数に設定

`%APPDATA%\Python\Scripts` を環境変数 Path に追加します。

```PowerShell
[System.Environment]::SetEnvironmentVariable('path', $env:APPDATA + "\Python\Scripts;" + [System.Environment]::GetEnvironmentVariable('path', "User"),"User")
```

## 【Poetry】Poetry のバージョン確認

Poetry のバージョンを表示し、 Path が通っているかどうかを確認します。

```PowerShell
poetry --version
```

## 【Poetry】.venv 仮想環境ディレクトリをプロジェクト直下に変更

.venv 仮想環境ディレクトリをプロジェクト直下に変更します。
プロジェクト直下にしたくない場合は飛ばして頂いて大丈夫です。

```PowerShell
poetry config virtualenvs.in-project true
```

## 【Poetry】pyenv で指定したバージョンを Poetry で利用するように変更

pyenv で指定したバージョンの Python を Poetry で利用するように設定を変更します。

```PowerShell
poetry config virtualenvs.prefer-active-python true
```

以上でセットアップは完了です。

# 新規開発環境の構築

Poetry を用いた仮想環境を新規で作成します。

## プロジェクトの親ディレクトリを開く

プロジェクトを作成したい親ディレクトリへ移動します。

```PowerShell
cd [親ディレクトリ]
```

## Python のバージョンを指定

利用したい Python のバージョンを予め指定しておきます。

```PowerShell
pyenv versions
pyenv local [バージョン]	
```

> **補足**
> `poetry new` コマンドを実行する前に親ディレクトリで実行しておくのがポイントです。

## 仮想環境用のプロジェクトの作成

指定した [プロジェクト名] のディレクトリ内に仮想環境用のプロジェクトが構築されます。
上記で指定したバージョンまたは `Global` で設定されている Python のバージョンが記述された `pyproject.toml` が作成されます。

```PowerShell
poetry new [プロジェクト名]
```

## プロジェクトディレクトリを開く

作成されたプロジェクトディレクトリへ移動します。

```PowerShell
cd [プロジェクト名]
```

## Python のバージョンを指定

Poetry が利用する Python のバージョンを明示的に指定します。
本来不要ですが、この設定を行うことで .python-version ファイルが作成され、 Git で管理できるようになります。

```PowerShell
pyenv versions
pyenv local [バージョン]	
```

## .venv 仮想環境ディレクトリのパスを変更

.venv 仮想環境ディレクトリのパスをプロジェクト直下に変更します。
グローバルで設定している場合は、本来不要ですが、この設定を行うことで poetry.toml ファイルが作成され、 Git で管理できるようになります。

```PowerShell
poetry config virtualenvs.in-project true --local
```

## 仮想環境のセットアップ

仮想環境のセットアップを行います。
引数無しの場合、 ./.venv ディレクトリ配下に仮想環境のセットアップが行われます。

```PowerShell
poetry install
```

> **補足1**
> pyenv で指定したバージョンの Python 仮想環境が作成されない場合は、 `.venv` ディレクトリを削除し、`pyproject.toml` を開きます。
> ```pyproject.toml
> [tool.poetry.dependencies]
> python = "^3.xx"
> ```
> 上記のバージョンを利用したい Python のバージョンに合わせて修正してください。
> 上書き保存を行った後、改めて `poetry install` コマンドを実行してください。

> **補足2**
> 上記の方法でも指定したバージョンでの仮想環境が作られない場合は、一度、 `venv` コマンドで仮想環境を作った上で、 `poetry install` コマンドを実施してください。
> ```powershell
> python -m venv .venv 
> poetry install
> ```

## GitHub リポジトリの作成

GitHub の Web サイトで新しいリポジトリを作成し、作成されたリポジトリの URL をコピーしておきます。
※Git でのバージョン管理を行わない場合は、これ以降の手順は不要になります。

## Git リポジトリの作成

Git リポジトリの作成を行います。	

```PowerShell
git init
```

## GitHub リモートリポジトリの追加

GitHub 上のリモートリポジトリを追加します。

```PowerShell
git remote add origin [Github のリポジトリの URL]
```

## .gitignore ファイルの作成

仮想環境などを Git の追跡対象外にするために .gitignore ファイルを作成します。

```PowerShell
ni .gitignore
set-content .gitignore -Value '.venv/'
```

以上で、新規開発環境の構築は完了です。

# 既存環境から開発環境の構築

Poetry を用いて既存環境から仮想環境を作成します。
なお、既存の開発環境は Github に保存されているものとします。

## 親ディレクトリを開く	

プロジェクトを作成したい親ディレクトリへ移動します。	

```PowerShell
cd [親ディレクトリ]
```
	
## Github から Clone

Github から Clone します。

```PowerShell
git clone [Github のリポジトリの URL]	
```

## プロジェクトディレクトリを開く

作成されたプロジェクトディレクトリへ移動します。

```PowerShell
cd [project-name]
```

## Python のバージョンを指定

Poetry が利用する Python のバージョンを明示的に指定します。
グローバルで設定している場合は、本来不要ですが、この設定を行うことで .python-version ファイルが作成され、 Git で管理できるようになります。	
既に .python-version ファイルが存在している場合は不要です。	

```PowerShell
pyenv versions
pyenv local [バージョン]
```
	
## .venv 仮想環境ディレクトリのパスを変更

.venv 仮想環境ディレクトリのパスをプロジェクト直下に変更します。
グローバルで設定している場合は、本来不要ですが、この設定を行うことで poetry.toml ファイルが作成され、 Git で管理できるようになります。
既に poetry.toml ファイルが存在している場合は不要です。

```PowerShell
poetry config virtualenvs.in-project true --local	
```

## 仮想環境のセットアップ

仮想環境のセットアップを行います。
引数無しの場合、 ./.venv ディレクトリ配下に仮想環境のセットアップが行われます。

```PowerShell
poetry install
```

以上で既存環境からの環境構築は完了です。

# よく使うコマンド

環境構築後によく使うコマンドをまとめておきます。

## Python モジュールの追加

Python モジュールを追加するには `poetry add` コマンドを使用します。

```powershell
poetry add [モジュール名]
```

## Python の実行方法

Python コードを実行するには `poetry run` コマンドを使用します。

```powershell
poetry run python [Pythonスクリプトのパス]  
```
PyInstaller や pytest を利用する場合は下記のようにします。

```powershell
poetry run pyinstaller app.py
poetry run pytest test.py
```

また、 Shell に入って実行することもできます。

```powershell
poetry shell
```

なお、 Shell を終了するには `exit` コマンドを使用します。

```powershell
exit
```

# その他のコマンド

よく使うその他のコマンドを列挙します。

## Python のインストール

必要なバージョンの Python がインストールされていない場合などに利用します。
手順はセットアップと同様です。

### インストール可能な Python のバージョン確認

インストール可能な Python のバージョン一覧を確認します。

```PowerShell
pyenv install --list
```

### Python のインストール	

Python のインストールを行います。
上記のコマンドで出力された Python バージョンの中から必要なものを指定して、インストールしてください。

GUI が表示される場合は指示に従ってインストールを行ってください。

```PowerShell
pyenv install [バージョン]
```

### Pyenv の shims を再構成

Pyenv の shims を再構成します。

```PowerShell
pyenv rehash
```

## Python のバージョン切り替え

Python のバージョン切り替えを行います。
Python のバージョンの切り替えが必要な場合のみ行います。

### セット可能な Python のバージョン確認

```PowerShell
pyenv versions
```

### 指定したバージョンの Python をセット

```PowerShell
pyenv local [バージョン]
pyenv global [バージョン]
```

> **補足**
> local：現在のディレクトリに対してセット	
> global：システム全体にセット	

## 現在のディレクトリで有効な Python のバージョンの確認

現在のディレクトリで有効な Python のバージョンの確認が行えます。

```PowerShell
PS	pyenv version
```

## pyenv-win のバージョン確認

pyenv-win のバージョン確認方法です。

```PowerShell
pyenv --version
```

## pyenv-win のアップデート

pyenv-win のアップデート方法です。
pyenv-win ディレクトリに移動して、 git pull を実行します。

```PowerShell
cd $env:USERPROFILE\.pyenv\pyenv-win; git pull
```

## Poetry のバージョン確認

Poetry のバージョン確認方法です。

```PowerShell
poetry --version
```

## Poetry のアップデート

Poetry のアップデート方法です。

```PowerShell
poetry self update
```

## Poetry のアンインストール

Poetry のアンインストール方法です。

```PowerShell
(Invoke-WebRequest -Uri https://install.python-poetry.org -UseBasicParsing).Content | python - --uninstall
```

## requirements.txt のエクスポート

requirements.txt のエクスポート方法です。

```PowerShell
poetry export -f requirements.txt --output requirements.txt
```

## インストールされているモジュールの確認

インストールされているモジュールの確認方法です。

```PowerShell
poetry show
```

## Python モジュールの削除

仮想環境にインストールされているモジュールを削除する方法です。

```PowerShell
poetry remove [モジュール名]
```

## Poetry の設定の確認

Poetry の設定の確認方法です。

```PowerShell
poetry config --list
```

## 既存環境の Python バージョンを変更する方法

既存環境の Python のバージョン変更は下記の手順で実行できます。

1. 既存の仮想環境の `.venv` ディレクトリを削除する。
1. `pyenv local` コマンドを実行して、 Python のバージョンを指定する。
1. `pyproject.toml` を開き、 Python のバージョンを修正して、上書き保存します。
   ```pyproject.toml
   [tool.poetry.dependencies]
   python = "^3.xx"
   ```
1. `poetry install` コマンドを実行し、仮想環境の再構築を行います。
1. 環境に合わせて必要なモジュールを追加します。

# 参考文献

下記のサイトを参考にさせて頂きました。

https://python-poetry.org/docs/

https://qiita.com/radiol/items/7cf7d1366f76cab3dc3b

<!-- EOF -->