Update documentation of the combine filter

[sschmittsva]

SUMMARY

I've updated the documentation of the combine filter. Changes:

• add to the short description that two or more dictionaries can be combined
• clarify in the description the notion of old/new (used later in the documentation for list_merge)
• add that the input can be a list of dictionaries
• extend the examples

ISSUE TYPE

• Docs Pull Request

[webknjaz]

/azp run

[azure-pipelines]

Azure Pipelines successfully started running 1 pipeline(s).

[jborean93]

Can we keep the existing examples as one liners, you can use your more complex ones as static dict definitions just above the combine template itself.

[sschmittsva]

Can we keep the existing examples as one liners

Sure. I'll readd them.

you can use your more complex ones as static dict definitions just above the combine template itself.

Sorry, I don't understand what you mean?

[jborean93]

Sorry, I don't understand what you mean?

I was just trying to say that it's best to keep the actual dictionary definitions just above the combine example rather than put them all at the top before using the combine template.

[sschmittsva]

Sorry, I don't understand what you mean?

I was just trying to say that it's best to keep the actual dictionary definitions just above the combine example rather than put them all at the top before using the combine template.

Thanks. Please have a look again.

[bcoca]

keep the defs as on liners to make them readable with the examples

[azrdev]

@sschmittsva AIUI _input is always a single parameter, in which the function receives everything that's passed into the filter (i.e. before | combine(...)), so it only takes a single dict

[sschmittsva]

That's what the former documentation wants you to think :) But it allows to receive a list of dicts, cf.

ansible/lib/ansible/plugins/filter/core.py

Line 343 in afd45ac

# allow the user to do `[dict1, dict2, ...] | combine`

and the example list_combine_ab_bc_cd.

[bcoca]

it was never intended for the input to be a list of dictionaries, for a case like this i would use map/select/reject filters on top. I'm of a mind to 'fix' combine to follow the normal filter semantics.

[utoddl]

That 'fix' would push more work onto users. For example, you can currently do

# Example 1
[defaults_dict] | product(list_of_dicts) | map("combine")

With your suggested 'fix', users would need to do

# Example 2
list_of_dicts | map("combine", defaults_dict, reverse=true)

except that won't work because combine lacks the reverse parameter to cause the dicts to be combined right-to-left instead of the heretofore left-to-right order. (In fact, I stumbled across #82329 while researching issues in prep for proposing just such an RFE.)

With such a fix in place, I don't see how one would accomplish what "Example 1" does. Would it not be better to 'fix' other filters that can't currently work this way?

[bcoca]

its 1 to 100 and also many filters are implemented in other projects, I'm not going to jinja2 and every collection to modify them, its always simpler to fix the outlier.

[utoddl]

Also fair. I may have misunderstood how the 'fix' you're talking about would percolate up to users. I do want to "get it" though, particularly because I maintain some internal filters for our group, and I'd like to do things the Right Way™.

Thanks for your perspective. This discussion would be better held in the forum. See you there.

[sschmittsva]

Is there anything else you would like to have changed?

[samccann]

@bcoca can you take another look (esp #82329 (comment) to see if it's accurate).