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

時間 2020-01-16

標籤 python 任務自動化工具 nox 配置 api 欄目 Python 简体版

原文原文鏈接

英文 | Configuration & APIhtml

出處 | nox 官方文檔python

譯者 | 豌豆花下貓@Python貓mysql

Github地址：https://github.com/chinesehua...git

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

接上篇《更好用的 Python 任務自動化工具：nox 官方教程》sql

Noxfile

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

定義會話

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

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

import nox

@nox.session
def tests(session):
    session.run('pytest')

會話描述

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

import nox

@nox.session
def tests(session):
    """Run the test suite."""
    session.run('pytest')

nox --list命令將顯示出:

$ nox --list
Available sessions:
* tests -> Run the test suite.

會話名稱

默認狀況下，Nox 使用被裝飾函數的名稱做爲會話的名稱。這對於絕大多數項目都很是有效，可是，若是須要，你也能夠使用 @nox.session 的 name 參數來自定義會話的名稱。例如:

import nox

@nox.session(name="custom-name")
def a_very_long_function_name(session):
    print("Hello!")

nox --list 命令將顯示：

$ nox --list
Available sessions:
* custom-name

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

$ nox --session "custom-name"
Hello!

配置會話的virtualenv

默認狀況下，Nox 在爲每一個會話建立一個新的 virtualenv 時，會使用 Nox 所用的同一個解釋器。若是你使用 Python 3.6 安裝了 nox，則 nox 將默認在全部會話中使用 Python 3.6。

經過給 @nox.session 指定 python 參數(或其別名 py)，你能夠告訴 nox 使用不一樣的 Python 解釋器/版本:

@nox.session(python='2.7')
def tests(session):
    pass

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

@nox.session(python=['2.7', '3.6'])
def tests(session):
    pass

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

@nox.session(python=['2.7', '3.6', 'pypy-6.0'])
def tests(session):
    pass

當準備你的會話時，Nox 將爲每一個解釋器建立單獨的會話。你能夠在運行 nox --list 的時候看到這些會話。例如這個 Noxfile:

@nox.session(python=['2.7', '3.5', '3.6', '3.7'])
def tests(session):
    pass

將產生這些會話:

* tests-2.7
* tests-3.5
* tests-3.6
* tests-3.7

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

若是你想徹底禁止建立 virtualenv，你能夠設置 python 參數爲 False:

@nox.session(python=False)
def tests(session):
    pass

最後，你還能夠指定每次都重用 virtualenv，而不是從新建立:

@nox.session(
    python=['2.7', '3.6'],
    reuse_venv=True)
def tests(session):
    pass

將參數傳入會話

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

@nox.session
def test(session):
    session.install('pytest')

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

    session.run('pytest', *test_files)

如今若是你運行:

nox

那麼 nox 將運行:

pytest test_a.py test_b.py

但若是你運行:

nox -- test_c.py

那麼 nox 將運行:

pytest test_c.py

參數化會話

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

@nox.session
@nox.parametrize('django', ['1.9', '2.0'])
def tests(session, django):
    session.install(f'django=={django}')
    session.run('pytest')

當你運行nox時，它會建立兩個不一樣的會話：

$ nox
nox > Running session tests(django='1.9')
nox > pip install django==1.9
...
nox > Running session tests(djano='2.0')
nox > pip install django==2.0

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，被參數化的參數使用。

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

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

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

* tests(database='postgres', django='1.9')
* tests(database='mysql', django='1.9')
* tests(database='postgres', django='2.0')
* tests(database='mysql', django='2.0')

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

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

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

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

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

@nox.session
@nox.parametrize('django', [
    nox.param('1.9', id='old'),
    nox.param('2.0', id='new'),
])
def tests(session, django):
    ...

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

* tests(old)
* tests(new)

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

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

@nox.session
@nox.parametrize(
    'django',
    ['1.9', '2.0'],
    ids=["old", "new"])
@nox.parametrize(
    'database',
    ['postgres', 'mysql'],
    ids=["psql", "mysql"])
def tests(session, django, database):
    ...

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

* tests(psql, old)
* tests(mysql, old)
* tests(psql, new)
* tests(mysql, new)

會話對象

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：

import nox

nox.options.envdir = ".cache"

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

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

import nox

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

...

如下的選項能夠在 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。