ansible-collections/community.general
1
0
Fork 0
mirror of https://github.com/ansible-collections/community.general.git synced 2025-08-02 20:24:23 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions 10

Merge 3c165c8fc9 into 84b5d38c51

Browse source
This commit is contained in:
Felix Fontein 2025-07-30 00:20:01 -04:00 • committed by GitHub
commit e2c4bf1c1b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
18 changed files with 717 additions and 67 deletions
Download patch file Download diff file Expand all files Collapse all files

2
changelogs/fragments/10422-tasks_only-result_format.yml Normal file
View file

@ -0,0 +1,2 @@
minor_changes:
- "tasks_only callback plugin - add ``result_format`` and ``pretty_results`` options similarly to the default callback (https://github.com/ansible-collections/community.general/pull/10422)."

10
docs/docsite/config.yml
View file

@ -5,3 +5,13 @@
changelog:
write_changelog: true
ansible_output:
global_env:
ANSIBLE_STDOUT_CALLBACK: community.general.tasks_only
ANSIBLE_COLLECTIONS_TASKS_ONLY_NUMBER_OF_COLUMNS: 90
global_postprocessors:
reformat-yaml:
command:
- python
- docs/docsite/reformat-yaml.py

27
docs/docsite/reformat-yaml.py Normal file
View file

@ -0,0 +1,27 @@
#!/usr/bin/env python
# Copyright (c) Ansible Project
# GNU General Public License v3.0+ (see LICENSES/GPL-3.0-or-later.txt or https://www.gnu.org/licenses/gpl-3.0.txt)
# SPDX-License-Identifier: GPL-3.0-or-later
import sys
from io import StringIO
from ruamel.yaml import YAML
def main() -> None:
yaml = YAML(typ='rt')
yaml.indent(mapping=2, sequence=4, offset=2)
yaml.allow_duplicate_keys = True
# Load
data = yaml.load(sys.stdin)
# Dump
sio = StringIO()
yaml.dump(data, sio)
print(sio.getvalue().rstrip('\n'))
if __name__ == "__main__":
main()

81
docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-keep_keys.rst
View file

@ -13,6 +13,34 @@ Use the filter :ansplugin:`community.general.keep_keys#filter` if you have a lis
Let us use the below list in the following examples:
.. ansible-output-meta::
actions:
- name: reset-previous-blocks
- name: set-template
template:
env:
ANSIBLE_CALLBACK_RESULT_FORMAT: yaml
variables:
data:
previous_code_block: yaml
previous_code_block_index: 0
computation:
previous_code_block: yaml+jinja
postprocessors:
- name: reformat-yaml
language: yaml
skip_first_lines: 2
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
- vars:
@{{ data | indent(8) }}@
@{{ computation | indent(8) }}@
ansible.builtin.debug:
var: result
.. code-block:: yaml
input:
@ -37,24 +65,48 @@ Let us use the below list in the following examples:
gives
.. ansible-output-data::
playbook: ~
.. code-block:: yaml
:emphasize-lines: 1-
result:
- {k0_x0: A0, k1_x1: B0}
- {k0_x0: A1, k1_x1: B1}
- k0_x0: A0
k1_x1: B0
- k0_x0: A1
k1_x1: B1
.. versionadded:: 9.1.0
* The results of the below examples 1-5 are all the same:
.. ansible-output-data::
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
- vars:
@{{ data | indent(8) }}@
# I picked one of the examples
mp: equal
target: ['k0_x0', 'k1_x1']
result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}"
ansible.builtin.debug:
var: result
.. code-block:: yaml
:emphasize-lines: 1-
result:
- {k0_x0: A0, k1_x1: B0}
- {k0_x0: A1, k1_x1: B1}
- k0_x0: A0
k1_x1: B0
- k0_x0: A1
k1_x1: B1
1. Match keys that equal any of the items in the target.
@ -105,12 +157,28 @@ gives
* The results of the below examples 6-9 are all the same:
.. ansible-output-data::
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
- vars:
@{{ data | indent(8) }}@
# I picked one of the examples
mp: equal
target: k0_x0
result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}"
ansible.builtin.debug:
var: result
.. code-block:: yaml
:emphasize-lines: 1-
result:
- {k0_x0: A0}
- {k0_x0: A1}
- k0_x0: A0
- k0_x0: A1
6. Match keys that equal the target.
@ -148,4 +216,3 @@ gives
mp: regex
target: ^.*0_x.*$
result: "{{ input | community.general.keep_keys(target=target, matching_parameter=mp) }}"

83
docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-remove_keys.rst
View file

@ -13,6 +13,34 @@ Use the filter :ansplugin:`community.general.remove_keys#filter` if you have a l
Let us use the below list in the following examples:
.. ansible-output-meta::
actions:
- name: reset-previous-blocks
- name: set-template
template:
env:
ANSIBLE_CALLBACK_RESULT_FORMAT: yaml
variables:
data:
previous_code_block: yaml
previous_code_block_index: 0
computation:
previous_code_block: yaml+jinja
postprocessors:
- name: reformat-yaml
language: yaml
skip_first_lines: 2
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
- vars:
@{{ data | indent(8) }}@
@{{ computation | indent(8) }}@
ansible.builtin.debug:
var: result
.. code-block:: yaml
input:
@ -37,13 +65,19 @@ Let us use the below list in the following examples:
gives
.. ansible-output-data::
playbook: ~
.. code-block:: yaml
:emphasize-lines: 1-
result:
- k2_x2: [C0]
- k2_x2:
- C0
k3_x3: foo
- k2_x2: [C1]
- k2_x2:
- C1
k3_x3: bar
@ -51,13 +85,31 @@ gives
* The results of the below examples 1-5 are all the same:
.. ansible-output-data::
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
- vars:
@{{ data | indent(8) }}@
# I picked one of the examples
mp: equal
target: ['k0_x0', 'k1_x1']
result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}"
ansible.builtin.debug:
var: result
.. code-block:: yaml
:emphasize-lines: 1-
result:
- k2_x2: [C0]
- k2_x2:
- C0
k3_x3: foo
- k2_x2: [C1]
- k2_x2:
- C1
k3_x3: bar
@ -109,15 +161,33 @@ gives
* The results of the below examples 6-9 are all the same:
.. ansible-output-data::
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
- vars:
@{{ data | indent(8) }}@
# I picked one of the examples
mp: equal
target: k0_x0
result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}"
ansible.builtin.debug:
var: result
.. code-block:: yaml
:emphasize-lines: 1-
result:
- k1_x1: B0
k2_x2: [C0]
k2_x2:
- C0
k3_x3: foo
- k1_x1: B1
k2_x2: [C1]
k2_x2:
- C1
k3_x3: bar
@ -156,4 +226,3 @@ gives
mp: regex
target: ^.*0_x.*$
result: "{{ input | community.general.remove_keys(target=target, matching_parameter=mp) }}"

102
docs/docsite/rst/filter_guide-abstract_informations-lists_of_dictionaries-replace_keys.rst
View file

@ -13,6 +13,34 @@ Use the filter :ansplugin:`community.general.replace_keys#filter` if you have a
Let us use the below list in the following examples:
.. ansible-output-meta::
actions:
- name: reset-previous-blocks
- name: set-template
template:
env:
ANSIBLE_CALLBACK_RESULT_FORMAT: yaml
variables:
data:
previous_code_block: yaml
previous_code_block_index: 0
computation:
previous_code_block: yaml+jinja
postprocessors:
- name: reformat-yaml
language: yaml
skip_first_lines: 2
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
- vars:
@{{ data | indent(8) }}@
@{{ computation | indent(8) }}@
ansible.builtin.debug:
var: result
.. code-block:: yaml
input:
@ -40,17 +68,23 @@ Let us use the below list in the following examples:
gives
.. ansible-output-data::
playbook: ~
.. code-block:: yaml
:emphasize-lines: 1-
result:
- a0: A0
a1: B0
k2_x2: [C0]
k2_x2:
- C0
k3_x3: foo
- a0: A1
a1: B1
k2_x2: [C1]
k2_x2:
- C1
k3_x3: bar
@ -58,17 +92,37 @@ gives
* The results of the below examples 1-3 are all the same:
.. ansible-output-data::
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
- vars:
@{{ data | indent(8) }}@
# I picked one of the examples
mp: starts_with
target:
- {after: a0, before: k0}
- {after: a1, before: k1}
result: "{{ input | community.general.replace_keys(target=target, matching_parameter=mp) }}"
ansible.builtin.debug:
var: result
.. code-block:: yaml
:emphasize-lines: 1-
result:
- a0: A0
a1: B0
k2_x2: [C0]
k2_x2:
- C0
k3_x3: foo
- a0: A1
a1: B1
k2_x2: [C1]
k2_x2:
- C1
k3_x3: bar
@ -111,12 +165,29 @@ gives
* The results of the below examples 4-5 are the same:
.. ansible-output-data::
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
- vars:
@{{ data | indent(8) }}@
# I picked one of the examples
mp: regex
target:
- {after: X, before: ^.*_x.*$}
result: "{{ input | community.general.replace_keys(target=target, matching_parameter=mp) }}"
ansible.builtin.debug:
var: result
.. code-block:: yaml
:emphasize-lines: 1-
result:
- {X: foo}
- {X: bar}
- X: foo
- X: bar
4. If more keys match the same attribute before the last one will be used.
@ -145,6 +216,11 @@ gives
6. If there are more matches for a key the first one will be used.
.. ansible-output-meta::
actions:
- name: reset-previous-blocks
.. code-block:: yaml
:emphasize-lines: 1-
@ -165,11 +241,17 @@ gives
gives
.. ansible-output-data::
playbook: ~
.. code-block:: yaml
:emphasize-lines: 1-
result:
- {X: A, bbb1: B, ccc1: C}
- {X: D, bbb2: E, ccc2: F}
- X: A
bbb1: B
ccc1: C
- X: D
bbb2: E
ccc2: F

24
docs/docsite/rst/filter_guide_abstract_informations_counting_elements_in_sequence.rst
View file

@ -20,6 +20,17 @@ The :ansplugin:`community.general.counter filter plugin <community.general.count
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Count character occurrences in a string] ********************************************
@ -72,9 +83,20 @@ This plugin is useful for selecting resources based on current allocation:
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Get ID of SCSI controller(s) with less than 4 disks attached and choose the one with the least disks]
TASK [Get ID of SCSI controller(s) with less than 4 disks attached and choose the one with the least disks] ***
ok: [localhost] => {
"msg": "scsi_2"
}

32
docs/docsite/rst/filter_guide_abstract_informations_dictionaries.rst
View file

@ -31,16 +31,27 @@ You can use the :ansplugin:`community.general.dict_kv filter <community.general.
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Create a single-entry dictionary] **************************************************
TASK [Create a single-entry dictionary] ***************************************************
ok: [localhost] => {
"msg": {
"thatsmyvar": "myvalue"
}
}
TASK [Create a list of dictionaries where the 'server' field is taken from a list] *******
TASK [Create a list of dictionaries where the 'server' field is taken from a list] ********
ok: [localhost] => {
"msg": [
{
@ -87,9 +98,20 @@ If you need to convert a list of key-value pairs to a dictionary, you can use th
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Create a dictionary with the dict function] ****************************************
TASK [Create a dictionary with the dict function] *****************************************
ok: [localhost] => {
"msg": {
"1": 2,
@ -97,7 +119,7 @@ This produces:
}
}
TASK [Create a dictionary with the community.general.dict filter] ************************
TASK [Create a dictionary with the community.general.dict filter] *************************
ok: [localhost] => {
"msg": {
"1": 2,
@ -105,7 +127,7 @@ This produces:
}
}
TASK [Create a list of dictionaries with map and the community.general.dict filter] ******
TASK [Create a list of dictionaries with map and the community.general.dict filter] *******
ok: [localhost] => {
"msg": [
{

45
docs/docsite/rst/filter_guide_abstract_informations_grouping.rst
View file

@ -22,6 +22,49 @@ One example is ``ansible_facts.mounts``, which is a list of dictionaries where e
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
skip_first_lines: 3 # the set_fact task
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
- ansible.builtin.set_fact:
ansible_facts:
mounts:
- block_available: 2000
block_size: 4096
block_total: 2345
block_used: 345
device: "/dev/sda1"
fstype: "ext4"
inode_available: 500
inode_total: 512
inode_used: 12
mount: "/boot"
options: "rw,relatime,data=ordered"
size_available: 56821
size_total: 543210
uuid: "ab31cade-d9c1-484d-8482-8a4cbee5241a"
- block_available: 1234
block_size: 4096
block_total: 12345
block_used: 11111
device: "/dev/sda2"
fstype: "ext4"
inode_available: 1111
inode_total: 1234
inode_used: 123
mount: "/"
options: "rw,relatime"
size_available: 42143
size_total: 543210
uuid: "abcdef01-2345-6789-0abc-def012345678"
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Output mount facts grouped by device name] ******************************************
@ -79,7 +122,7 @@ This produces:
"options": "rw,relatime",
"size_available": 42143,
"size_total": 543210,
"uuid": "bdf50b7d-4859-40af-8665-c637ee7a7808"
"uuid": "abcdef01-2345-6789-0abc-def012345678"
},
"/boot": {
"block_available": 2000,

61
docs/docsite/rst/filter_guide_abstract_informations_lists_helper.rst
View file

@ -21,6 +21,34 @@ These filters preserve the item order, eliminate duplicates and are an extended
Let us use the lists below in the following examples:
.. ansible-output-meta::
actions:
- name: reset-previous-blocks
- name: set-template
template:
env:
ANSIBLE_CALLBACK_RESULT_FORMAT: yaml
variables:
data:
previous_code_block: yaml
previous_code_block_index: 0
computation:
previous_code_block: yaml+jinja
postprocessors:
- name: reformat-yaml
language: yaml
skip_first_lines: 2
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
- vars:
@{{ data | indent(8) }}@
@{{ computation | indent(8) }}@
ansible.builtin.debug:
var: result
.. code-block:: yaml
A: [9, 5, 7, 1, 9, 4, 10, 5, 9, 7]
@ -35,9 +63,22 @@ The union of ``A`` and ``B`` can be written as:
This statement produces:
.. ansible-output-data::
playbook: ~
.. code-block:: yaml
result: [9, 5, 7, 1, 4, 10, 2, 8, 3]
result:
- 9
- 5
- 7
- 1
- 4
- 10
- 2
- 8
- 3
If you want to calculate the intersection of ``A``, ``B`` and ``C``, you can use the following statement:
@ -59,9 +100,14 @@ or
All three statements are equivalent and give:
.. ansible-output-data::
playbook: ~
.. code-block:: yaml
result: [1]
result:
- 1
.. note:: Be aware that in most cases, filter calls without any argument require ``flatten=true``, otherwise the input is returned as result. The reason for this is, that the input is considered as a variable argument and is wrapped by an additional outer list. ``flatten=true`` ensures that this list is removed before the input is processed by the filter logic.
@ -75,7 +121,14 @@ For example, the symmetric difference of ``A``, ``B`` and ``C`` may be written a
This gives:
.. ansible-output-data::
playbook: ~
.. code-block:: yaml
result: [5, 8, 3, 1]
result:
- 5
- 8
- 3
- 1

176
docs/docsite/rst/filter_guide_abstract_informations_merging_lists_of_dictionaries.rst
View file

@ -12,6 +12,34 @@ If you have two or more lists of dictionaries and want to combine them into a li
Let us use the lists below in the following examples:
.. ansible-output-meta::
actions:
- name: reset-previous-blocks
- name: set-template
template:
env:
ANSIBLE_CALLBACK_RESULT_FORMAT: yaml
variables:
data:
previous_code_block: yaml
previous_code_block_index: 0
computation:
previous_code_block: yaml+jinja
postprocessors:
- name: reformat-yaml
language: yaml
skip_first_lines: 2
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
- vars:
@{{ data | indent(8) }}@
@{{ computation | indent(8) }}@
ansible.builtin.debug:
var: list3
.. code-block:: yaml
list1:
@ -34,13 +62,22 @@ In the example below the lists are merged by the attribute ``name``:
This produces:
.. ansible-output-data::
playbook: ~
.. code-block:: yaml
list3:
- {name: bar, extra: false}
- {name: baz, path: /baz}
- {name: foo, extra: true, path: /foo}
- {name: meh, extra: true}
- extra: false
name: bar
- name: baz
path: /baz
- extra: true
name: foo
path: /foo
- extra: true
name: meh
.. versionadded:: 2.0.0
@ -56,13 +93,22 @@ It is possible to use a list of lists as an input of the filter:
This produces the same result as in the previous example:
.. ansible-output-data::
playbook: ~
.. code-block:: yaml
list3:
- {name: bar, extra: false}
- {name: baz, path: /baz}
- {name: foo, extra: true, path: /foo}
- {name: meh, extra: true}
- extra: false
name: bar
- name: baz
path: /baz
- extra: true
name: foo
path: /foo
- extra: true
name: meh
Single list
"""""""""""
@ -75,13 +121,22 @@ It is possible to merge single list:
This produces the same result as in the previous example:
.. ansible-output-data::
playbook: ~
.. code-block:: yaml
list3:
- {name: bar, extra: false}
- {name: baz, path: /baz}
- {name: foo, extra: true, path: /foo}
- {name: meh, extra: true}
- extra: false
name: bar
- name: baz
path: /baz
- extra: true
name: foo
path: /foo
- extra: true
name: meh
The filter also accepts two optional parameters: :ansopt:`community.general.lists_mergeby#filter:recursive` and :ansopt:`community.general.lists_mergeby#filter:list_merge`. This is available since community.general 4.4.0.
@ -96,6 +151,11 @@ The examples below set :ansopt:`community.general.lists_mergeby#filter:recursive
Let us use the lists below in the following examples
.. ansible-output-meta::
actions:
- name: reset-previous-blocks
.. code-block:: yaml
list1:
@ -128,17 +188,25 @@ Example :ansopt:`community.general.lists_mergeby#filter:list_merge=replace` (def
This produces:
.. ansible-output-data::
playbook: ~
.. code-block:: yaml
list3:
- name: myname01
param01:
list:
- patch_value
x: default_value
y: patch_value
list: [patch_value]
z: patch_value
- name: myname02
param01: [3, 4, 4]
param01:
- 3
- 4
- 4
list_merge=keep
"""""""""""""""
@ -153,17 +221,26 @@ Example :ansopt:`community.general.lists_mergeby#filter:list_merge=keep`:
This produces:
.. ansible-output-data::
playbook: ~
.. code-block:: yaml
list3:
- name: myname01
param01:
list:
- default_value
x: default_value
y: patch_value
list: [default_value]
z: patch_value
- name: myname02
param01: [1, 1, 2, 3]
param01:
- 1
- 1
- 2
- 3
list_merge=append
"""""""""""""""""
@ -178,17 +255,30 @@ Example :ansopt:`community.general.lists_mergeby#filter:list_merge=append`:
This produces:
.. ansible-output-data::
playbook: ~
.. code-block:: yaml
list3:
- name: myname01
param01:
list:
- default_value
- patch_value
x: default_value
y: patch_value
list: [default_value, patch_value]
z: patch_value
- name: myname02
param01: [1, 1, 2, 3, 3, 4, 4]
param01:
- 1
- 1
- 2
- 3
- 3
- 4
- 4
list_merge=prepend
""""""""""""""""""
@ -203,17 +293,30 @@ Example :ansopt:`community.general.lists_mergeby#filter:list_merge=prepend`:
This produces:
.. ansible-output-data::
playbook: ~
.. code-block:: yaml
list3:
- name: myname01
param01:
list:
- patch_value
- default_value
x: default_value
y: patch_value
list: [patch_value, default_value]
z: patch_value
- name: myname02
param01: [3, 4, 4, 1, 1, 2, 3]
param01:
- 3
- 4
- 4
- 1
- 1
- 2
- 3
list_merge=append_rp
""""""""""""""""""""
@ -228,17 +331,29 @@ Example :ansopt:`community.general.lists_mergeby#filter:list_merge=append_rp`:
This produces:
.. ansible-output-data::
playbook: ~
.. code-block:: yaml
list3:
- name: myname01
param01:
list:
- default_value
- patch_value
x: default_value
y: patch_value
list: [default_value, patch_value]
z: patch_value
- name: myname02
param01: [1, 1, 2, 3, 4, 4]
param01:
- 1
- 1
- 2
- 3
- 4
- 4
list_merge=prepend_rp
"""""""""""""""""""""
@ -253,15 +368,26 @@ Example :ansopt:`community.general.lists_mergeby#filter:list_merge=prepend_rp`:
This produces:
.. ansible-output-data::
playbook: ~
.. code-block:: yaml
list3:
- name: myname01
param01:
list:
- patch_value
- default_value
x: default_value
y: patch_value
list: [patch_value, default_value]
z: patch_value
- name: myname02
param01: [3, 4, 4, 1, 1, 2]
param01:
- 3
- 4
- 4
- 1
- 1
- 2

39
docs/docsite/rst/filter_guide_conversions.rst
View file

@ -24,6 +24,17 @@ Ansible offers the :ansplugin:`community.general.read_csv module <community.gene
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Parse CSV from string] **************************************************************
@ -69,6 +80,34 @@ Converting to JSON
This produces:
.. ansible-output-data::
skip_first_lines: 3
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
- ansible.builtin.set_fact:
result_stdout: |-
bin
boot
dev
etc
home
lib
proc
root
run
tmp
- name: Run 'ls' to list files in /
command: ls /
register: result
- name: Parse the ls output
debug:
msg: "{{ result_stdout | community.general.jc('ls') }}"
.. code-block:: ansible-output
TASK [Run 'ls' to list files in /] ********************************************************

31
docs/docsite/rst/filter_guide_creating_identifiers.rst
View file

@ -25,6 +25,17 @@ Hashids
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Create hashid] **********************************************************************
@ -66,16 +77,32 @@ You can use the :ansplugin:`community.general.random_mac filter <community.gener
This produces:
.. ansible-output-data::
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
- name: "Create a random MAC starting with ff:"
debug:
# We're using a seed here to avoid randomness in the output
msg: "{{ 'FF' | community.general.random_mac(seed='') }}"
- name: "Create a random MAC starting with 00:11:22:"
debug:
# We're using a seed here to avoid randomness in the output
msg: "{{ '00:11:22' | community.general.random_mac(seed='') }}"
.. code-block:: ansible-output
TASK [Create a random MAC starting with ff:] **********************************************
ok: [localhost] => {
"msg": "ff:69:d3:78:7f:b4"
"msg": "ff:84:f5:d1:59:20"
}
TASK [Create a random MAC starting with 00:11:22:] ****************************************
ok: [localhost] => {
"msg": "00:11:22:71:5d:3b"
"msg": "00:11:22:84:f5:d1"
}
You can also initialize the random number generator from a seed to create random-but-idempotent MAC addresses:

17
docs/docsite/rst/filter_guide_working_with_times.rst
View file

@ -69,21 +69,32 @@ Note that months and years are using a simplified representation: a month is 30
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Convert string to seconds] **********************************************************
ok: [localhost] => {
"msg": "109210.123"
"msg": 109210.123
}
TASK [Convert string to hours] ************************************************************
ok: [localhost] => {
"msg": "30.336145277778"
"msg": 30.336145277778
}
TASK [Convert string to years (using 365.25 days == 1 year)] ******************************
ok: [localhost] => {
"msg": "1.096851471595"
"msg": 1.096851471595
}
.. versionadded: 0.2.0

13
docs/docsite/rst/filter_guide_working_with_unicode.rst
View file

@ -21,9 +21,20 @@ You can use the :ansplugin:`community.general.unicode_normalize filter <communit
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Compare Unicode representations] ********************************************************
TASK [Compare Unicode representations] ****************************************************
ok: [localhost] => {
"msg": true
}

11
docs/docsite/rst/filter_guide_working_with_versions.rst
View file

@ -23,6 +23,17 @@ If you need to sort a list of version numbers, the Jinja ``sort`` filter is prob
This produces:
.. ansible-output-data::
variables:
task:
previous_code_block: yaml+jinja
playbook: |-
- hosts: localhost
gather_facts: false
tasks:
@{{ task | indent(4) }}@
.. code-block:: ansible-output
TASK [Sort list by version number] ********************************************************

21
noxfile.py
View file

@ -6,10 +6,14 @@
# dependencies = ["nox>=2025.02.09", "antsibull-nox"]
# ///
import os
import sys
import nox
# Whether the noxfile is running in CI:
IN_CI = os.environ.get("CI") == "true"
try:
import antsibull_nox
@ -32,6 +36,23 @@ def botmeta(session: nox.Session) -> None:
session.run("python", "tests/sanity/extra/botmeta.py")
@nox.session(name="ansible-output", default=False)
def ansible_output(session: nox.Session) -> None:
session.install(
"ansible-core",
"antsibull-docs",
# Needed libs for some code blocks:
"jc",
"hashids",
# Tools for post-processing
"ruamel.yaml", # used by docs/docsite/reformat-yaml.py
)
args = []
if IN_CI:
args.append("--check")
session.run("antsibull-docs", "ansible-output", *args, *session.posargs)
# Allow to run the noxfile with `python noxfile.py`, `pipx run noxfile.py`, or similar.
# Requires nox >= 2025.02.09
if __name__ == "__main__":

9
plugins/callback/tasks_only.py
View file

@ -17,7 +17,8 @@ description:
- Can be used to generate output for documentation examples.
For this, the O(number_of_columns) option should be set to an explicit value.
extends_documentation_fragment:
- default_callback
- ansible.builtin.default_callback
- ansible.builtin.result_format_callback
options:
number_of_columns:
description:
@ -25,6 +26,12 @@ options:
type: int
env:
- name: ANSIBLE_COLLECTIONS_TASKS_ONLY_NUMBER_OF_COLUMNS
result_format:
# Part of the ansible.builtin.result_format_callback doc fragment
version_added: 11.2.0
pretty_results:
# Part of the ansible.builtin.result_format_callback doc fragment
version_added: 11.2.0
"""
EXAMPLES = r"""