Opened 14 months ago

Last modified 11 months ago

#27106 assigned Cleanup/optimization

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

Reported by: Baptiste Mispelon Owned by: Burhan Khalid
Component: Documentation Version: 1.10
Severity: Normal Keywords:
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: no UI/UX: no

Description

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

Change History (7)

comment:1 Changed 14 months ago by Tim Graham

Triage Stage: UnreviewedAccepted

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.

comment:2 Changed 14 months ago by 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.

Last edited 14 months ago by Aymeric Augustin (previous) (diff)

comment:3 Changed 12 months ago by Burhan Khalid

Owner: changed from nobody to Burhan Khalid
Status: newassigned

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.

comment:4 Changed 12 months ago by Burhan Khalid

Has patch: set

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.

comment:5 Changed 12 months ago by felixxm

Patch needs improvement: set

comment:6 Changed 12 months ago by Burhan Khalid

Patch needs improvement: unset

comment:7 Changed 11 months ago by Tim Graham

Patch needs improvement: set
Note: See TracTickets for help on using tickets.
Back to Top