Skip to content

Fix a few examples in docs that are not 2.19 compatible #2581

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: devel
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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:
Expand All @@ -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

Expand Down
38 changes: 0 additions & 38 deletions docs/docsite/rst/playbook_guide/complex_data_manipulation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
4 changes: 2 additions & 2 deletions docs/docsite/rst/playbook_guide/playbooks_async.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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::
Expand Down
22 changes: 0 additions & 22 deletions docs/docsite/rst/playbook_guide/playbooks_filters.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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<dividend>[0-9]+)/(?P<divisor>[0-9]+)', '\\g<dividend>', '\\g<divisor>') }}
# => ['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
Expand Down
26 changes: 0 additions & 26 deletions docs/docsite/rst/reference_appendices/faq.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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?
Expand Down