Flask1.0.2系列（十七） 命令列介面
英文原文地址：http://flask.pocoo.org/docs/1.0/cli/
若有翻譯錯誤或者不盡人意之處，請指出，謝謝~
在你的虛擬環境中安裝Flask的時候會安裝flask指令碼——一個Click命令列介面。從終端執行，這個指令碼能夠訪問內建的、擴充套件的、以及應用程式定義的命令。--help選項能夠獲取更多關於任何命令和選項的資訊。
1. 檢測應用程式
flask命令是由Flask安裝的，而不是由你的應用程式安裝的；為了使用flask命名，你必須告訴它，哪裡能找到你的應用程式。FLASK_APP環境變數被用來指定如何載入應用程式。
Unix Bash（Linux，Mac等）：
$ export FLASK_APP=hello
$ flask run Windows CMD：
> set FLASK_APP=hello
> flask run Windows PowerShell：
> $env:FLASK_APP = "hello"
> flask run 雖然FLASK_APP支援多種選項來指定你的應用程式，但是大多數情況都是很簡單的。這裡列出典型的值：
(nothing)
wsgi.py檔案被匯入，將自動探測一個應用（app物件）。這提供了一種簡單的方法，可以從帶有額外引數的工廠建立一個應用（app）。
FLASK_APP=hello
名字被匯入，自動探測一個應用（app物件）或者工廠（create_app）。
——————————————————————————————————————
FLASK_APP有三個部分：一個可選路徑用於設定當前工作目錄，一個Python檔案或者點（.）匯入路徑，以及一個可選的例項或者工廠的變數名稱。如果名稱是一個工廠，它可以選擇性地在括號中跟上引數。下面的值演示了上述內容：
FLASK_APP=src/hello
設定當前工作目錄到src，然後匯入hello。
FLASK_APP=hello.web
匯入路徑hello.web。
FLASK_APP="hello:create_app('dev')"
在hello中的create_app工廠被呼叫，並且有一個字串型別的引數‘dev’。
如果FLASK_APP沒有被設定，命令會尋找一個叫做wsgi.py或者app.py的檔案，並且嘗試檢測一個應用程式例項或者工廠。
在給定的匯入中，命令會尋找一個叫做app或者application的應用程式例項，然後再尋找任何應用程式例項。如果沒有找到例項，命令會查詢一個叫做create_app或者make_app的工廠方法來返回一個例項。
當呼叫一個應用程式工廠，如果工廠攜帶一個叫做info的引數，然後ScriptInfo例項會作為一個關鍵字引數傳遞進來。如果括號跟隨工廠名稱，它們的內容將被解析為Python常量，並且作為引數傳遞給這個方法。這意味著，字串必須在引號內。
2. 執行開發伺服器
run命令會執行開發伺服器。大多數情況下，它代替了Flask.run()函式。
$ flask run
* Serving Flask app "hello"
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit) 警告：
在生產中不要使用這個命令來執行你的應用程式。僅在開發期間才會使用開發伺服器。開發伺服器是為了方便才提供的，因此它沒有被設計的安全、穩定以及有效率。
3. 開啟一個Shell
為了在你的應用程式中探測資料，你可以使用shell命令來開始一個互動式Python shell。一個應用程式上下文會被啟用，並且app例項也會被匯入。
$ flask shell
Python 3.6.2 (default, Jul 20 2017, 03:52:27)
[GCC 7.1.1 20170630] on linux
App: example
Instance: /home/user/Projects/hello/instance
>>> 使用shell_context_processor()來新增其他自動匯入。
4. 環境
（新增於版本1.0。）
Flask應用執行的環境是由FLASK_ENV環境變數設定的。如果沒有設定它，預設為production。其他認可的環境是development。Flask和擴充套件會根據環境來決定開啟某些行為。
如果env被設定為development，flask命令會開啟除錯模式，並且flask run會開啟互動式偵錯程式和過載器。
$ FLASK_ENV=development flask run
* Serving Flask app "hello"
* Environment: development
* Debug mode: on
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
* Restarting with inotify reloader
* Debugger is active!
* Debugger PIN: 223-456-9195. 除錯模式
當FLASK_ENV為development時，除錯模式被開啟。如果你希望單獨地控制除錯模式，使用FLASK_DEBUG可以辦到：設為1表示開啟除錯模式，0標識禁用它。
6. 從點環境（dotenv）載入環境變數
相比於在每次開啟一個新的終端時設定FLASK_APP，你可以使用Flask支援的點環境（dotenv）來自動設定環境變數。
如果python-dotenv已經安裝，執行flask命令會從檔案.env和.flaskenv中讀取定義好的值，並設定到環境變數。這可以避免當開啟新終端時不得不手動設定FLASK_APP的操作，並且使用環境變數來設定配置，類似於一些開發服務的工作方式。
在命令列設定的變數用於那些在.env中設定的變數，這些變數用於.flaskenv中設定的變數。.flaskenv應用於公共變數，如FLASK_APP，而.env不應提交到儲存庫，以便它可以設定私有變數。
從被你成為flask的目錄開始，向上掃描以定位檔案。假定在專案的最頂層目錄，當前工作目錄將被設定為檔案的位置。
檔案僅在flask命令或者呼叫run()時才會被載入。當在生產模式下執行時，如果你想要載入這些檔案，你應該手動呼叫load_dotenv()。
6.1 設定命令選項
Click被配置為從環境變數中載入命令選項的預設值。這個變數使用模式FLASK_COMMAND_OPTION。舉個栗子，為了設定執行命令的埠，替換flask run --port 8000的方式是：
export FLASK_RUN_PORT=8000
flask run
* Running on http://127.0.0.1:8000/ 這些都能被新增到.flaskenv檔案中，以便控制預設命令選項，就像是FLASK_APP的使用一樣。
6.2 禁用點環境（dotenv）
如果flask探測到了點環境（dotenv）檔案，但是python-dotenv並沒有被安裝，flask命令將顯示一條資訊。
flask run
* Tip: There are .env files present. Do "pip install python-dotenv" to use them. 你可以設定環境變數FLASK_SKIP_DOTENV來告訴Flask不要載入點環境檔案，即使python-dotenv已經安裝了。如果你想要手動載入它們，或者你使用了其他方法已經載入了它們，這個選項就很有幫助了。請記住，環境變數必須在app載入前設定，或者它的配置值沒有達到預期時才設定。
export FLASK_SKIP_DOTENV=1
flask run7. 從虛擬環境載入環境變數
如果你不想安裝dotenv，你依然可以設定環境變數：將它們設定到虛擬環境的activate指令碼的末尾。啟用虛擬環境，這些變數就會被設定。
Unix Bash，venv/bin/activate：
export FLASK_APP=helloWindows CMD，venv/Scripts/activate.bat：
set FLASK_APP=hello 使用dotenv的好處在於，.flaskenv能被提交到版本庫中，因此當專案被簽出時，專案也能自動地載入這些環境變數。
8. 自定義命令
使用Click可以實現flask命令。檢視這個專案的文件來獲取關於編寫命令的所有知識。
這個例子添加了帶有引數name的命令create_user：
import click
from flask import Flask
app = Flask(__name__)
@app.cli.command()
@click.argument('name')
def create_user(name):
...flask create_user admin 這個示例添加了同樣的命令，但是命令為user create，表示一個命令在一個命令組內。如果你想組織多種相關的命令，這是很有用的：
import click
from flask import Flask
from flask.cli import AppGroup
app = Flask(__name__)
user_cli = AppGroup('user')
@user_cli.command('create')
@click.argument('name')
def create_user(name):
...
app.cli.add_command(user_cli)flask user create demo 檢視Testing CLI Commands來複習一下如何測試你自定義的命名。
9. 應用程式上下文
通過Flask app的cli.command()裝飾器來新增命令，這個裝飾器在執行的時候會得到一個應用程式上下文，因此你的命令和擴充套件有權訪問app和它的配置。如果你通過Click的command()裝飾器建立一個命令，你可以使用with_appcontext()來獲取與Flask裝飾器相同的行為。
import click
from flask.cli import with_appcontext
@click.command
@with_appcontext
def do_work():
...
app.cli.add_command(do_work) 如果你確定一個命令不需要上下文，你可以禁用它：
@app.cli.command(with_appcontext=False)
def do_work():
...10. 外掛
Flask會自動地載入flask.commands入口點（entry point）指定的命令。對於想要在安裝時新增命令的擴充套件來說，這是很有用的。入口點被指定在setup.py檔案中：
from setuptools import setup
setup(
name='flask-my-extension',
...,
entry_points={
'flask.commands': [
'my-command=flask_my_extension.commands:cli'
],
},
) 在flask_my_extension/commands.py內部，你可以匯出一個Click物件：
import click
@click.command()
def cli():
... 一旦在你的Flask專案所在的相同的虛擬環境下安裝了這個包，你可以執行flask my-command來呼叫這個命令。
11. 自定義指令碼
當你使用應用程式工廠模式時，它能更加方便地定義你自己的Click指令碼。相較於使用FLASK_APP並且讓Flask載入你的應用程式，你可以建立你自己的Click物件，並且匯出它就像一個console script入口點（entry point）。
建立一個FlaskGroup例項，並且將其傳給工廠：
import click
from flask import Flask
from flask.cli import FlaskGroup
def create_app():
app = Flask('wiki')
# other setup
return app
@click.group(cls=FlaskGroup, create_app=create_app)
def cli():
"""Management script for the Wiki application.""" 在setup.py中定義入口點：
from setuptools import setup
setup(
name='flask-my-extension',
...,
entry_points={
'console_scripts': [
'wiki=wiki:cli'
],
},
) 在虛擬環境下，使用可編輯模式（editable mode）來安裝應用程式，然後這個自定義指令碼就是可用狀態的。
注意，你不需要設定FLASK_APP。
$ pip install -e .
$ wiki run 自定義指令碼中的錯誤：
當使用自定義指令碼時，如果你在你的模組級別程式碼引入一個錯誤，重新載入器將會失敗，因為它無法載入到進入點（entry point）。
flask命令，獨立於你的程式碼，不會有這些問題，因此大多數情況下這是推薦的方式。
12. PyCharm
在PyCharm2018.1版本中，Flask CLI特定並沒有完全整合到PyCharm中。我們不得不做一些微調以便它們能順利工作。這裡介紹的內容與其他IDE類似。
在PyCharm中，開啟你的專案，點選選單欄的Run，並且跳轉到Edit Configurations。你會看到類似於下圖的介面：
這裡有些選項需要修改。
點選+（Add New Configuration）按鈕，然後選擇Python。給這個配置一個漂亮的帶有描述性的名字，比如“Run Flask Server”。因為flask run命令的緣故，因此勾選上“Single instance only”，以便你在同一時間只能執行一次這個服務。
選擇在圖片標記A的下拉選單選擇Module name，並且輸入flask。
在圖片標記B的地方，Parameters欄位用來設定CLI命令的執行引數。在這裡我們使用run，用來執行開發伺服器。
你可以跳過下一步，如果你使用從dotenv載入環境變數的話。在圖片標記C的地方我們需要新增一個環境變數來確定我們的應用程式。點選瀏覽按鈕，新增一個條目，左邊輸入FLASK_APP，右邊輸入Python匯入或者檔案（這裡輸入hello）。
接下來我們需要在圖片標記D的地方設定工作目錄，這個工作目錄就是我們應用程式所在的資料夾。
如果你已經將你的專案作為包安裝在了虛擬環境中，你需要在圖片標記E的地方勾選上PYTHONPATH選項。這可以更精確地匹配到你在稍後會如何部署你的app。
點選Apply按鈕來儲存這個配置，或者OK來儲存並關閉這個窗體。在PyCharm主窗體選擇這個配置，並且點選play按鈕來執行這個服務。
現在，我們在PyCharm中已經有一個執行flask run命令的配置。我們可以複製這個配置，並且修改指令碼引數來執行不同的CLI命令，比如flask shell。