Add alias "allowlist_externals" to "whitelist_externals" (#1601)

Author: dajose

CONTRIBUTORS

@@ -26,6 +26,7 @@ Clark Boylan
 Cyril Roelandt
 Dane Hillard
 David Staheli
+David Diaz
 Ederag
 Eli Collins
 Eugene Yunak

docs/changelog/1491.deprecation.rst

@@ -0,0 +1 @@
+Add allowlist_externals alias to whitelist_externals (whitelist_externals is now deprecated). - by :user:`dajose`

docs/config.rst

@@ -325,15 +325,20 @@ Complete list of settings that you can put into ``testenv*`` sections:
 
     Don't set this option if your :conf:`install_command` does not use pip.
 
-.. conf:: whitelist_externals ^ MULTI-LINE-LIST
+.. conf:: allowlist_externals ^ MULTI-LINE-LIST
 
     Each line specifies a command name (in glob-style pattern format)
     which can be used in the ``commands`` section without triggering
     a "not installed in virtualenv" warning.  Example: if you use the
-    unix ``make`` for running tests you can list ``whitelist_externals=make``
-    or ``whitelist_externals=/usr/bin/make`` if you want more precision.
+    unix ``make`` for running tests you can list ``allowlist_externals=make``
+    or ``allowlist_externals=/usr/bin/make`` if you want more precision.
     If you don't want tox to issue a warning in any case, just use
-    ``whitelist_externals=*`` which will match all commands (not recommended).
+    ``allowlist_externals=*`` which will match all commands (not recommended).
+
+    .. note::
+
+        ``whitelist_externals`` has the same meaning and usage as ``allowlist_externals``
+        but it is now deprecated.
 
 .. conf:: changedir ^ PATH ^ {toxinidir}
 
@@ -461,7 +466,7 @@ Complete list of settings that you can put into ``testenv*`` sections:
         WARNING: test command found but not installed in testenv
             cmd: /path/to/parent/interpreter/bin/<some command>
             env: /foo/bar/.tox/python
-        Maybe you forgot to specify a dependency? See also the whitelist_externals envconfig setting.
+        Maybe you forgot to specify a dependency? See also the allowlist_externals envconfig setting.
 
 
 .. conf:: alwayscopy ^ true|false ^ false

docs/example/basic.rst

@@ -104,21 +104,21 @@ runs on you can set a platform regular expression like this:
 If the expression does not match against ``sys.platform``
 the test environment will be skipped.
 
-whitelisting non-virtualenv commands
+allowing non-virtualenv commands
 -----------------------------------------------
 
 .. versionadded:: 1.5
 
 Sometimes you may want to use tools not contained in your
 virtualenv such as ``make``, ``bash`` or others. To avoid
-warnings you can use the ``whitelist_externals`` testenv
+warnings you can use the ``allowlist_externals`` testenv
 configuration:
 
 .. code-block:: ini
 
     # content of tox.ini
     [testenv]
-    whitelist_externals = make
+    allowlist_externals = make
                           /bin/bash
 
 

docs/index.rst

@@ -119,7 +119,7 @@ tox will take care of environment isolation for you: it will strip away all oper
 environment variables not specified via :conf:`passenv`. Furthermore, it will also alter the
 ``PATH`` variable so that your commands resolve first and foremost within the current active
 tox environment. In general all executables in the path are available in ``commands``, but tox will
-emit a warning if it was not explicitly allowed via :conf:`whitelist_externals`.
+emit a warning if it was not explicitly allowed via :conf:`allowlist_externals`.
 
 Current features
 -------------------

src/tox/config/__init__.py

@@ -760,7 +760,11 @@ def passenv(testenv_config, value):
     )
 
     parser.add_testenv_attribute(
-        name="whitelist_externals",
+        name="whitelist_externals", type="line-list", help="DEPRECATED: use allowlist_externals",
+    )
+
+    parser.add_testenv_attribute(
+        name="allowlist_externals",
         type="line-list",
         help="each lines specifies a path or basename for which tox will not warn "
         "about it coming from outside the test environment.",

src/tox/venv.py

@@ -169,7 +169,7 @@ def getcommandpath(self, name, venv=True, cwd=None):
 
         - If it's a local path we will rewrite it as as a relative path.
         - If venv is True we will check if the command is coming from the venv
-          or is whitelisted to come from external.
+          or is allowed to come from external.
         """
         name = str(name)
         if os.path.isabs(name):
@@ -180,7 +180,7 @@ def getcommandpath(self, name, venv=True, cwd=None):
                 return str(path)
 
         if venv:
-            path = self._venv_lookup_and_check_external_whitelist(name)
+            path = self._venv_lookup_and_check_external_allowlist(name)
         else:
             path = self._normal_lookup(name)
 
@@ -191,7 +191,7 @@ def getcommandpath(self, name, venv=True, cwd=None):
 
         return str(path)  # will not be rewritten for reporting
 
-    def _venv_lookup_and_check_external_whitelist(self, name):
+    def _venv_lookup_and_check_external_allowlist(self, name):
         path = self._venv_lookup(name)
         if path is None:
             path = self._normal_lookup(name)
@@ -212,7 +212,7 @@ def _check_external_allowed_and_warn(self, path):
                 "  cmd: {}\n"
                 "  env: {}\n"
                 "Maybe you forgot to specify a dependency? "
-                "See also the whitelist_externals envconfig setting.\n\n"
+                "See also the allowlist_externals envconfig setting.\n\n"
                 "DEPRECATION WARNING: this will be an error in tox 4 and above!".format(
                     path, self.envconfig.envdir,
                 ),
@@ -223,7 +223,16 @@ def is_allowed_external(self, p):
         if tox.INFO.IS_WIN:
             tryadd += [os.path.normcase(x) for x in os.environ["PATHEXT"].split(os.pathsep)]
             p = py.path.local(os.path.normcase(str(p)))
-        for x in self.envconfig.whitelist_externals:
+
+        if self.envconfig.allowlist_externals and self.envconfig.whitelist_externals:
+            raise tox.exception.ConfigError(
+                "Either whitelist_externals or allowlist_externals might be specified, not both",
+            )
+
+        allowed_externals = (
+            self.envconfig.whitelist_externals or self.envconfig.allowlist_externals
+        )
+        for x in allowed_externals:
             for add in tryadd:
                 if p.fnmatch(x + add):
                     return True

tests/integration/test_parallel_interrupt.py

@@ -33,7 +33,7 @@ def test_parallel_interrupt(initproj, monkeypatch, capfd):
                     skip_install = True
                     commands = python -c "open('{{envname}}', 'w').write('done'); \
                     import time; time.sleep(100)"
-                    whitelist_externals = {}
+                    allowlist_externals = {}
 
                 """.format(
                 sys.executable,

tests/unit/config/test_config.py

@@ -999,25 +999,25 @@ def test_specific_command_overrides(self, newconfig):
         envconfig = config.envconfigs["py"]
         assert envconfig.commands == [["abc"]]
 
-    def test_whitelist_externals(self, newconfig):
+    def test_allowlist_externals(self, newconfig):
         config = newconfig(
             """
             [testenv]
-            whitelist_externals = xyz
+            allowlist_externals = xyz
             commands=xyz
             [testenv:x]
 
             [testenv:py]
-            whitelist_externals = xyz2
+            allowlist_externals = xyz2
             commands=abc
         """,
         )
         assert len(config.envconfigs) == 2
         envconfig = config.envconfigs["py"]
         assert envconfig.commands == [["abc"]]
-        assert envconfig.whitelist_externals == ["xyz2"]
+        assert envconfig.allowlist_externals == ["xyz2"]
         envconfig = config.envconfigs["x"]
-        assert envconfig.whitelist_externals == ["xyz"]
+        assert envconfig.allowlist_externals == ["xyz"]
 
     def test_changedir(self, newconfig):
         config = newconfig(

tests/unit/session/test_parallel.py

@@ -98,7 +98,7 @@ def test_parallel_error_report(cmd, initproj, monkeypatch, live):
             skip_install = true
             commands=python -c "import sys, os; sys.stderr.write(str(12345) + os.linesep);\
              raise SystemExit(17)"
-            whitelist_externals = {}
+            allowlist_externals = {}
         """.format(
                 sys.executable,
             ),
@@ -129,7 +129,7 @@ def test_parallel_deadlock(cmd, initproj, monkeypatch):
 skipsdist = true
 
 [testenv]
-whitelist_externals = {}
+allowlist_externals = {}
 commands =
     python -c '[print("hello world") for _ in range(5000)]'
 """.format(
@@ -148,7 +148,7 @@ def test_parallel_recreate(cmd, initproj, monkeypatch):
 skipsdist = true
 
 [testenv]
-whitelist_externals = {}
+allowlist_externals = {}
 commands =
     python -c '[print("hello world") for _ in range(1)]'
 """.format(
@@ -177,7 +177,7 @@ def test_parallel_show_output(cmd, initproj, monkeypatch):
 skipsdist = true
 
 [testenv]
-whitelist_externals = {}
+allowlist_externals = {}
 commands =
     python -c 'import sys; sys.stderr.write("stderr env"); sys.stdout.write("stdout env")'
 

tests/unit/test_venv.py

@@ -450,6 +450,41 @@ def test_install_command_whitelisted(newmocksession):
     assert venv.status == "commands failed"
 
 
+def test_install_command_allowlisted(newmocksession):
+    mocksession = newmocksession(
+        ["--recreate"],
+        """\
+        [testenv]
+        allowlist_externals = pytest
+                              xy*
+        commands=
+            pytest
+            xyz
+        """,
+    )
+    venv = mocksession.getvenv("python")
+    venv.test()
+    mocksession.report.expect("warning", "*test command found but not*", invert=True)
+    assert venv.status == "commands failed"
+
+
+def test_install_command_allowlisted_exclusive(newmocksession):
+    mocksession = newmocksession(
+        ["--recreate"],
+        """\
+        [testenv]
+        allowlist_externals = pytest
+        whitelist_externals = xy*
+        commands=
+            pytest
+            xyz
+        """,
+    )
+    venv = mocksession.getvenv("python")
+    with pytest.raises(tox.exception.ConfigError):
+        venv.test()
+
+
 def test_install_command_not_installed_bash(newmocksession):
     mocksession = newmocksession(
         ["--recreate"],

tests/unit/test_z_cmdline.py

@@ -821,7 +821,7 @@ def test_empty_activity_shown_verbose(initproj, cmd):
             [testenv]
             list_dependencies_command=echo
             commands={envpython} --version
-            whitelist_externals = echo
+            allowlist_externals = echo
     """,
         },
     )