From 82f4f587655deb7100a6fcec5c0c739866ea2fa9 Mon Sep 17 00:00:00 2001 From: Matt Martz Date: Tue, 29 Apr 2025 12:19:33 -0500 Subject: [PATCH 1/3] Fix a few examples in docs that are not 2.19 compatible --- .../complex_data_manipulation.rst | 38 ------------------- .../rst/playbook_guide/playbooks_async.rst | 4 +- 2 files changed, 2 insertions(+), 40 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/complex_data_manipulation.rst b/docs/docsite/rst/playbook_guide/complex_data_manipulation.rst index d311979b275..4b04329d134 100644 --- a/docs/docsite/rst/playbook_guide/complex_data_manipulation.rst +++ b/docs/docsite/rst/playbook_guide/complex_data_manipulation.rst @@ -127,44 +127,6 @@ In this case, we want to find the mount point for a given path across our machin msg: "{{(ansible_facts.mounts | selectattr('mount', 'in', path) | list | sort(attribute='mount'))[-1]['mount']}}" -.. _omit_elements_from_list: - -Omit elements from a list -------------------------- - -The special ``omit`` variable ONLY works with module options, but we can still use it in other ways as an identifier to tailor a list of elements: - -.. code-block:: YAML+Jinja - :caption: Inline list filtering when feeding a module option - :emphasize-lines: 3, 6 - - - name: Enable a list of Windows features, by name - ansible.builtin.set_fact: - win_feature_list: "{{ namestuff | reject('equalto', omit) | list }}" - vars: - namestuff: - - "{{ (fs_installed_smb_v1 | default(False)) | ternary(omit, 'FS-SMB1') }}" - - "foo" - - "bar" - - -Another way is to avoid adding elements to the list in the first place, so you can just use it directly: - -.. code-block:: YAML+Jinja - :caption: Using set_fact in a loop to increment a list conditionally - :emphasize-lines: 3, 4, 6 - - - name: Build unique list with some items conditionally omitted - ansible.builtin.set_fact: - namestuff: ' {{ (namestuff | default([])) | union([item]) }}' - when: item != omit - loop: - - "{{ (fs_installed_smb_v1 | default(False)) | ternary(omit, 'FS-SMB1') }}" - - "foo" - - "bar" - - - .. _combine_optional_values: Combine values from same list of dicts diff --git a/docs/docsite/rst/playbook_guide/playbooks_async.rst b/docs/docsite/rst/playbook_guide/playbooks_async.rst index 17349feeb58..559fab2552d 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_async.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_async.rst @@ -122,7 +122,7 @@ If you need a synchronization point with an async task, you can register it to o async_status: jid: "{{ yum_sleeper.ansible_job_id }}" register: job_result - until: job_result.finished + until: job_result is finished retries: 100 delay: 10 @@ -174,7 +174,7 @@ To run multiple asynchronous tasks while limiting the number of tasks running co loop_control: loop_var: "async_result_item" register: async_poll_results - until: async_poll_results.finished + until: async_poll_results is finished retries: 30 .. seealso:: From 23364d5c787e111ca6e6b00742bf5d7e1e21e520 Mon Sep 17 00:00:00 2001 From: Matt Martz Date: Tue, 29 Apr 2025 12:23:01 -0500 Subject: [PATCH 2/3] remove finalize example of None -> empty string --- .../rst/playbook_guide/playbooks_filters.rst | 22 ---------------- docs/docsite/rst/reference_appendices/faq.rst | 26 ------------------- 2 files changed, 48 deletions(-) diff --git a/docs/docsite/rst/playbook_guide/playbooks_filters.rst b/docs/docsite/rst/playbook_guide/playbooks_filters.rst index 045e0c5bb4a..bf1445fa530 100644 --- a/docs/docsite/rst/playbook_guide/playbooks_filters.rst +++ b/docs/docsite/rst/playbook_guide/playbooks_filters.rst @@ -1850,28 +1850,6 @@ To search in a string or extract parts of a string with a regular expression, us {{ '21/42' | regex_search('(?P[0-9]+)/(?P[0-9]+)', '\\g', '\\g') }} # => ['21', '42'] -The :ansplugin:`ansible.builtin.regex_search#filter` filter returns an empty string if it cannot find a match: - -.. code-block:: jinja - - {{ 'ansible' | regex_search('foobar') }} - # => '' - - -.. note:: - - - The :ansplugin:`ansible.builtin.regex_search#filter` filter returns ``None`` when used in a Jinja expression (for example in conjunction with operators, other filters, and so on). See the two examples below. - - .. code-block:: jinja - - {{ 'ansible' | regex_search('foobar') == '' }} - # => False - {{ 'ansible' | regex_search('foobar') is none }} - # => True - - This is due to historic behavior and the custom re-implementation of some of the Jinja internals in Ansible. Enable the ``jinja2_native`` setting if you want the :ansplugin:`ansible.builtin.regex_search#filter` filter to always return ``None`` if it cannot find a match. See :ref:`jinja2_faqs` for details. - To extract all occurrences of regex matches in a string, use the :ansplugin:`ansible.builtin.regex_findall#filter` filter: .. code-block:: jinja diff --git a/docs/docsite/rst/reference_appendices/faq.rst b/docs/docsite/rst/reference_appendices/faq.rst index 20ba50ca877..5161c2c7663 100644 --- a/docs/docsite/rst/reference_appendices/faq.rst +++ b/docs/docsite/rst/reference_appendices/faq.rst @@ -898,32 +898,6 @@ and backups, which most file based modules also support: state: absent when: updated is changed -.. _jinja2_faqs: - -Why does the ``regex_search`` filter return `None` instead of an empty string? -++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ - -Until the jinja2 2.10 release, Jinja was only able to return strings, but Ansible needed Python objects in some cases. Ansible uses ``safe_eval`` and only sends strings that look like certain types of Python objects through this function. With ``regex_search`` that does not find a match, the result (``None``) is converted to the string "None" which is not useful in non-native jinja2. - -The following example of a single templating action shows this behavior: - -.. code-block:: jinja - - {{ 'ansible' | regex_search('foobar') }} - -This example does not result in a Python ``None``, so Ansible historically converted it to "" (empty string). - -The native jinja2 functionality actually allows us to return full Python objects, that are always represented as Python objects everywhere, and as such the result of a single templating action with ``regex_search`` can result in the Python ``None``. - -.. note:: - - Native jinja2 functionality is not needed when ``regex_search`` is used as an intermediate result that is then compared to the jinja2 ``none`` test. - - .. code-block:: jinja - - {{ 'ansible' | regex_search('foobar') is none }} - - .. _docs_contributions: How do I submit a change to the documentation? From b821c1092b26ff5112c4cb312b8c89b13d439ebf Mon Sep 17 00:00:00 2001 From: Matt Martz Date: Tue, 29 Apr 2025 12:51:05 -0500 Subject: [PATCH 3/3] A few assert cleanups --- .../dev_guide/developing_resource_modules_network.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst b/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst index aca467a0597..6df724ac05d 100644 --- a/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst +++ b/docs/docsite/rst/network/dev_guide/developing_resource_modules_network.rst @@ -582,7 +582,7 @@ The following example walks through the integration tests for the ``vyos.vyos.vy - name: Assert that before dicts were correctly generated assert: that: - - "{{ populate | symmetric_difference(result['before']) | length == 0 }}" + - populate | symmetric_difference(result['before']) | length == 0 - name: Assert that correct commands were generated assert: that: @@ -594,8 +594,7 @@ The following example walks through the integration tests for the ``vyos.vyos.vy - name: Assert that after dicts were correctly generated assert: that: - - "{{ overridden['after'] | symmetric_difference(result['after']) - | length == 0 }}" + - overridden['after'] | symmetric_difference(result['after']) | length == 0 - name: Override device configuration with provided configuration (IDEMPOTENT) register: result vyos.vyos.vyos_l3_interfaces: @@ -614,8 +613,7 @@ The following example walks through the integration tests for the ``vyos.vyos.vy - name: Assert that before dicts were correctly generated assert: that: - - "{{ overridden['after'] | symmetric_difference(result['before']) - | length == 0 }}" + - overridden['after'] | symmetric_difference(result['before']) | length == 0 always: - import_tasks: _remove_config.yaml