Python 任務自動化工具：nox 的配置與 API

英文 | Configuration & API

出處 | nox 官方文檔

譯者 | 豌豆花下貓@Python貓

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

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

接上篇《 》

Noxfile

Nox 默認在一個名為noxfile.py的文件中查找配置。在運行 nox 時，你可以使用 --noxfile參數指定其它的文件。

定義會話

格式：session(func=None, python=None, py=None, reuse_venv=None, name=None, venv_backend=None)，將被裝飾的函數指定為一個會話。

Nox 會話是通過被@nox.session裝飾的標準 Python 函數來配置的。例如:

<code>importnox

@nox.session
deftests(session): 

session.run('pytest')
/<code>

會話描述

你可以使用文檔字符串向會話中添加一個描述。第一行內容會在列出會話時顯示。例如:

<code>importnox

@nox.session
deftests(session):
"""Runthetestsuite."""
session.run('pytest')
/<code>

nox --list命令將顯示出:

<code>$nox--list
Availablesessions:
*tests->Runthetestsuite.
/<code>

會話名稱

默認情況下，Nox 使用被裝飾函數的名稱作為會話的名稱。這對於絕大多數項目都非常有效，但是，如果需要，你也可以使用 @nox.session 的 name 參數來自定義會話的名稱。例如:

<code>importnox

@nox.session(name="custom-name")
defa_very_long_function_name(session):
print("Hello!")
/<code>

nox --list 命令將顯示：

<code>$nox--list
Availablesessions:
*custom-name 

/<code>

你可以告訴 nox 使用自定義的名稱運行會話:

<code>$nox--session"custom-name"
Hello!
/<code>

配置會話的virtualenv

默認情況下，Nox 在為每個會話創建一個新的 virtualenv 時，會使用 Nox 所用的同一個解釋器。如果你使用 Python 3.6 安裝了 nox，則 nox 將默認在所有會話中使用 Python 3.6。

通過給 @nox.session 指定 python 參數(或其別名 py)，你可以告訴 nox 使用不同的 Python 解釋器/版本:

<code>@nox.session(python='2.7')
deftests(session):
pass
/<code>

你還可以告訴 Nox 使用多個 Python 解釋器運行你的會話。Nox 將為指定的每個解釋器創建一個單獨的 virtualenv 並運行會話。例如，下面的會話將運行兩次——一次使用 Python 2.7，一次使用 Python 3.6:

<code>@nox.session(python=['2.7','3.6'])
deftests(session):
pass
/<code>

當你提供一個版本號時，Nox 會自動添加 python 來確定可執行文件的名稱。但是，Nox 也可以接受完整的可執行名稱。如果你想使用 pypy 來測試，例如:

<code>@nox.session(python=['2.7','3.6','pypy-6.0'])
deftests(session):
pass
/<code>

當準備你的會話時，Nox 將為每個解釋器創建單獨的會話。你可以在運行 nox --list 的時候看到這些會話。例如這個 Noxfile:

<code>@nox.session(python=['2.7','3.5','3.6','3.7'])
deftests(session):
pass
/<code>

將產生這些會話:

<code>*tests-2.7
*tests-3.5
*tests-3.6
*tests-3.7
/<code>

注意，這個擴展發生在參數化之前，所以你仍然可以對多個解釋器的會話進行參數化。

如果你想完全禁止創建 virtualenv，你可以設置 python 參數為 False:

<code>@nox.session(python=False)
deftests(session):
pass
/<code>

最後，你還可以指定每次都重用 virtualenv，而不是重新創建:

<code>@nox.session(
python=['2.7','3.6'],
reuse_venv=True)
deftests(session):
pass
/<code> 

將參數傳入會話

通常往測試會話中傳遞參數是很有用的。下面是一個簡單示例，演示瞭如何使用參數對特定文件作測試：

<code>@nox.session
deftest(session):
session.install('pytest')

ifsession.posargs:
test_files=session.posargs
else:
test_files=['test_a.py','test_b.py']

session.run('pytest',*test_files)
/<code>

現在如果你運行:

<code>nox
/<code>

那麼 nox 將運行:

<code>pytesttest_a.pytest_b.py
/<code>

但如果你運行:

<code>nox--test_c.py
/<code>

那麼 nox 將運行:

<code>pytesttest_c.py
/<code>

參數化會話

會話的參數可以用nox.parametrize() 裝飾器來作參數化。下面是一個典型的參數化安裝 Django 版本的例子：

<code>@nox.session
@nox.parametrize('django',['1.9','2.0'])
deftests(session,django):
session.install(f'django=={django}')
session.run('pytest')
/<code>

當你運行nox時，它會創建兩個不同的會話：

<code>$nox
nox>Runningsessiontests(django='1.9')
nox>pipinstalldjango==1.9
...
nox>Runningsessiontests(djano='2.0')
nox>pipinstalldjango==2.0
/<code>

nox.parametrize() 的接口和用法故意跟pytest的參數化 相類似。

格式：parametrize(arg_names, arg_values_list, ids=None)

作用是參數化一個會話。

將 arg_values_list 列表賦給對應的 arg_names，為裝飾的會話函數添加新的調用。參數化在會話發現期間執行，每次調用都作為 nox 的單個會話出現。

參數：

• arg_names (Sequence[str])——一系列參數名稱
• arg_values_list (Sequence[Union[Any, Tuple]])——參數值列表決定了使用不同參數值調用會話的頻率。如果只指定了一個參數名，那麼這就是一個簡單的值列表，例如[1,2,3]。如果指定了 N 個參數名，這必須是一個 N 元組的列表，其中每個元素為其各自的參數名指定一個值，例如 [(1,'a'), (2,'b')]。
• ids (Sequence[str]) ——可選項，一系列測試 id，被參數化的參數使用。

你也可以堆疊裝飾器，令其產生組合了參數的會話，例如:

<code>@nox.session
@nox.parametrize('django',['1.9','2.0'])
@nox.parametrize('database',['postgres','mysql'])
deftests(session,django,database):
...
/<code>

如果運行nox —list，你將看到它生成了以下的會話集:

<code>*tests(database='postgres',django='1.9')
*tests(database='mysql',django='1.9')
*tests(database='postgres',django='2.0')
*tests(database='mysql',django='2.0')
/<code>

如果你只想運行一個參數化會話，請參閱"指定參數化會話"部分。

為參數化的會話起友好的名稱

自動生成的參數化會話的名稱，如tests(django='1.9', database='postgres')，即使用關鍵字過濾，也可能很長且很難處理。

在此場景中，可以為參數化會話提供輔助的自定義 id 。這兩個例子是等價的:

<code>@nox.session
@nox.parametrize('django', 

['1.9','2.0'],
ids=['old','new'])
deftests(session,django):
...
/<code>

<code>@nox.session
@nox.parametrize('django',[
nox.param('1.9',id='old'),
nox.param('2.0',id='new'),
])
deftests(session,django):
...
/<code>

當運行nox --list時，你將看到它們的新 id:

<code>*tests(old)
*tests(new)
/<code>

你可以用nox --sessions "tests(old)"，以此類推。

這也適用於堆疊參數化。id 是在組合期間組合的。例如:

<code>@nox.session
@nox.parametrize(
'django',
['1.9','2.0'],
ids=["old","new"])
@nox.parametrize(
'database',
['postgres','mysql'],
ids=["psql","mysql"])
deftests(session,django,database):
...
/<code>

運行nox --list時會產生這些會話:

<code>*tests(psql,old)
*tests(mysql,old)
*tests(psql,new)
*tests(mysql,new)
/<code> 

會話對象

Nox 將使用 Session 類的一個實例來調用你的會話函數。

class Session(runner) ¶

會話對象被傳遞到用戶自定義的每個會話函數中。

這是在 Nox 會話中安裝軟件包和運行命令的主要途徑。

• bin¶——virtualenv 的 bin 目錄
• cd(dir)¶——chdir() 的一個別名
• chdir(dir)¶——更改當前的工作目錄
• conda_install(*args, **kwargs)¶ 調用conda install來在會話環境中的安裝軟件包。 直接安裝軟件包: session.conda_install('pandas')
  session.conda_install('numpy', 'scipy')
  session.conda_install('--channel=conda-forge', 'dask==2.1.0')
  根據 requirements.txt 文件來安裝軟件包： session.conda_install('--file', 'requirements.txt')
  session.conda_install('--file', 'requirements-dev.txt')
  不破壞 conda 已安裝的依賴而安裝軟件包： session.install('.', '--no-deps')
  # Install in editable mode.
  session.install('-e', '.', '--no-deps')
  剩下的關鍵字參數跟 run() 相同。
• env¶——一個環境變量的字典，傳給所有的命令。
• error(*args, **kwargs)¶——立即中止會話並隨意地記錄一個錯誤。
• install(*args, **kwargs)¶ ——調用 pip 在會話的 virtualenv 裡安裝包。 直接安裝包： session.install('pytest')
  session.install('requests', 'mock')
  session.install('requests[security]==2.9.1')
  根據 requirements.txt 文件來安裝軟件包： session.install('-r', 'requirements.txt')
  session.install('-r', 'requirements-dev.txt')
  安裝當前的包： session.install('.')
  # Install in editable mode.
  session.install('-e', '.')
  剩下的關鍵字參數跟 run() 相同。
• interactive¶ ——如果 Nox 在交互式會話中運行，則返回 True，否則返回 False。
• log(*args, **kwargs)¶——在會話期間輸出一份日誌。
• notify(target)¶ ——將給定的會話放在隊列的末尾。 此方法是冪等的；對同一會話的多次通知無效。 參數：target (Union[str, Callable])——需要通知的會話。這可以指定適當的字符串(與nox -s 的使用相同)或使用函數對象。
• posargs¶ ——用於設置從命令行上傳給 nox 的額外參數。
• python¶ ——傳給@nox.session的 Python 版本。
• run(args, env=None, kwargs)¶ ——運行一個命令。 命令必須安裝字符串列表指定，例如： session.run('pytest', '-k', 'fast', 'tests/')
  session.run('flake8', '--import-order-style=google')
  你不能把所有東西都當作一個字符串傳遞。例如，不可以這樣： session.run('pytest -k fast tests/')
  你可以用env 為命令設置環境變量： session.run(
  
  'bash', '-c', 'echo $SOME_ENV',
  env={'SOME_ENV': 'Hello'})
  你還可以使用success_codes ，告訴 nox 將非零退出碼視為成功。例如，如果你想將 pytest 的“tests discovered, but none selected”錯誤視為成功： session.run(
  'pytest', '-k', 'not slow',
  success_codes=[0, 5])
  在 Windows 上，像del這樣的內置命令不能直接調用，但是你可以使用cmd /c 來調用它們： session.run('cmd', '/c', 'del', 'docs/modules.rst')
  參數：
• env (dict or None)——用於向命令公開的環境變量字典。默認情況下，傳遞所有環境變量。
• silent (bool) ——靜默命令輸出，除非命令失敗。默認為 False。
• success_codes (list, tuple, or None)——一系列被認為是成功的返回碼。默認情況下，只有 0 被認為是成功的。
• external (bool) ——如果為 False(默認值)，那麼不在 virtualenv 路徑中的程序將發出告警。如果為 True，則不會發出告警。這些告警可以使用--error-on-external-run將其轉換為錯誤。這對沒有 virtualenv 的會話沒有影響。
• skip(*args, **kwargs)¶ ——立即跳出會話，並隨意記錄一個告警。
• virtualenv¶ ——運行所有命令的 virtualenv。

修改 Noxfile 中的 Nox 行為

Nox 有各種命令行參數，可用於修改其行為。其中一些還可以在 Noxfile 中使用 nox.options 指定。例如，如果你想將 Nox 的 virtualenvs 存儲在不同的目錄中，而不需要每次都將它傳遞給 nox：

<code>importnox

nox.options.envdir=".cache"

@nox.session
deftests(session):
...
/<code>

或者，如果你想提供一組默認運行的會話：

<code>importnox

nox.options.sessions=["lint","tests-3.6"]

...
/<code>

以下的選項可以在 Noxfile 中指定：

• nox.options.envdir 等同於指定 –envdir.
• nox.options.sessions 等同於指定 -s or –sessions.
• nox.options.keywords 等同於指定 -k or –keywords.
• nox.options.reuse_existing_virtualenvs 等同於指定 –reuse-existing-virtualenvs 。通過在調用時指定 --no-reuse-existing-virtualenvs ，你可以強制取消它。
• nox.options.stop_on_first_error 等同於指定 –stop-on-first-error. 通過在調用時指定 --no-stop-on-first-error，你可以強制取消它。
• nox.options.error_on_missing_interpreters 等同於指定 –error-on-missing-interpreters 。通過在調用時指定 --no-error-on-missing-interpreters ，你可以強制取消它。
• nox.options.error_on_external_run 等同於指定 –error-on-external-run. 通過在調用時指定 --no-error-on-external-run ，你可以強制取消它。
• nox.options.report 等同於指定 –report。

在調用 nox 時，命令行上指定的任何選項都優先於 Noxfile 中指定的選項。如果在命令行上指定了--sessions或--keywords，那麼在 Noxfile 中指定的兩個選項都將被忽略。

主要分享 Python基礎、Python進階、Python哲學、編程語言、書籍推薦等內容，另外還有官方 PEP 翻譯與優質外文的翻譯，值得關注一同學習。

閱讀更多 Python貓 的文章

關鍵字: Python 指定 自動化