英文 |Command-line usage

出處 | nox 官方文件

譯者 | 豌豆花下貓@Python貓

Github地址：https://github.com/chinesehuazhou/nox_doc_cn

宣告：本翻譯基於CC BY-NC-SA 4.0授權協議，內容略有改動，轉載請保留原文出處，請勿用於商業或非法用途。

接上篇《Python 任務自動化工具：nox 的配置與 API》

呼叫方式

nox 通常是在命令列上被呼叫的：

nox

你還可以通過 Python 直譯器呼叫 nox：

python3 -m nox

列出可用的會話

列出所有可用的會話，包括引數化的會話：

nox -l
nox --list
nox --list-sessions
 

執行所有會話

你可以不帶任何引數地執行 nox 來執行每個會話：

nox

會話被執行的順序是它們在 noxfile 中出現的順序。

指定一個或多個會話

預設情況下，nox 將執行在 noxfile 中定義的所有會話。但是，你可以選擇使用--session、-s 或-e 執行特定的一組：

nox --session tests
nox -s lint tests
nox -e lint

你還可以使用NOXSESSION環境變數：

NOXSESSION=lint nox
NOXSESSION=lint,tests nox

nox 將按照指定的順序執行這些會話。

你還可以使用pytest-風格的關鍵字來過濾測試會話：

nox -k "not lint"
nox -k "tests and not lint"

指定引數化的會話

如果你有引數化的會話，例如：

@nox.parametrize('django', ['1.9', '2.0'])
def tests(session, django):
    ...

那麼執行nox --session tests，實際上將執行該會話的所有引數化版本。如果你要使用一組特定的引數化引數執行會話，則可以使用會話名稱來指定它們：

nox --session "tests(django='1.9')"
nox --session "tests(django='2.0')"

重用虛擬環境

預設情況下，nox 在每次執行時都會刪除並重新建立虛擬環境（virtualenv）。通常，對於大多數專案和持續整合環境而言，這都是很好的，因為pip的快取使得重新安裝相當快。但是，在某些情況下，在兩次執行之間重用虛擬環境是更有利的。使用-r或--reuse-existing-virtualenvs：

nox -r
nox --reuse-existing-virtualenvs

如果 noxfile 設定了nox.options.reuse_existing_virtualenvn，你可以在命令列使用--no-reuse-existing-virtualenvs 覆蓋 noxfile 的設定。

如果有會話失敗，則停止

預設情況下，即使一個會話失敗，nox 也將繼續執行所有會話。一旦第一個會話失敗，你可以使用--stop-on-first-error來使 nox 中止：

nox --stop-on-first-error

如果 noxfile 設定了nox.options.stop_on_first_error，你可以在命令列中使用--no-stop-on-first-error覆蓋 noxfile 的設定。

當缺失直譯器時令會話失敗

預設情況下，nox 將跳過找不到 Python 直譯器的會話。如果你希望 nox 將這些會話標記為失敗，你可以使用--error-on-missing-interpreters：

nox --error-on-missing-interpreters

如果 noxfile 設定了nox.options.error_on_missing_interpreters，你可以在命令列中使用--no-error-on-missing-interpreters覆蓋 noxfile 設定。

禁止外部程式

預設情況下，對於未在會話的虛擬環境中安裝的程式，nox 會發出警告，但最終會允許你執行它。如果 nox 在非顯式將external = True 傳遞給session.run 的情況下，還使用任意外部程式，則你可以使用--error-on-external-run來使它失敗：

nox --error-on-external-run

如果 noxfile 設定了nox.options.error_on_external_run，你可以在命令列中使用--no-error-on-external-run覆蓋 noxfile 設定。

指定其它配置檔案

如果由於某種原因你的 noxfile 沒有命名為 noxfile.py ，你可以使用--noxfile 或-f ：

nox --noxfile something.py
nox -f something.py

將虛擬環境儲存在其它目錄中

預設情況下，nox 將虛擬環境儲存在./.nox中，但是，你可以使用--envdir進行更改：

nox --envdir /tmp/envs

跳過除安裝命令外的所有內容

在很多情況下，僅需要 nox 執行安裝命令，例如準備環境作離線測試，或者重新建立用於測試的虛擬環境。你可以使用--install-only跳過 run 命令。

例如，給定這個 noxfile：

@nox.session
def tests(session):
    session.install("pytest")
    session.install(".")
    session.run("pytest")

執行：

nox --install-only

將同時執行兩個 install 命令，但跳過 run 命令：

nox > Running session tests
nox > Creating virtualenv using python3.7 in ./.nox/tests
nox > pip install pytest
nox > pip install .
nox > Skipping pytest run, as --install-only is set.
nox > Session tests was successful.

強制非互動行為

session.interactive可用於判斷 nox 是在互動式終端（例如一個實際的人在其計算機上執行它）還是在非互動式終端（例如一個連續整合系統）中執行。

@nox.session
def docs(session):
    ...

    if session.interactive:
        nox.run("sphinx-autobuild", ...)
    else:
        nox.run("sphinx-build", ...)

有時，需要強制 nox 將會話視為非互動式的。你可以使用--non-interactive引數來執行此操作：

nox --non-interactive

這會使得session.interactive始終返回 False 。

控制彩色輸出

預設情況下，如果你在互動式終端中使用，則 nox 將輸出彩色的日誌。但是，如果要將stderr重定向到檔案，或者不使用互動式終端，或者設定了環境變數NO_COLOR，則 nox 會以純文字格式輸出。

你可以使用--nocolor和--forcecolor標誌來手動控制 nox 的輸出。

例如，這將始終輸出彩色日誌：

nox --forcecolor

但是，這將永遠不會輸出彩色日誌：

nox --nocolor

控制命令的詳細程度

預設情況下，nox 僅顯示失敗的命令的輸出，當給命令傳遞了silent = False 時，沒有輸出。通過將--verbose傳遞給 nox，無論 silent 引數如何，都會顯示所有命令的所有輸出。

輸出機器可讀的報告

你可以通過指定--report以json格式輸出報告：

nox --report status.json

Windows

nox 臨時性支援在 Windows 上執行。但是，這取決於你的 Windows，Python 和虛擬環境的版本可能會出現問題。有關更多資訊，請參見以下內容：

• tox issue 260
• Python issue 24493
• Virtualenv issue 774

Windows 上的 Python 二進位制檔案可通過 Windows 的 Python 啟動器（py ）找到。例如，通過確定py -3.5 會呼叫哪個可執行檔案，以此來找到 Python 3.5 。如果一個測試需要使用特定的 Python 的 32 位版本，則應使用X.Y-32 作為版本。

從 tox 轉化

nox 具有將 tox.ini 檔案轉換為 noxfile.py 檔案的實驗性支援。它還不支援 tox 的所有功能，僅用於完成過度轉換的大部分機械工作，你可能仍需要對轉換後的 noxfile.py 作一些修改。

要使用轉換器，請在安裝 nox 時附上tox_to_nox：

pip install --upgrade nox[tox_to_nox]

然後，只需在 tox.ini 所在的目錄中執行tox-to-nox：

tox-to-nox

這將基於 tox.ini 中的環境建立一個 noxfile.py。一些注意事項：

• 生成環境 可以工作，但是會被轉換為單獨的環境。tox-to-nox不夠聰明，無法將其轉換為引數化的會話，但是手動提取通用配置以進行引數化應該很簡單。
  
• 由於 tox 解析其配置的方式，所有替換項 會在轉換時被引入。這意味著你需要用適當的變數替換 noxfile.py 中的靜態字串。
  
• 幾種不常用的 tox 選項尚未實現，但有可能實現。如果遇到你認為有用的功能，請提出功能請求（feature request）。

shell 補齊

將適當的命令新增到 shell 的配置檔案中，以便在啟動時執行。你可能需要重啟或重新登入，才能使自動補齊功能生效。

bash

eval "$(register-python-argcomplete nox)"

zsh

# To activate completions for zsh you need to have
# bashcompinit enabled in zsh:
autoload -U bashcompinit
bashcompinit

# Afterwards you can enable completion for nox:
eval "$(register-python-argcomplete nox)"

tcsh

eval `register-python-argcomplete --shell tcsh nox`

fish

register-python-argcomplete --shell fish nox | .

公眾號【Python貓】， 本號連載優質的系列文章，有喵星哲學貓系列、Python進階系列、好書推薦系列、技術寫作、優質英文推薦與翻譯等等，歡迎關注哦