django.utils.functional documentation

[Daniele Procida]

There are caching/laziness-related functions and classes in django.utils.functional, but none seem to be documented (apart from cached_property which has documentation forthcoming).


django.utils.functional.memoize

Caches the output of a function in a dictionary. Could this be implemented as a decorator, and if so, would that be a more elegant way to make use of it?


django.utils.functional.lazy

Makes a callable lazy. Could this also be implemented as a decorator? And could a function be both memoized and made lazy?


django.utils.functional.allow_lazy

A decorator that makes a function respect the laziness of its arguments - if it's called with lazy arguments, it will itself become lazy.


django.utils.functional.LazyObject
django.utils.functional.SimpleLazyObject

Wrappers to make classes lazy. The difference between them is that when the wrapped classes are finally instantiated, the former makes it possible to manipulate the instantiation. The difference between these and django.utils.functional.lazy:

* lazy() can be applied to any callable, not just objects
* lazy() needs to know in advance what type the resulting items will be, whereas these don't


django.utils.functional.Promise
django.utils.functional.curry
django.utils.functional.lazy_property

I can't work out what these are for. Are they things that ought to be documented?


Daniele

[Aymeric Augustin]

Hi Daniele,

As you noticed, the purpose of these functions isn't very well defined. They were written to fill specific use cases in the Django codebase.

Before we document django.utils.functional, effectively making it a stable API, it would be best:
- to define a consistent and nice API covering a sensible scope,
- to make sure their behavior is intuitive and as safe as possible, and otherwise consider adding safeguards.

Sometimes not documenting anything is better than providing a sub-par API… This isn't a strong opinion or a -1, just something for you to consider before moving forwards with that plan.

--
Aymeric.

> --
> You received this message because you are subscribed to the Google Groups "Django developers" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to django-develop...@googlegroups.com.
> To post to this group, send email to django-d...@googlegroups.com.
> Visit this group at http://groups.google.com/group/django-developers.
> For more options, visit https://groups.google.com/groups/opt_out.