Ansible：使用 CLI 列出 Jinja2 过滤器

Question

While developing with Ansible, I would like to be able to use the CLI entirely to lookup information without having to Google something every 5 minutes.

I often use the ansible-doc command to get information about built-in modules, Ansible keywords, etc. and ansible-config when I have to write an ansible.cfg file. Unfortunately, I cannot find anything related to Jinja2 filters.

Question

How can I get a list of all Jinja2 filters without relying solely on my memory in case I do not have access to a browser or I'm sitting a Red Hat exam?

Answer 1

I've long wished that ansible-doc had a -t filters option, too, but I think that's unlikely to happen since the filters are in a unique situation given that jinja2 itself has filters then ansible layers extra filters on top of the built-in jinja2 ones using its plugins mechanism. That story only gets worse with the new ansible-collections split

There are (at least) two work-arounds I can offer for the offline case:

1. the pydoc command
2. brute force find

using pydoc

You can identify the python interpreter that ansible, itself, is using via ansible --version and look for ansible python module location . While that path will point to the .../site-packages/ansible directory, it will still help know if ansible is in a virtualenv (as Brew does), in $HOME/.local , or against which system python version one should look

In these snippets, I'm going to be using just bare python , but in the actual case it would be the fully-qualified path to the python binary ansible uses

Then, enumerate the jinja2 filters via

python -m pydoc jinja2.filters

and the non-collection ansible filters by first getting the top-level package:

$ PAGER=cat python -m pydoc ansible.plugins.filter
Help on package ansible.plugins.filter in ansible.plugins:

NAME
    ansible.plugins.filter - # Make coding more python3-ish

PACKAGE CONTENTS
    core
    mathstuff
    urls
    urlsplit

and then iterate on the filter packages

for i in core mathstuff urls urlsplit; do
  python -m pydoc ansible.plugins.filter.$i
done

That technique will also print the actual python source code path at the bottom of the output, if you need to dig into the actual implementation detail for any nuance or memory-jog

I had some limited success using this trickery to find potential filter plugins out of the installed collections

ansible-galaxy collection list | \
    sed 's/^/ansible_collections./; s/  *[0-9].*/.plugins.filter/'

but obviously not all of those packages are correct or even exist

brute force using find

The newfound split into ansible-collections makes getting the whole list harder using that pydoc method, but they are still on-disk python files so you can use the path predicate to locate the ones which provide filter plugins:

for p in $(ansible --version | awk -F= '/ansible .* location/{gsub(":", "\n", $2); print $2}'); do
  find ${p}* -path '*/plugins/filter/*' -name '*.py' 2>/dev/null
done

which will serve as a memory jog, a place to read the source, and targets for using the aforementioned pydoc technique, if you prefer