Extend boolean values section in playbooks_variables

[skilyazhnev]

Hello!

in continuation of this issue

#1279

[ansible-documentation-bot]

Thanks for your Ansible docs contribution! We talk about Ansible documentation on matrix at #docs:ansible.im and on libera IRC at #ansible-docs if you ever want to join us and chat about the docs! We meet there on Tuesdays (see the Ansible calendar) and welcome additions to our weekly agenda items - scroll down to find the upcoming agenda and add a comment to put something new on that agenda.

[oraNod]

LGTM. Thanks @skilyazhnev

[oraNod]

Some minor nits but the rest LGTM

[oraNod]

@ssbarnea and @bcoca Please take a minute to review the latest round of edits. The details seem good to me and I'd like to get them merged.

Thanks again for the docs contribution @skilyazhnev

[bcoca]

This is not really 'ansible native' but YAML that uses true and false and the rest of the list below, it would be 'more true' that True and False are the 'native' options as Ansible evaluation happens inside Python and those are the 'Python native booleans', this also depends on context as inside a {{ }} expression it is Jinja doing the evaluation, which is again using Python under the hood.

[bcoca]

the bool filter, while is it Jinja, it is an Ansible customization which approximates (but does not really match) the YAML booleans, the table below is incorrect as this is the actual code:

    if a is None or isinstance(a, bool):
        return a
    if isinstance(a, string_types):
        a = a.lower()
    if a in ('yes', 'on', '1', 'true', 1):
        return True
    return False

so it realy only converts 'matching True' and everything else is False

[bcoca]

though this is something I'm planning to fix so they are closer to YAML by default but can be 'pythonic' otherwise.

[brlin-tw]

Note that YAML 1.2 drops all of the non-upper/lowercase-variant-true-false boolean variants, we may want to discourage people from using deprecated alternative boolean value styles.

Spec

[bcoca]

brlin-tw not an issue until 2 things happen:

• pyyaml releases a 1.2 compatible version
• that version of pyyaml is widely adopted by OS/distributions

While the first will possibly happen soon, the second will take a long time, so we can defer the change until the first actually happens.

[oraNod]

@bcoca What about adding a note that discourages the alternative boolean value styles and clearly stating that they will be deprecated in future?

Is there anything else holding this PR up?

[bcoca]

| and clearly stating that they will be deprecated in future?

will they?

[oraNod]

| and clearly stating that they will be deprecated in future?

will they?

fair point. I reread your comment about pyyaml. what if we come up with some other phrasing to discourage the use of alternative boolean styles? I mean we do have a linter that already complains about anything other than true | false.

[bcoca]

The linter is expressing an opinion, it might not be the correct one for all contexts

[oraNod]

yeah, linters tend to be opinionated about things. I'm probably straying from the point, which is about using the | bool filter and values being interpretable as boolean. I don't want to be a pain about it.

@bcoca would it work to remove the Interpretable as boolean table and focus more on the code for the bool filter that you pointed out? my thinking was to give a brief description instead along the lines of:

"Using True and False for boolean values is generally a good choice because they are clear and unambiguous. These values are also likely to be more compatible across versions. Standardizing on True and False also makes code more consistent and aids maintainability. Additionally these values avoid the need to for Ansible to interpret various input types, which can lead to unexpected behavior in some cases such as logical expressions."

then we could show the example.

of course I could trim down the details about using True and False if that's a little too much.

thanks.

[oraNod]

Hi @skilyazhnev We've made some changes to the underlying readthedocs project for this repository. I'm going to close and re-open this issue to kick off a new PR preview build.

You might notice there will be two checks for readthedocs. One for docs/readthedocs.org:stage-ansible-core and another for docs/readthedocs.org:ansible-core.

The stage-ansible-core check is for the old project and will result in a 404. Please ignore that and use the ansible-core check only.

Thank you for your patience and understanding. Also thanks for your contribution to the Ansible documentation. If you have any questions or concerns, please do let us know either here, in the docs channel on Matrix, or in the Ansible forum. Cheers.