FilterArgumentError exception is not documented and not in the "jinja2" module

[andy-maier]

The documentation at https://jinja.palletsprojects.com/en/stable/ documents all public exceptions in the jinja2.exceptions module, except for FilterArgumentError.

When I ask Claude what exception should be returned from Jinja2 filters in case of invalid arguments, it refers to FilterArgumentError.

When I scan the filters provided by Jinja2 itself for what they return in case of invalid arguments, it is FilterArgumentError.

I do realize that there is an asymmetry between filter and test plugins w.r.t. this exception (i.e. there is no TestArgumentError), and Ansible has similar asymmetries between filters and tests.

However, I think from a pragmatic and compatibility perspective, FilterArgumentError should be treated as a first class citizen exception, and should be documented and made visible in the jinja2 top level module.

[davidism]

TemplateRuntimeError does seem to be documented: https://jinja.palletsprojects.com/en/stable/api/#jinja2.TemplateRuntimeError

[davidism]

I'm not clear how documenting FilterArgumentError will help, I can't see when you would meaningfully catch this and do something.

Since they are publicly available in jinja2.exceptions, they should also be documented.

Unless things are documented, they are not considered public. There are plenty of things that are importable, there's no such thing as truly private in Python.

[andy-maier]

@davidism Sorry for my confusion - TemplateRuntimeError is in fact documented. I updated my issue description accordingly, and did not notice that you had responded so quickly!

[andy-maier]

@davidism FilterArgumentError is raised by several filters provided by Jinja2 itself.

[davidism]

Right, but that's within the runtime of a template, where you can't catch errors. You could catch it around the render call, but to what end? Why does it need to be public. In general, I'm really reluctant to add more to the public API just for the sake of consistency. I might not have documented some of those other exceptions if I was writing it today.

[andy-maier]

My issue is not so much about catching it, but what I should raise in case of invalid arguments in a filter or test plugin.

[davidism]

Hmm, I guess I'd advise raising a TypeError like any other Python function that gets an invalid argument, or a ValueError if it's a valid argument but invalid value. I don't know why this exception exists without digging in more.

[andy-maier]

Ok, I see.

It is just that FilterArgumentError is used quite a bit out there:

• The jinja2-ansible-filters package imports jinja2.exceptions.FilterArgumentErrorand raises it in several of its filters.
• Jinja2 itself raises it in the following filters: dictsort, urlize, format, round, reverse, map, select, reject.

If you really want to stop its use, it should probably be deprecated.