config: singular ANSIBLE_COLLECTIONS_PATH (#70007)

* config: singular ANSIBLE_COLLECTIONS_PATH Every other *_PATH setting in ansible is singular, and the traditional $PATH variable is also singular despite containing a list of directories. Let's be consistent both internally and with POSIX tradition. * update all ANSIBLE_COLLECTIONS_PATHS env references to be singular * deprecate plural ANSIBLE_COLLECTIONS_PATHS setting
4 years ago · 47d14a33bd
parent a114da80ee
commit 47d14a33bd
15 changed files with 46 additions and 29 deletions
--- a/changelogs/fragments/singular-collection-path.yml
+++ b/changelogs/fragments/singular-collection-path.yml
@ -0,0 +1,3 @@
+minor_changes:
+- config - accept singular version of ``collections_path`` ini setting and
+  ``ANSIBLE_COLLECTIONS_PATH`` environment variable setting
--- a/lib/ansible/config/base.yml
+++ b/lib/ansible/config/base.yml
@ -233,9 +233,23 @@ COLLECTIONS_PATHS:
  default: ~/.ansible/collections:/usr/share/ansible/collections
  type: pathspec
  env:
-  - {name: ANSIBLE_COLLECTIONS_PATHS}
+  - name: ANSIBLE_COLLECTIONS_PATHS
+    deprecated:
+      why: all PATH-type options are singular PATH
+      version: "2.14"
+      alternatives: the "ANSIBLE_COLLECTIONS_PATH" environment variable
+  - name: ANSIBLE_COLLECTIONS_PATH
+    version_added: '2.10'
  ini:
-  - {key: collections_paths, section: defaults}
+  - key: collections_paths
+    section: defaults
+    deprecated:
+      why: all path-type options are singular path
+      version: "2.14"
+      alternatives: the "collections_path" ini setting
+  - key: collections_path
+    section: defaults
+    version_added: '2.10'
 COLLECTIONS_ON_ANSIBLE_VERSION_MISMATCH:
  name: Defines behavior when loading a collection that does not support the current Ansible version
  description:
--- a/lib/ansible/executor/task_executor.py
+++ b/lib/ansible/executor/task_executor.py
@ -1092,7 +1092,7 @@ def start_connection(play_context, variables, task_uuid):
        # can.
        'ANSIBLE_BECOME_PLUGINS': become_loader.print_paths(),
        'ANSIBLE_CLICONF_PLUGINS': cliconf_loader.print_paths(),
-        'ANSIBLE_COLLECTIONS_PATHS': to_native(os.pathsep.join(AnsibleCollectionConfig.collection_paths)),
+        'ANSIBLE_COLLECTIONS_PATH': to_native(os.pathsep.join(AnsibleCollectionConfig.collection_paths)),
        'ANSIBLE_CONNECTION_PLUGINS': connection_loader.print_paths(),
        'ANSIBLE_HTTPAPI_PLUGINS': httpapi_loader.print_paths(),
        'ANSIBLE_NETCONF_PLUGINS': netconf_loader.print_paths(),
--- a/test/integration/targets/ansible-galaxy-collection/tasks/install.yml
+++ b/test/integration/targets/ansible-galaxy-collection/tasks/install.yml
@ -7,7 +7,7 @@
 - name: install simple collection with implicit path - {{ test_name }}
  command: ansible-galaxy collection install namespace1.name1 -s '{{ test_server }}' {{ galaxy_verbosity }}
  environment:
-    ANSIBLE_COLLECTIONS_PATHS: '{{ galaxy_dir }}/ansible_collections'
+    ANSIBLE_COLLECTIONS_PATH: '{{ galaxy_dir }}/ansible_collections'
  register: install_normal

 - name: get installed files of install simple collection with implicit path - {{ test_name }}
@ -34,7 +34,7 @@
 - name: install existing without --force - {{ test_name }}
  command: ansible-galaxy collection install namespace1.name1 -s '{{ test_server }}' {{ galaxy_verbosity }}
  environment:
-    ANSIBLE_COLLECTIONS_PATHS: '{{ galaxy_dir }}/ansible_collections'
+    ANSIBLE_COLLECTIONS_PATH: '{{ galaxy_dir }}/ansible_collections'
  register: install_existing_no_force

 - name: assert install existing without --force - {{ test_name }}
@ -98,7 +98,7 @@
  args:
    chdir: '{{ galaxy_dir }}/ansible_collections'
  environment:
-    ANSIBLE_COLLECTIONS_PATHS: '{{ galaxy_dir }}/ansible_collections'
+    ANSIBLE_COLLECTIONS_PATH: '{{ galaxy_dir }}/ansible_collections'
    ANSIBLE_CONFIG: '{{ galaxy_dir }}/ansible.cfg'
  register: install_multiple_with_dep

@ -140,7 +140,7 @@
  command: ansible-galaxy collection install '{{ galaxy_dir }}/namespace3.tar.gz' {{ galaxy_verbosity }}
  register: install_tarball
  environment:
-    ANSIBLE_COLLECTIONS_PATHS: '{{ galaxy_dir }}/ansible_collections'
+    ANSIBLE_COLLECTIONS_PATH: '{{ galaxy_dir }}/ansible_collections'

 - name: get result of install collection from a tarball - {{ test_name }}
  slurp:
@ -161,7 +161,7 @@
  register: fail_bad_tar
  failed_when: fail_bad_tar.rc != 1 and "Cannot extract tar entry '../../outside.sh' as it will be placed outside the collection directory" not in fail_bad_tar.stderr
  environment:
-    ANSIBLE_COLLECTIONS_PATHS: '{{ galaxy_dir }}/ansible_collections'
+    ANSIBLE_COLLECTIONS_PATH: '{{ galaxy_dir }}/ansible_collections'

 - name: get result of failed collection install - {{ test_name }}
  stat:
@ -177,7 +177,7 @@
  command: ansible-galaxy collection install '{{ test_server }}custom/collections/namespace4-name-1.0.0.tar.gz' {{ galaxy_verbosity }}
  register: install_uri
  environment:
-    ANSIBLE_COLLECTIONS_PATHS: '{{ galaxy_dir }}/ansible_collections'
+    ANSIBLE_COLLECTIONS_PATH: '{{ galaxy_dir }}/ansible_collections'

 - name: get result of install collection from a URI - {{ test_name }}
  slurp:
@ -201,7 +201,7 @@
  command: ansible-galaxy collection install namespace5.name -s '{{ test_server }}' {{ galaxy_verbosity }}
  register: install_empty_server_list
  environment:
-    ANSIBLE_COLLECTIONS_PATHS: '{{ galaxy_dir }}/ansible_collections'
+    ANSIBLE_COLLECTIONS_PATH: '{{ galaxy_dir }}/ansible_collections'
    ANSIBLE_GALAXY_SERVER_LIST: ''

 - name: get result of a collection with an empty server list - {{ test_name }}
@ -230,7 +230,7 @@
  command: ansible-galaxy collection install -r '{{ galaxy_dir }}/ansible_collections/requirements-with-role.yml' -s '{{ test_server }}' -vvv
  register: install_req_collection
  environment:
-    ANSIBLE_COLLECTIONS_PATHS: '{{ galaxy_dir }}/ansible_collections'
+    ANSIBLE_COLLECTIONS_PATH: '{{ galaxy_dir }}/ansible_collections'

 - name: get result of install collections only with requirements-with-roles.yml - {{ test_name }}
  slurp:
@ -263,7 +263,7 @@
  command: ansible-galaxy install -r '{{ galaxy_dir }}/ansible_collections/requirements.yaml' -s '{{ test_server }}'
  register: install_req
  environment:
-    ANSIBLE_COLLECTIONS_PATHS: '{{ galaxy_dir }}/ansible_collections'
+    ANSIBLE_COLLECTIONS_PATH: '{{ galaxy_dir }}/ansible_collections'

 - name: get result of install collections with ansible-galaxy install - {{ test_name }}
  slurp:
--- a/test/integration/targets/ansible-galaxy/runme.sh
+++ b/test/integration/targets/ansible-galaxy/runme.sh
@ -205,7 +205,7 @@ popd # ${galaxy_testdir}
 # https://github.com/ansible/ansible/issues/60167#issuecomment-585460706

 f_ansible_galaxy_status \
-    "list specific role not in the first path in ANSIBLE_ROLES_PATHS"
+    "list specific role not in the first path in ANSIBLE_ROLES_PATH"

 role_testdir=$(mktemp -d)
 pushd "${role_testdir}"
@ -352,7 +352,7 @@ ansible-galaxy collection install ansible_test-zoo-2.5.0.tar.gz -p ./local
 ansible-galaxy collection init "ansible_test.development"
 mv ./ansible_test/development "${galaxy_testdir}/local/ansible_collections/ansible_test/"

-export ANSIBLE_COLLECTIONS_PATHS=~/.ansible/collections:${galaxy_testdir}/local
+export ANSIBLE_COLLECTIONS_PATH=~/.ansible/collections:${galaxy_testdir}/local

 f_ansible_galaxy_status \
    "collection list all collections"
@ -413,7 +413,7 @@ f_ansible_galaxy_status \

    rmdir emptydir

-unset ANSIBLE_COLLECTIONS_PATHS
+unset ANSIBLE_COLLECTIONS_PATH

 ## end ansible-galaxy collection list

--- a/test/integration/targets/collections/runme.sh
+++ b/test/integration/targets/collections/runme.sh
@ -2,7 +2,7 @@

 set -eux

-export ANSIBLE_COLLECTIONS_PATHS=$PWD/collection_root_user:$PWD/collection_root_sys
+export ANSIBLE_COLLECTIONS_PATH=$PWD/collection_root_user:$PWD/collection_root_sys
 export ANSIBLE_GATHERING=explicit
 export ANSIBLE_GATHER_SUBSET=minimal
 export ANSIBLE_HOST_PATTERN_MISMATCH=error
@ -52,7 +52,7 @@ fi
 ansible-playbook inventory_test.yml -i a.statichost.yml -i redirected.statichost.yml "$@"

 # test adjacent with --playbook-dir
-export ANSIBLE_COLLECTIONS_PATHS=''
+export ANSIBLE_COLLECTIONS_PATH=''
 ANSIBLE_INVENTORY_ANY_UNPARSED_IS_FAILED=1 ansible-inventory --list --export --playbook-dir=. -v "$@"

 # use an inventory source with caching enabled
--- a/test/integration/targets/collections/vars_plugin_tests.sh
+++ b/test/integration/targets/collections/vars_plugin_tests.sh
@ -17,7 +17,7 @@ grep '"adj_var": "value"' out.txt

 # Test vars plugin in a collection path
 export ANSIBLE_VARS_ENABLED=testns.testcoll.custom_vars
-export ANSIBLE_COLLECTIONS_PATHS=$PWD/collection_root_user:$PWD/collection_root_sys
+export ANSIBLE_COLLECTIONS_PATH=$PWD/collection_root_user:$PWD/collection_root_sys

 ansible-inventory -i a.statichost.yml --list --playbook-dir=./ | tee out.txt

@ -46,7 +46,7 @@ grep -v '"whitelisted": true' out.txt

 # Test plugins in plugin paths that opt-in to require whitelisting
 unset ANSIBLE_VARS_ENABLED
-unset ANSIBLE_COLLECTIONS_PATHS
+unset ANSIBLE_COLLECTIONS_PATH

 ANSIBLE_VARS_ENABLED=vars_req_whitelist ansible-inventory -i a.statichost.yml --list --playbook-dir=./ | tee out.txt

--- a/test/integration/targets/collections_plugin_namespace/runme.sh
+++ b/test/integration/targets/collections_plugin_namespace/runme.sh
@ -2,4 +2,4 @@

 set -eux

-ANSIBLE_COLLECTIONS_PATHS="${PWD}/collection_root" ansible-playbook test.yml -i ../../inventory "$@"
+ANSIBLE_COLLECTIONS_PATH="${PWD}/collection_root" ansible-playbook test.yml -i ../../inventory "$@"
--- a/test/integration/targets/collections_relative_imports/runme.sh
+++ b/test/integration/targets/collections_relative_imports/runme.sh
@ -10,4 +10,4 @@ else

 fi

-ANSIBLE_COLLECTIONS_PATHS="${PWD}/collection_root" ansible-playbook "${TEST_PLAYBOOK}" -i "${INVENTORY_PATH}" "$@"
+ANSIBLE_COLLECTIONS_PATH="${PWD}/collection_root" ansible-playbook "${TEST_PLAYBOOK}" -i "${INVENTORY_PATH}" "$@"
--- a/test/integration/targets/collections_runtime_pythonpath/runme.sh
+++ b/test/integration/targets/collections_runtime_pythonpath/runme.sh
@ -51,7 +51,7 @@ ansible \
    PYTHONPATH/site-packages ===
 # This is done by injecting a module with the same FQCN
 # into another collection root.
-ANSIBLE_COLLECTIONS_PATHS="${PWD}/ansible-collection-python-dist-foo" \
+ANSIBLE_COLLECTIONS_PATH="${PWD}/ansible-collection-python-dist-foo" \
 PYTHONPATH="${PWD}/ansible-collection-python-dist-boo:$PYTHONPATH" \
 ansible \
    -m python.dist.boo \
--- a/test/lib/ansible_test/_data/pytest/plugins/ansible_pytest_collections.py
+++ b/test/lib/ansible_test/_data/pytest/plugins/ansible_pytest_collections.py
@ -6,7 +6,7 @@ import os
 import sys

 # set by ansible-test to a single directory, rather than a list of directories as supported by Ansible itself
-ANSIBLE_COLLECTIONS_PATH = os.path.join(os.environ['ANSIBLE_COLLECTIONS_PATHS'], 'ansible_collections')
+ANSIBLE_COLLECTIONS_PATH = os.path.join(os.environ['ANSIBLE_COLLECTIONS_PATH'], 'ansible_collections')


 def collection_pypkgpath(self):
--- a/test/lib/ansible_test/_data/sanity/import/importer.py
+++ b/test/lib/ansible_test/_data/sanity/import/importer.py
@ -25,7 +25,7 @@ def main():
    temp_path = os.environ['SANITY_TEMP_PATH'] + os.path.sep
    external_python = os.environ.get('SANITY_EXTERNAL_PYTHON') or sys.executable
    collection_full_name = os.environ.get('SANITY_COLLECTION_FULL_NAME')
-    collection_root = os.environ.get('ANSIBLE_COLLECTIONS_PATHS')
+    collection_root = os.environ.get('ANSIBLE_COLLECTIONS_PATH')

    try:
        # noinspection PyCompatibility
--- a/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/main.py
+++ b/test/lib/ansible_test/_data/sanity/validate-modules/validate_modules/main.py
@ -2251,7 +2251,7 @@ class PythonPackageValidator(Validator):


 def setup_collection_loader():
-    collections_paths = os.environ.get('ANSIBLE_COLLECTIONS_PATHS', '').split(os.pathsep)
+    collections_paths = os.environ.get('ANSIBLE_COLLECTIONS_PATH', '').split(os.pathsep)
    _AnsibleCollectionFinder(collections_paths)


@ -2290,7 +2290,7 @@ def run():
    parser.add_argument('--collection',
                        help='Specifies the path to the collection, when '
                             'validating files within a collection. Ensure '
-                             'that ANSIBLE_COLLECTIONS_PATHS is set so the '
+                             'that ANSIBLE_COLLECTIONS_PATH is set so the '
                             'contents of the collection can be located')
    parser.add_argument('--collection-version',
                        help='The collection\'s version number used to check '
--- a/test/lib/ansible_test/_internal/ansible_util.py
+++ b/test/lib/ansible_test/_internal/ansible_util.py
@ -107,7 +107,7 @@ def ansible_environment(args, color=True, ansible_config=None):

    if data_context().content.collection:
        env.update(dict(
-            ANSIBLE_COLLECTIONS_PATHS=data_context().content.collection.root,
+            ANSIBLE_COLLECTIONS_PATH=data_context().content.collection.root,
        ))

    if data_context().content.is_ansible:
@ -127,7 +127,7 @@ def configure_plugin_paths(args):  # type: (CommonConfig) -> t.Dict[str, str]
    collection_root = os.path.join(support_path, 'collections')

    env = dict(
-        ANSIBLE_COLLECTIONS_PATHS=collection_root,
+        ANSIBLE_COLLECTIONS_PATH=collection_root,
    )

    # provide private copies of plugins for integration tests
--- a/test/units/utils/collection_loader/test_collection_loader.py
+++ b/test/units/utils/collection_loader/test_collection_loader.py
@ -367,7 +367,7 @@ def test_import_from_collection(monkeypatch):

    # define the collection root before any ansible code has been loaded
    # otherwise config will have already been loaded and changing the environment will have no effect
-    monkeypatch.setenv('ANSIBLE_COLLECTIONS_PATHS', collection_root)
+    monkeypatch.setenv('ANSIBLE_COLLECTIONS_PATH', collection_root)

    finder = _AnsibleCollectionFinder(paths=[collection_root])
    reset_collections_loader_state(finder)