Document which template filters can be used in Python code (and how)

[Baptiste Mispelon]

The Django template language ships with a lot of filters. Usually they're implemented as Python functions and can be imported and used in your own code.

However this particular usage is not documented (take the example of the various truncate* filters [1]).

I think it would be useful to know:

1) Which template filters can be used as functions;
2) Where to import them from and how to use them;
3) If there are limitations/gotchas related to using them.

[1] ​https://docs.djangoproject.com/en/1.10/ref/templates/builtins/#truncatechars

[Tim Graham]

While I think I've imported from django.template.defaultfilters in some of my own projects, I'm not sure that promoting that pattern as a public API is a good idea. Some of the filters use functions from django.utils.*, e.g. the slugify filter uses django.utils.text.slugify. I don't mind linking to those utility functions from the template tag documentation.

[Aymeric Augustin]

Yes, generally speaking Django template filters should be thin wrappers around utility functions. This makes it easy to use the underlying plain function in Jinja2 templates.

[Burhan Khalid]

I'll work a PR for this, where I'll link to the relevant django.utils.* documentation for those filters that are pure wrappers for other functions.

[Burhan Khalid]

​https://github.com/django/django/pull/7519

There was some documentation missing for some of the utils functions, which I added to the relevant sections in order to ensure Sphinx internal references were linked correctly.

[Ryan Cheley]

Before I start working on this ticket I wanted to make sure that it was still needed / valid. I can pick up the work that was done previously and try to get it over the finish line.

[Natalia Bidart]

Baptiste, would you have some time to answer the latest question in comment:9?

[Baptiste Mispelon]

Replying to Ryan Cheley:

Before I start working on this ticket I wanted to make sure that it was still needed / valid. I can pick up the work that was done previously and try to get it over the finish line.

The truncatechars filter linked in the original ticket still doesn't document which utility function it uses under the hood. Based on that, I would say that the ticket is still valid.

Reading comment:1 and comment:2, it seems the direction of the ticket is to:

1) identify the utility functions that are used by the default template filters
2) make sure those utilities are documented (on their respective pages)
3) make sure the template filter documentation links to the corresponding utils documentation

[Ryan Cheley]

Replying to Baptiste Mispelon:

The truncatechars filter linked in the original ticket still doesn't document which utility function it uses under the hood. Based on that, I would say that the ticket is still valid.

Reading comment:1 and comment:2, it seems the direction of the ticket is to:

1) identify the utility functions that are used by the default template filters
2) make sure those utilities are documented (on their respective pages)
3) make sure the template filter documentation links to the corresponding utils documentation

For truncatechars would something like this be what is needed (it would need to be cleaned up to conform to the standards in the docs, but I just want to make sure I’m on the right track)

truncatechars when given a non-HTML string uses unicodedata.normalize documented here ​https://docs.python.org/3/library/unicodedata.html#unicodedata.normalize

truncatechars when given an HTML string uses HTMLParse from html.parser which is documented here ​https://docs.python.org/3/library/html.parser.html

[Ryan Cheley]

I'm documenting the work being done here so as to not generate too much noise in the notifications as i work through this ticket

​https://github.com/ryancheley/public-notes/issues/7