# 還在用 pip 嗎，試試 Poetry 吧！
**Poetry** 其實跟 **“pip”** 一樣 python 的套件管理系統之一，之於 MacOS 的 brew。

- Poetry 強大的地方在於文件管理，可以多面向的設定 configuration，比方說 decouple dev 的 環境 及 prod 的環境，或是 global 的環境。

- Poetry doc file 格式採用 .toml，可以把它想像成 .json 即可，透過 .toml 去設置、不同環境配置的 configuaration。

## 如何在專用開發使用 Poetry

### ① 必須先安裝 poetry

# curl install poetry (macOS)
$ curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
====start to install====
...
..
.

# check install success or not
$ poetry --version
Poetry version 1.1.4

# 將 poetry 加入環境變數才可以使用 cmd
$ export PATH=$PATH:$HOME/.poetry/bin

### ② 使用 poetry 建立新專案

$ poetry new [project name] (e.g. $ poetry new hello-world)
Created package hello_world in hello-world

=> this step will auto create a project.toml file
├── README.rst
├── hello_world
│   └── __init__.py
├── pyproject.toml
└── tests
    ├── __init__.py
    └── test_hello_world.py

### ③ 建立 python 虛擬環境

# if need to create a virtual environment(Optional)
$ touch poetry.toml

$ vi poetry.toml
# paste it in the .toml file (means to create a .venv in the dir)
[virtualenvs]
in-project = true

# cmd create a virtual env (will help to create a .venv dir)
$ touch poetry shell
Creating virtualenv hello-world in /Users/{user}/hello-world/.venv
Spawning shell within /Users/{user}/poetry-tutor/hello-world/.venv

# activate the virtual enviornment
$ source .venv/bin/activate
$ poetry install

### ④ 安裝 package

# poetry vs pip 
# poetry 在安裝套件時是使用 `poetry add` 指令安裝，相對於 `pip install`
$ poetry add requests
Package operations: 5 installs, 0 updates, 0 removals
  • Installing certifi (2020.12.5)
  • Installing chardet (4.0.0)
  • Installing idna (2.10)
  • Installing urllib3 (1.26.4)
  • Installing requests (2.25.1)

=> 此時會在 pyproject.toml 的 [tool.poetry.dependencies] 加入 requests
$ vi pyproject.toml
   1 [tool.poetry]
   2 name = "hello-world"
   3 version = "0.1.0"
   4 description = ""
   5 authors = ["mzuen <[e-mail]>"]
   6
   7 [tool.poetry.dependencies]
   8 python = "^3.9"
=> 9 requests = "^2.25.1" 

### ⑤ 安裝 dev 環境的 package

# 一開始有說到 poetry 相較於 pip 方便管理不同環境下的 packages
# 使用 --dev 參數來加入 packages
$ poetry add --dev mypy
=> 此時會在 pyproject.toml 的 [tool.poetry.dependencies] 加入 requests
$ vi pyproject.toml
   1 [tool.poetry]  
   2 name = "hello-world"
     ...
   11 [tool.poetry.dev-dependencies]
   12 pytest = "^5.2"
=> 13 mypy = "^0.3.2"

### ⑥ 安裝後的 poetry.lock file
poetry install 後，會出現一個檔案 poetry.lock。
檔案裡面記錄著 Python 專案需要的相依套件、版本以及 hash 等資訊
每次安裝或移除套件 poetry.lock **都會被更新**，可以將其 commit 進行版本控制。
=> 此階段已經完成了 python 環境的設置了

## 其他指令集

### » 快速安裝

# 不分環境，全部安裝
$ poetry install

# 只安裝 dev 環境 packages
$ poetrty install --dev

# 只安裝 production 環境 packages
$ poetry install --no-dev

### » 更新、移除套件

# update
$ poetry update [package_name]

# remove
$ poetry remove [package_name]

### » Configuration 設置檔

# 可以看到你的 poetry 設置哪些設定
$ poetry config --list
cache-dir = "/Users/{user}/Library/Caches/pypoetry"
experimental.new-installer = true
installer.parallel = true
virtualenvs.create = true
virtualenvs.in-project = true
virtualenvs.path = "{cache-dir}/virtualenvs"

### » Helper 小幫手
其實 poetry 的 help 寫得蠻清楚的，以上講的大部分都可以在裡面找到

$ poetry help
...
...

###### tags: `python3`