[Django] #27106: Document which template filters can be used in Python code (and how)

[Django]

#27106: Document which template filters can be used in Python code (and how)
------------------------------------------------+------------------------
Reporter: bmispelon | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.10
Severity: Normal | Keywords:
Triage Stage: Unreviewed | Has patch: 0
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 0 | Easy pickings: 0
UI/UX: 0 |
------------------------------------------------+------------------------
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

--
Ticket URL: <https://code.djangoproject.com/ticket/27106>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

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

--------------------------------------+------------------------------------

Reporter: bmispelon | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

--------------------------------------+------------------------------------
Changes (by timgraham):

* stage: Unreviewed => Accepted

Comment:

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.

--
Ticket URL: <https://code.djangoproject.com/ticket/27106#comment:1>

[Django]

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

--------------------------------------+------------------------------------

Reporter: bmispelon | Owner: nobody
Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

--------------------------------------+------------------------------------

Comment (by aaugustin):

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

--
Ticket URL: <https://code.djangoproject.com/ticket/27106#comment:2>

[Django]

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

-------------------------------------+-------------------------------------
Reporter: Baptiste Mispelon | Owner: Burhan
Type: | Khalid
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Burhan Khalid):

* owner: nobody => Burhan Khalid
* status: new => assigned

Comment:

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.

--
Ticket URL: <https://code.djangoproject.com/ticket/27106#comment:3>

[Django]

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

-------------------------------------+-------------------------------------
Reporter: Baptiste Mispelon | Owner: Burhan
Type: | Khalid
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Burhan Khalid):

* has_patch: 0 => 1

Comment:

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.

--
Ticket URL: <https://code.djangoproject.com/ticket/27106#comment:4>

[Django]

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

-------------------------------------+-------------------------------------
Reporter: Baptiste Mispelon | Owner: Burhan
Type: | Khalid
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by felixxm):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/27106#comment:5>

[Django]

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

-------------------------------------+-------------------------------------
Reporter: Baptiste Mispelon | Owner: Burhan
Type: | Khalid
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Burhan Khalid):

* needs_better_patch: 1 => 0

--
Ticket URL: <https://code.djangoproject.com/ticket/27106#comment:6>

[Django]

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

-------------------------------------+-------------------------------------
Reporter: Baptiste Mispelon | Owner: Burhan
Type: | Khalid
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Tim Graham):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/27106#comment:7>

[Django]

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

--------------------------------------+------------------------------------
Reporter: Baptiste Mispelon | Owner: (none)

Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0

--------------------------------------+------------------------------------
Changes (by Mariusz Felisiak):

* owner: Burhan Khalid => (none)
* status: assigned => new

--
Ticket URL: <https://code.djangoproject.com/ticket/27106#comment:8>

[Django]

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

-------------------------------------+-------------------------------------
Reporter: Baptiste Mispelon | Owner: Ryan
Type: | Cheley
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Ryan Cheley):

* owner: (none) => Ryan Cheley

* status: new => assigned

Comment:

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.
--
Ticket URL: <https://code.djangoproject.com/ticket/27106#comment:9>

[Django]

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

-------------------------------------+-------------------------------------
Reporter: Baptiste Mispelon | Owner: Ryan
Type: | Cheley
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Natalia Bidart):

* cc: Baptiste Mispelon (added)

Comment:

Baptiste, would you have some time to answer the latest question in
comment:9?
--
Ticket URL: <https://code.djangoproject.com/ticket/27106#comment:10>

[Django]

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

-------------------------------------+-------------------------------------
Reporter: Baptiste Mispelon | Owner: Ryan
Type: | Cheley
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Comment (by Baptiste Mispelon):

Replying to [comment:9 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
--
Ticket URL: <https://code.djangoproject.com/ticket/27106#comment:11>

[Django]

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

-------------------------------------+-------------------------------------
Reporter: Baptiste Mispelon | Owner: Ryan
Type: | Cheley
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Comment (by Ryan Cheley):

Replying to [comment:11 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
--
Ticket URL: <https://code.djangoproject.com/ticket/27106#comment:12>

[Django]

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

-------------------------------------+-------------------------------------
Reporter: Baptiste Mispelon | Owner: Ryan
Type: | Cheley
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Comment (by 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
--
Ticket URL: <https://code.djangoproject.com/ticket/27106#comment:13>

[Django]

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

-------------------------------------+-------------------------------------
Reporter: Baptiste Mispelon | Owner: Ryan
Type: | Cheley
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Ryan Cheley):

* needs_better_patch: 1 => 0

--
Ticket URL: <https://code.djangoproject.com/ticket/27106#comment:14>

[Django]

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

-------------------------------------+-------------------------------------
Reporter: Baptiste Mispelon | Owner: Ryan
Type: | Cheley
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 1.10

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 1

Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Sarah Boyce):

* needs_better_patch: 0 => 1

--
Ticket URL: <https://code.djangoproject.com/ticket/27106#comment:15>