to_paths

Collection Note

This module is part of the ansible.utils collection. To install the collection, use:

ansible-galaxy collection install ansible.utils

Added in version 1.0.0.

Synopsis

• Flatten a complex object into a dictionary of paths and values.
• Paths are dot delimited whenever possible.
• Brackets are used for list indices and keys that contain special characters.
• B(to_paths) is also available as a B(lookup plugin) for convenience.
• Using the parameters below- C(var|ansible.utils.to_paths(prepend, wantlist))

Parameters

Parameter	Defaults / Choices	Comments
prepend str		Prepend each path entry. Useful to add the initial I(var) name.
var raw required		The value of I(var) will be will be used. This option represents the value that is passed to the filter plugin in pipe format. For example C(config_data|ansible.utils.to_paths()), in this case C(config_data) represents this option.
wantlist bool		If set to C(True), the return value will always be a list.

Examples

#### Simple examples

- ansible.builtin.set_fact:
    a:
      b:
        c:
          d:
            - 0
            - 1
          e:
            - true
            - false

- ansible.builtin.set_fact:
    paths: "{{ a|ansible.utils.to_paths }}"

# TASK [ansible.builtin.set_fact] ********************************************
# ok: [nxos101] => changed=false
#   ansible_facts:
#     paths:
#       b.c.d[0]: 0
#       b.c.d[1]: 1
#       b.c.e[0]: True
#       b.c.e[1]: False

- name: Use prepend to add the initial variable name
  ansible.builtin.set_fact:
    paths: "{{ a|ansible.utils.to_paths(prepend='a') }}"

# TASK [Use prepend to add the initial variable name] **************************
# ok: [nxos101] => changed=false
#   ansible_facts:
#     paths:
#       a.b.c.d[0]: 0
#       a.b.c.d[1]: 1
#       a.b.c.e[0]: True
#       a.b.c.e[1]: False


#### Using a complex object

- name: Make an API call
  uri:
    url: "https://nxos101/restconf/data/openconfig-interfaces:interfaces"
    headers:
      accept: "application/yang.data+json"
    url_password: password
    url_username: admin
    validate_certs: false
  register: result
  delegate_to: localhost

- name: Flatten the complex object
  ansible.builtin.set_fact:
    paths: "{{ result.json|ansible.utils.to_paths }}"

# TASK [Flatten the complex object] ******************************************
# ok: [nxos101] => changed=false
#   ansible_facts:
#     paths:
#       interfaces.interface[0].config.enabled: 'true'
#       interfaces.interface[0].config.mtu: '1500'
#       interfaces.interface[0].config.name: eth1/71
#       interfaces.interface[0].config.type: ethernetCsmacd
#       interfaces.interface[0].ethernet.config['auto-negotiate']: 'true'
#       interfaces.interface[0].ethernet.state.counters['in-crc-errors']: '0'
#       interfaces.interface[0].ethernet.state.counters['in-fragment-frames']: '0'
#       interfaces.interface[0].ethernet.state.counters['in-jabber-frames']: '0'
#       interfaces.interface[0].ethernet.state.counters['in-mac-control-frames']: '0'
#       <...>

Authors

• Bradley Thornton (@cidrblock)