Utilitaires Django¶
Ce document présente tous les modules stables dans django.utils
. La plupart des modules dans django.utils
sont conçus pour un usage interne et seuls les parties documentées ici peuvent être considérées comme stables et donc rétrocompatibles, selon la politique interne d’obsolescence de publication.
django.utils.cache
¶
Ce module contient des fonctions utilitaires pour le contrôle du cache HTTP. Il opère en manipulant l’en-tête Vary
des réponses. Il contient des fonctions pour modifier directement l’en-tête des objets réponse ainsi que des décorateurs qui modifient les fonctions afin qu’elle se chargent elles-mêmes de la modification des en-têtes.
Pour plus d’informations sur l’en-tête Vary
, voir la RFC 9110#section-12.5.5.
À la base, l’en-tête HTTP Vary
définit quels en-têtes de requête un cache doit prendre en considération pour générer sa clé de cache. Les requêtes vers un même chemin mais contenant des contenus d’en-tête différents pour les en-têtes mentionnés dans Vary
ont besoin de produire des clés de cache différentes pour ne pas délivrer de mauvais contenu.
Par exemple, l’intergiciel d’internationalisation doit pouvoir mettre en cache des versions différentes en fonction de l’en-tête Accept-language
.
-
patch_cache_control
(response, **kwargs)[source]¶ Cette fonction complète l’en-tête
Cache-Control
en y ajoutant tous les paramètres nommés. La transformation se fait comme suit :- Tous les paramètres nommés sont transformés en minuscules et les soulignements sont convertis en tirets.
- Si la valeur d’un paramètre est
True
(exactementTrue
, pas seulement une valeur évaluée àTrue
), seul le nom du paramètre est ajouté à l’en-tête. - Tous les autres paramètres sont ajoutés avec leur valeur, après avoir passé par la fonction
str()
.
-
get_max_age
(response)[source]¶ Renvoie la valeur
max-age
de l’en-tête de réponseCache-Control
sous forme de nombre entier (ouNone
s’il n’existe pas ou qu’il n’est pas un nombre entier).
-
patch_response_headers
(response, cache_timeout=None)[source]¶ Ajoute certains en-têtes utiles à l’objet
HttpResponse
donné :Expires
Cache-Control
Chaque en-tête n’est ajouté que s’il n’est pas déjà présent.
cache_timeout
est en secondes. Le réglageCACHE_MIDDLEWARE_SECONDS
est utilisé par défaut.
-
add_never_cache_headers
(response)[source]¶ Ajoute un en-tête
Expires
à la date actuelle.Ajoute un en-tête
Cache-Control: max-age=0, no-cache, no-store, must-revalidate, private
à une réponse pour indiquer que la page ne doit jamais être mise en cache.Chaque en-tête n’est ajouté que s’il n’est pas déjà présent.
-
patch_vary_headers
(response, newheaders)[source]¶ Ajoute (ou met à jour) l’en-tête
Vary
dans l’objetHttpResponse
donné.newheaders
est une liste de noms d’en-têtes qui doivent se trouver dansVary
. Si les en-têtes contiennent un astérisque, l’en-têteVary
consistera en un seul astérisque'*'
, selon la RFC 9110#section-12.5.5. Sinon, les en-têtes existants dansVary
ne sont pas enlevés.
-
get_cache_key
(request, key_prefix=None, method='GET', cache=None)[source]¶ Renvoie une clé de cache basée sur le chemin de requête. Cette méthode peut être utilisée dans la phase de requête car elle extrait la liste d’en-têtes à prendre en compte à partir du registre global de chemin et utilise ces en-têtes pour construire une clé de cache à utiliser.
Si aucune liste d’en-tête n’est stockée, la page doit être reconstruite et cette fonction renvoie donc
None
.
-
learn_cache_key
(request, response, cache_timeout=None, key_prefix=None, cache=None)[source]¶ Apprend quels en-têtes à prendre en compte pour un certain chemin de requête à partir de l’objet réponse. Elle stocke ces en-têtes dans un registre global de chemins afin que tout accès ultérieur à ce chemin sache les en-têtes à prendre en compte sans devoir construire l’objet réponse lui-même. Les en-têtes sont nommés dans l’en-tête
Vary
de la réponse, mais il s’agit d’éviter de devoir générer la réponse.La liste des en-têtes à utiliser pour la génération de la clé de cache est stockée dans le même cache que les pages elles-mêmes. Si le cache rejette certaines vieilles données du cache, cela signifie qu’il faut reconstruire une fois la réponse pour avoir accès à l’en-tête
Vary
et par là à la liste des en-têtes à utiliser pour la clé de cache.
django.utils.dateparse
¶
Les fonctions définies dans ce module partagent les propriétés suivantes :
- Elles acceptent les chaînes aux formats date/heure ISO 8601 (ou certaines alternatives proches) et renvoient des objets des classes correspondantes du module Python
datetime
. - Elles génèrent une exception
ValueError
si la valeur d’entrée est correctement mise en forme mais qu’elle ne correspond pas à une date ou heure valable. - Elles renvoient
None
si la valeur d’entrée n’est pas correctement mise en forme. - Elles acceptent une résolution de valeur d’entrée jusqu’à la picoseconde, mais elles tronquent à la microseconde car c’est la résolution maximale gérée par Python.
-
parse_date
(value)[source]¶ Analyse une chaîne et renvoie un objet
datetime.date
.
-
parse_time
(value)[source]¶ Analyse une chaîne et renvoie un objet
datetime.time
.Les décalages UTC ne sont pas pris en charge ; si
value
en contient un, le résultat seraNone
.
-
parse_datetime
(value)[source]¶ Analyse une chaîne et renvoie un objet
datetime.datetime
.Les décalages UTC sont pris en charge ; si
value
en contient un, l’attributtzinfo
du résultat sera une instancedatetime.timezone
.
-
parse_duration
(value)[source]¶ Analyse une chaîne et renvoie un objet
datetime.timedelta
.S’attend à recevoir des données au format
"JJ HH:MM:SS.uuuuuu"
,"DD HH:MM:SS,uuuuuu"
ou tel que défini par ISO 8601 (par ex.P4DT1H15M20S
ce qui est équivalent à4 1:15:20
), ou au format d’intervalle jour-heure de PostgreSQL (par ex.3 days 04:05:06
).
django.utils.decorators
¶
-
method_decorator
(decorator, name='')[source]¶ Convertit un décorateur de fonction en un décorateur de méthode. Cette fonction peut être utilisée pour décorer des méthodes ou des classes ; dans ce dernier cas,
name
est le nom de la méthode à décorer et est obligatoire.decorator
peut aussi être une liste ou un tuple de fonctions. Celles-ci sont décorées dans l’ordre inverse, ce qui fait que l’ordre d’appel est le même que celui dans lequel les fonctions apparaissent dans la liste.Voir décoration des vues fondées sur les classes pour un exemple d’utilisation.
-
decorator_from_middleware
(middleware_class)[source]¶ Renvoie un décorateur de vue à partir d’une classe d’intergiciel. Cela permet d’utiliser des fonctionnalités d’intergiciel pour certaines vues seulement. L’intergiciel est créé sans aucun paramètre.
Il s’attend à des intergiciels compatibles avec l’ancien style de Django jusqu’à 1.9 (en ayant des méthodes comme
process_request()
,process_exception()
etprocess_response()
).
-
decorator_from_middleware_with_args
(middleware_class)[source]¶ Comme
decorator_from_middleware
, mais renvoie une fonction qui accepte des paramètres à transmettre à la classemiddleware_class
. Par exemple, le décorateurcache_page()
est créé à partir deCacheMiddleware
comme ceci :cache_page = decorator_from_middleware_with_args(CacheMiddleware) @cache_page(3600) def my_view(request): pass
-
sync_only_middleware
(middleware)[source]¶ Marque un intergiciel comme purement synchrone (par défaut dans Django, mais cela ajoute une robustesse supplémentaire au cas où la valeur par défaut devait changer dans le futur).
-
async_only_middleware
(middleware)[source]¶ Marque un intergiciel comme purement asynchrone. Django va l’envelopper dans une boucle événementielle asynchrone lorsqu’il est appelé à partir d’un chemin de requête WSGI.
-
sync_and_async_middleware
(middleware)[source]¶ Marque un intergiciel comme compatible synchrone et asynchrone, ce qui évite de devoir convertir les requêtes. Vous devez implémenter la détection du type de requête actuel pour utiliser ce décorateur. Voir la documentation des intergiciels asynchrones pour plus de détails.
django.utils.encoding
¶
-
smart_str
(s, encoding='utf-8', strings_only=False, errors='strict')[source]¶ Renvoie un objet
str
représentant un objet arbitraires
. Traite les chaînes d’octets en utilisant le codageencoding
.Si
strings_only
estTrue
, ne convertit pas certains objets non assimilables à des chaînes.
-
is_protected_type
(obj)[source]¶ Détermine si l’instance d’objet est d’un type protégé.
Les objets d’un type protégé sont préservés tels quels lorsqu’ils sont transmis à
force_str(strings_only=True)
.
-
force_str
(s, encoding='utf-8', strings_only=False, errors='strict')[source]¶ Semblable à
smart_str()
, sauf que les instances différées sont évaluées en chaînes, plutôt que de conserver leur état différé.Si
strings_only
estTrue
, ne convertit pas certains objets non assimilables à des chaînes.
-
smart_bytes
(s, encoding='utf-8', strings_only=False, errors='strict')[source]¶ Renvoie une version de l’objet arbitraire
s
sous forme de chaîne d’octets, en utilisant le codage indiqué dansencoding
.Si
strings_only
estTrue
, ne convertit pas certains objets non assimilables à des chaînes.
-
force_bytes
(s, encoding='utf-8', strings_only=False, errors='strict')[source]¶ Semblable à
smart_bytes
, sauf que les instances différées sont évaluées en chaînes d’octets, plutôt que de conserver leur état différé.Si
strings_only
estTrue
, ne convertit pas certains objets non assimilables à des chaînes.
-
iri_to_uri
(iri)[source]¶ Convertit une portion d’identifiant de ressource internationalisé (IRI) en portion d’URI qui convient pour l’inclusion dans une URL.
Il s’agit de l’algorithme de la section 3.1 de la RFC 3987#section-3.1, légèrement simplifiée dans la mesure où l’on admet que la valeur d’entrée est une chaîne et non pas un flux binaire arbitraire.
Accepte une IRI (chaîne ou octets UTF-8) et renvoie une chaîne contenant le résultat encodé.
-
uri_to_iri
(uri)[source]¶ Convertit une URI (Uniform Resource Identifier) en une IRI (Internationalized Resource Identifier).
Il s’agit d’un algorithme inspiré de la section 3.2 de la RFC 3987#section-3.2.
Accepte une URI en octets ASCII et renvoie une chaîne contenant le résultat encodé.
-
filepath_to_uri
(path)[source]¶ Convertit un chemin de système de fichiers en une portion d’URI convenable pour son inclusion dans une URL. Le chemin en entrée doit être soit des octets UTF-8, une chaîne ou un chemin
Path
.Cette méthode code certains caractères qui sont normalement identifiés comme des caractères spéciaux dans les URI. Notez que cette méthode ne code pas le caractère « “ » car c’est un caractère accepté dans les URI. Voir la fonction JavaScript
encodeURIComponent()
pour plus de détails.Renvoie une chaîne ASCII contenant le résultat encodé.
django.utils.feedgenerator
¶
Exemple d’utilisation :
>>> from django.utils import feedgenerator
>>> feed = feedgenerator.Rss201rev2Feed(
... title="Poynter E-Media Tidbits",
... link="https://www.poynter.org/tag/e-media-tidbits/",
... description="A group blog by the sharpest minds in online media/journalism/publishing.",
... language="en",
... )
>>> feed.add_item(
... title="Hello",
... link="https://www.holovaty.com/test/",
... description="Testing.",
... )
>>> with open("test.rss", "w") as fp:
... feed.write(fp, "utf-8")
...
Pour simplifier la sélection d’un générateur, utilisez feedgenerator.DefaultFeed
qui est actuellement Rss201rev2Feed
.
Pour les définitions des différentes versions de RSS, voir https://web.archive.org/web/20110718035220/http://diveintomark.org/archives/2004/02/04/incompatible-rss
-
get_tag_uri
(url, date)[source]¶ Crée un
TagURI
.Voir https://web.archive.org/web/20110514113830/http://diveintomark.org/archives/2004/05/28/howto-atom-id
SyndicationFeed
¶
-
class
SyndicationFeed
[source]¶ Classe de base pour tous les flux de syndication. Les sous-classes doivent implémenter
write()
.-
__init__
(title, link, description, language=None, author_email=None, author_name=None, author_link=None, subtitle=None, categories=None, feed_url=None, feed_copyright=None, feed_guid=None, ttl=None, **kwargs)[source]¶ Initialise le flux avec le dictionnaire de métadonnées indiqué, qui s’applique au flux entier.
Tout paramètre nommé supplémentaire passé à
__init__
est stocké dansself.feed
.Tous les paramètres doivent être des chaînes, à l’exception de
categories
, qui doit être une liste de chaînes.
-
add_item
(title, link, description, author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, categories=(), item_copyright=None, ttl=None, updateddate=None, enclosures=None, **kwargs)[source]¶ Ajoute un élément au flux. Tous les paramètres sont censés être des chaînes, sauf
pubdate
etupdateddate
qui doivent être des objetsdatetime.datetime
, etenclosures
qui doit être une liste d’instancesEnclosure
.
-
root_attributes
()[source]¶ Renvoie des attributs supplémentaires à ajouter à l’élément racine (c’est-à-dire le flux ou canal). Appelé depuis
write()
.
-
add_root_elements
(handler)[source]¶ Ajoute des éléments à l’élément racine (c’est-à-dire le flux ou canal). Appelé depuis
write()
.
-
item_attributes
(item)[source]¶ Renvoie des attributs supplémentaires à placer dans chaque élément du flux.
-
Rss201rev2Feed
¶
-
class
Rss201rev2Feed
(RssFeed)[source]¶ Spécification : https://cyber.harvard.edu/rss/rss.html
RssUserland091Feed
¶
-
class
RssUserland091Feed
(RssFeed)[source]¶ Spécification : http://backend.userland.com/rss091
django.utils.functional
¶
-
class
cached_property
(func)[source]¶ Le décorateur
@cached_property
met en cache le résultat d’une méthode ayant un seul paramètreself
sous forme de propriété. Le résultat en cache persiste aussi longtemps que l’instance, ce qui fait que si l’instance est conservée et que la fonction est appelée une nouvelle fois plus tard, le résultat en cache est renvoyé.Considérons un cas typique où une vue a besoin d’appeler la méthode d’un modèle pour effectuer un certain calcul avant de placer cette instance de modèle dans le contexte passé au gabarit, et celui-ci a aussi besoin d’appeler la méthode une nouvelle fois :
# the model class Person(models.Model): def friends(self): # expensive computation ... return friends # in the view: if person.friends(): ...
Et dans le gabarit, vous auriez :
{% for friend in person.friends %}
friends()
sera ici appelée deux fois. Puisque les instancesperson
dans la vue et dans le gabarit représentent la même instance, décorer la méthodefriends()
avec@cached_property
permet d’éviter celafrom django.utils.functional import cached_property class Person(models.Model): @cached_property def friends(self): ...
Notez que la méthode étant maintenant devenue une propriété, le code Python doit y accéder de manière adéquate :
# in the view: if person.friends: ...
La valeur en cache peut être traitée comme n’importe quel autre attribut normal de l’instance :
# clear it, requiring re-computation next time it's called del person.friends # or delattr(person, "friends") # set a value manually, that will persist on the instance until cleared person.friends = ["Huckleberry Finn", "Tom Sawyer"]
En raison du fonctionnement du protocole de descripteur, l’utilisation de
del
(oudelattr
) sur une propriété décorée parcached_property
qui n’a pas encore été accédée génère une exceptionAttributeError
.En plus d’offrir des avantages potentiels en terme de performance,
@cached_property
peut garantir que la valeur d’un attribut ne change pas de manière inattendue au cours de la vie d’une instance. Cela pourrait se produire avec une méthode dont le calcul est basé surdatetime.now()
, ou dans le cas où la base de données est modifiée par une autre processus dans le bref intervalle entre des appels successifs d’une méthode de la même instance.Vous pouvez créer des propriétés en cache pour des méthodes. Par exemple, si vous avez une méthode coûteuse
get_friends()
et que vous vouliez permettre de l’appeler aussi sans récupérer la valeur en cache, vous pourriez écrire :friends = cached_property(get_friends)
Alors que
person.get_friends()
recalcule les amis à chaque appel, la valeur de la propriété en cache persiste tant que vous ne la supprimez pas, comme expliqué ci-dessus :x = person.friends # calls first time y = person.get_friends() # calls again z = person.friends # does not call x is z # is True
-
class
classproperty
(method=None)[source]¶ Semblable à
@classmethod
, le décorateur@classproperty
convertit le résultat d’une méthode ayant un unique paramètrecls
en une propriété à laquelle on peut directement accéder depuis la classe.
-
keep_lazy
(func, *resultclasses)[source]¶ Django offre de nombreuses fonctions utilitaires (particulièrement dans
django.utils
) qui acceptent une chaîne comme premier paramètre et font quelque chose avec cette chaîne. Ces fonctions sont utilisées aussi bien par des filtres de gabarit que de façon directe dans du code Python.Si vous écrivez vous-même des fonctions semblables et que vous devez gérer des traductions, vous serez confronté au problème du traitement du premier paramètre quand il s’agit d’un objet de traduction différée. Il n’est pas souhaitable de le convertir immédiatement en chaîne de caractères, car il se peut que cette fonction soit utilisée en dehors d’une vue (et donc que le réglage de langue du fil d’exécution en cours ne soit pas le bon).
Pour des cas comme celui-là, utilisez le décorateur
django.utils.functional.keep_lazy()
. Il modifie la fonction afin que si elle est appelée avec en paramètre une traduction différée, l’évaluation de la fonction est reportée jusqu’au moment où il devient vraiment nécessaire de produire une chaîne.Par exemple :
from django.utils.functional import keep_lazy, keep_lazy_text def fancy_utility_function(s, *args, **kwargs): # Do some conversion on string 's' ... fancy_utility_function = keep_lazy(str)(fancy_utility_function) # Or more succinctly: @keep_lazy(str) def fancy_utility_function(s, *args, **kwargs): ...
Le décorateur
keep_lazy()
accepte quelques paramètres supplémentaires (*args
) indiquant le ou les types renvoyés par la fonction originale. Un cas d’utilisation fréquent est d’avoir des fonctions qui renvoient du texte. Pour celles-ci, passez le typestr
àkeep_lazy
(ou utilisez le décorateurkeep_lazy_text()
présenté à la section suivante).L’emploi de ce décorateur permet d’écrire une fonction et de compter sur la présence d’une vraie chaîne en entrée, puis d’ajouter au final la prise en charge des objets de traduction différée.
-
keep_lazy_text
(func)[source]¶ Un raccourci pour
keep_lazy(str)(func)
.Si vous avez une fonction qui renvoie du texte et que vous souhaitez pouvoir accepter des paramètres dont l’évaluation est différée, utilisez ce décorateur :
from django.utils.functional import keep_lazy, keep_lazy_text # Our previous example was: @keep_lazy(str) def fancy_utility_function(s, *args, **kwargs): ... # Which can be rewritten as: @keep_lazy_text def fancy_utility_function(s, *args, **kwargs): ...
django.utils.html
¶
En principe, le code HTML doit être construit avec des gabarits Django pour profiter de leur mécanisme d’échappement automatique, en faisant appel aux utilitaires de django.utils.safestring
en cas de besoin. Ce module fournit quelques utilitaires supplémentaires de bas niveau pour l’échappement de code HTML.
-
escape
(text)[source]¶ Renvoie le texte donné en codant les esperluettes, les guillemets et les chevrons de manière adaptée au HTML. Le texte en entrée est d’abord forcé en chaîne de caractères et le résultat final est marqué comme sûr avec
mark_safe()
.
-
conditional_escape
(text)[source]¶ Semblable à
escape()
, sauf qu’elle n’opère pas sur les chaînes déjà échappées afin d’éviter un double échappement.
-
format_html
(format_string, *args, **kwargs)[source]¶ Cette fonction est semblable à
str.format()
, sauf qu’elle est destinée à construire des fragments de HTML. Le premier argumentformat_string
n’est pas échappé, mais tous les autres arguments, nommés ou pas, sont traités parconditional_escape()
avant d’être transmis àstr.format()
. Finalement, la chaîne résultante est marquée comme sûre avecmark_safe()
.Dans les cas où il s’agit de produire des petits fragments HTML, cette fonction doit être préférée à l’interpolation de chaîne directe avec
%
oustr.format()
, car elle applique l’échappement à tous ses paramètres, tout comme le fait le système de gabarit par défaut.Donc au lieu d’écrire :
mark_safe( "%s <b>%s</b> %s" % ( some_html, escape(some_text), escape(some_other_text), ) )
Il est préférable d’écrire :
format_html( "{} <b>{}</b> {}", mark_safe(some_html), some_text, some_other_text, )
Ceci présente l’avantage de ne pas devoir appliquer soi-même
escape()
à chacun des paramètres et de risquer une anomalie ou une vulnérabilité XSS si on en oublie un.Notez que bien que cette fonction utilise
str.format()
pour effectuer l’interpolation, certaines des options de format fournies parstr.format()
(par ex. les formats de nombre) ne fonctionnent pas, car tous les paramètres sont passés par la moulinetteconditional_escape()
qui appelleforce_str()
sur les valeurs reçues.Obsolète depuis la version 5.0: La prise en charge de l’appel à
format_html()
sans transmettre d’arguments, nommés ou pas, est dorénavant obsolète.
-
format_html_join
(sep, format_string, args_generator)[source]¶ Une adaptateur de
format_html()
conçu pour le cas courant d’un groupe de paramètres devant être mis en forme avec la même chaîne de format, puis combinés avecsep
.sep
passe lui-même aussi parconditional_escape()
.args_generator
doit être un itérateur renvoyant la liste de paramètresargs
qui seront transmis àformat_html()
. Par exemple :format_html_join("\n", "<li>{} {}</li>", ((u.first_name, u.last_name) for u in users))
-
json_script
(value, element_id=None, encoder=None)[source]¶ Échappe tous les caractères spéciaux HTML/XML avec leur séquence d’échappement Unicode, afin que leur valeur puisse être utilisée de manière sécurisée avec JavaScript. Elle enveloppe également le JSON échappé dans une balise
<script>
. Si le paramètreelement_id
ne vaut pasNone
, la balise<script>
reçoit comme paramètreid
cette valeur. Par exemple :>>> json_script({"hello": "world"}, element_id="hello-data") '<script id="hello-data" type="application/json">{"hello": "world"}</script>'
Le codeur
encoder
qui contient par défautdjango.core.serializers.json.DjangoJSONEncoder
est utilisé pour sérialiser les données. Voir sérialisation JSON pour plus de détails sur ce sérialiseur.
-
strip_tags
(value)[source]¶ Tente de supprimer de la chaîne tout ce qui ressemble à une balise HTML, c’est-à-dire tout ce qui est contenu à l’intérieur de
<>
.Il n’y a absolument AUCUNE garantie que la chaîne résultante sera vraiment sûre du point de vue HTML. Il ne faut donc JAMAIS marquer comme sûre le résultat d’un appel à
strip_tag
sans l’avoir d’abord échappé, par exemple avecescape()
.Par exemple :
strip_tags(value)
Si
value
vaut"<b>Joël</b> <button>est</button> une <span>limace</span>"
, la valeur renvoyée sera"Joël est une limace"
.Si vous recherchez une solution plus solide, recherchez un outil tiers de nettoyage de HTML.
-
html_safe
()[source]¶ La méthode
__html__()
d’une classe aide les gabarits non Django à détecter les classes dont le résultat ne demande pas d’échappement HTML.Ce décorateur définit la méthode
__html__()
pour la classe décorée en enveloppant__str__()
dansmark_safe()
. Assurez-vous que la méthode__str__()
renvoie effectivement du texte qui ne demande pas d’échappement HTML.
django.utils.http
¶
-
urlencode
(query, doseq=False)[source]¶ Une version de la fonction Python
urllib.parse.urlencode()
pouvant agir sur des dictionnairesMultiValueDict
et d’autres valeurs qui ne sont pas des chaînes.
-
http_date
(epoch_seconds=None)[source]¶ Met en forme la date/heure en respectant le format de date RFC 1123#section-5.2.14 tel que défini par la RFC 9110#section-5.6.7 du standard HTTP.
Accepte un nombre à virgule exprimé en secondes depuis le temps Unix initial en UTC, de manière semblable à ce que produit
time.time()
. Si le paramètre estNone
, c’est la date actuelle qui est renvoyée.Produit une chaîne au format
Wdy, DD Mon YYYY HH:MM:SS GMT
.
-
content_disposition_header
(as_attachment, filename)[source]¶ Construit la valeur d’un en-tête HTTP
Content-Disposition
à partir du nom de fichierfilename
donné tel que spécifié par rfc:6266. RenvoieNone
sias_attachment
vautFalse
et quefilename
vautNone
, sinon renvoie une chaîne apte à être utilisée dans l’en-tête HTTPContent-Disposition
.
django.utils.module_loading
¶
Fonctions pour manipuler les modules Python.
-
import_string
(dotted_path)[source]¶ Importe un chemin pointé de module et renvoie la classe ou l’attribut désigné par le dernier nom du chemin. Génère
ImportError
si l’importation échoue. Par exemple :from django.utils.module_loading import import_string ValidationError = import_string("django.core.exceptions.ValidationError")
est équivalent à :
from django.core.exceptions import ValidationError
django.utils.safestring
¶
Fonctions et classes pour travailler avec des « chaînes sûres » : des chaînes qui peuvent être affichées sans crainte sans devoir subir d’échappement HTML. Quand une chaîne est marquée comme « sûre » (safe), cela signifie que le producteur de la chaîne a déjà transformé en entités appropriées les caractères qui ne doivent pas être interprétés par le moteur HTML (par ex. « < »).
-
class
SafeString
[source]¶ Une sous-classe de
str
pour des chaînes ayant été explicitement marquées comme « sûres » (plus besoin d’échappement) à des fins d’affichage HTML.
-
mark_safe
(s)[source]¶ Marque explicitement une chaîne comme sûre en vue de son affichage (HTML). L’objet renvoyé peut être utilisé partout où une chaîne peut être utilisé.
Cette fonction peut être utilisée plusieurs fois sur la même chaîne.
Peut aussi être utilisé comme décorateur.
Pour la construction de fragments de HTML, il est généralement préférable d’utiliser plutôt
django.utils.html.format_html()
.Une chaîne marquée comme sûre redevient non sûre quand elle est modifiée. Par exemple :
>>> mystr = "<b>Hello World</b> " >>> mystr = mark_safe(mystr) >>> type(mystr) <class 'django.utils.safestring.SafeString'> >>> mystr = mystr.strip() # removing whitespace >>> type(mystr) <type 'str'>
django.utils.text
¶
-
format_lazy
(format_string, *args, **kwargs)¶ Une version de
str.format()
pour les cas oùformat_string
,args
oukwargs
contiennent des objets différés. Le premier paramètre est la chaîne à mettre en forme. Par exemple :from django.utils.text import format_lazy from django.utils.translation import pgettext_lazy urlpatterns = [ path( format_lazy("{person}/<int:pk>/", person=pgettext_lazy("URL", "person")), PersonDetailView.as_view(), ), ]
Cet exemple permet aux traducteurs de traduire une partie de l’URL. Si « person » est traduit en « persona », l’expression régulière va correspondre à
persona/(?P<pk>\d+)/$
, par ex.persona/5/
.
-
slugify
(value, allow_unicode=False)[source]¶ Convertit une chaîne en un « slug » d’URL en :
- Convertissant en ASCII si
allow_unicode
vautFalse
(par défaut). - Convertissant en minuscules.
- Supprimant les caractères qui ne sont pas alphanumériques, des soulignements, des tirets ou des espaces blancs.
- Remplaçant tout espace blanc ou répétition de tirets par un seul.
- Supprimant les caractères blancs, les tirets et les soulignements en début et fin de chaîne.
Par exemple :
>>> slugify(" Joel is a slug ") 'joel-is-a-slug'
Si vous souhaitez permettre les caractères Unicode, passez
allow_unicode=True
. Par exemple :>>> slugify("你好 World", allow_unicode=True) '你好-world'
- Convertissant en ASCII si
django.utils.timezone
¶
-
get_fixed_timezone
(offset)[source]¶ Renvoie une instance
tzinfo
représentant un fuseau horaire avec un décalage UTC fixe.offset
est une différence de tempsdatetime.timedelta
ou un nombre entier en minutes. Utilisez des valeurs positives pour les fuseaux horaires à l’est d’UTC et des valeurs négatives à l’ouest d’UTC.
-
get_default_timezone
()[source]¶ Renvoie une instance
tzinfo
qui représente le fuseau horaire par défaut.
-
get_default_timezone_name
()[source]¶ Renvoie le nom du fuseau horaire par défaut.
-
get_current_timezone
()[source]¶ Renvoie une instance
tzinfo
qui représente le fuseau horaire en cours.
-
get_current_timezone_name
()[source]¶ Renvoie le nom du fuseau horaire en cours.
-
activate
(timezone)[source]¶ Définit le fuseau horaire actif. Le paramètre
timezone
doit être une instance d’une sous-classe detzinfo
ou un nom de fuseau horaire.
-
deactivate
()[source]¶ Désactive le fuseau horaire actuel.
-
override
(timezone)[source]¶ Gestionnaire de contexte Python qui définit le fuseau horaire actif lorsqu’il entre en action avec
activate()
, puis restaure le fuseau horaire précédemment actif en quittant. Si le paramètretimezone
vautNone
, le fuseau horaire actif est alors désactivé à l’entrée du gestionnaire avecdeactivate()
.override
est aussi utilisable comme décorateur de fonction.
-
localtime
(value=None, timezone=None)[source]¶ Convertit un objet
datetime
conscient vers un fuseau horaire différent, par défaut le fuseau horaire actif.Lorsque
value
est omise, la valeur par défaut estnow()
.Cette fonction ne fonctionne pas avec des objets date/heure naïfs ; utilisez alors plutôt
make_aware()
.
-
localdate
(value=None, timezone=None)[source]¶ Utilise
localtime()
pour convertir un objetdatetime
conscient en unedate()
dans un fuseau horaire différent, par défaut le fuseau horaire actif.Lorsque
value
est omise, la valeur par défaut estnow()
.Cette fonction ne fonctionne pas avec des objets date/heure naïfs.
-
now
()[source]¶ Renvoie un objet
datetime
représentant le moment actuel dans le temps (« maintenant »). La valeur précisément renvoyée dépend de la valeur deUSE_TZ
:- Si
USE_TZ
estFalse
, il s’agira d’une date/heure naïve (c’est-à-dire une date/heure sans fuseau horaire associé) représentant le temps actuel dans le fuseau horaire local du système. - Si
USE_TZ
estTrue
, il s’agira d’une date/heure consciente représentant le temps actuel en UTC. Notez quenow()
renvoie toujours le temps UTC quelle que soit la valeur deTIME_ZONE
; vous pouvez utiliserlocaltime()
pour obtenir l’heure dans le fuseau horaire actif.
- Si
-
is_aware
(value)[source]¶ Renvoie
True
sivalue
est consciente,False
si elle est naïve. Cette fonction présuppose quevalue
est un objetdatetime
.
-
is_naive
(value)[source]¶ Renvoie
True
sivalue
est naïve,False
si elle est consciente. Cette fonction présuppose quevalue
est un objetdatetime
.
-
make_aware
(value, timezone=None)[source]¶ Renvoie un objet
datetime
conscient représentant le même moment dans le temps quevalue
dans le fuseautimezone
,value
étant un objetdatetime
naïf. Sitimezone
est défini àNone
, il prend le fuseau horaire actuel comme valeur par défaut.
-
make_naive
(value, timezone=None)[source]¶ Renvoie un objet
datetime
naïf représentant le même moment dans le temps quevalue
dans le fuseautimezone
,value
étant un objetdatetime
conscient. Sitimezone
est défini àNone
, il prend le fuseau horaire actuel comme valeur par défaut.
django.utils.translation
¶
Pour une discussion complète sur l’utilisation de ce qui suit, consultez la documentation sur la traduction.
-
pgettext
(context, message)[source]¶ Traduit
message
seloncontext
et renvoie le résultat dans une chaîne.Pour plus d’informations, voir Marqueurs contextuels.
-
gettext_lazy
(message)¶
-
pgettext_lazy
(context, message)¶ Même comportement que les versions non différées ci-dessus, mais en utilisant une exécution différée.
-
gettext_noop
(message)[source]¶ Marque les chaînes en vue de leur traduction mais ne les traduit pas sur le moment. Cela peut être utile pour stocker des chaînes qui doivent rester dans la langue de base (parce qu’elles pourraient être utilisées de manière externe) dans des variables globales et que ces chaînes seront traduites plus tard.
-
ngettext
(singular, plural, number)[source]¶ Traduit
singular
etplural
et renvoie la chaîne appropriée en fonction denumber
.
-
npgettext
(context, singular, plural, number)[source]¶ Traduit
singulier
etpluriel
et renvoie la chaîne appropriée en fonction denombre
et decontext
.
-
npgettext_lazy
(context, singular, plural, number)[source]¶ Même comportement que les versions non différées ci-dessus, mais en utilisant une exécution différée.
-
activate
(language)[source]¶ Récupère le catalogue de traduction d’une langue donnée et l’active comme catalogue de traduction courant pour le fil d’exécution en cours.
-
deactivate
()[source]¶ Désactive le catalogue de traduction actif afin que des appels à _ subséquents vont refaire appel au catalogue de traduction par défaut.
-
deactivate_all
()[source]¶ Place une instance de
NullTranslations()
comme catalogue de traduction actif. Cela peut être utile si l’on souhaite que des traductions différées apparaissent avec leur chaîne originale (donc non traduite) pour une raison quelconque.
-
override
(language, deactivate=False)[source]¶ Un gestionnaire de contexte Python qui utilise
django.utils.translation.activate()
pour récupérer le catalogue de traduction d’une langue données, qui l’active comme catalogue de traduction pour le fil d’exécution en cours et qui réactive la langue précédemment active lors de sa sortie. Il est possible de définir le paramètredeactivate
àTrue
si l’on souhaite que la langue de traduction temporaire soit désactivée à la sortie du gestionnaire avecdjango.utils.translation.deactivate()
. Si le paramètrelanguage
vautNone
, une instance deNullTranslations()
est activée dans le code affecté par le gestionnaire de contexte.override
est aussi utilisable comme décorateur de fonction.
-
check_for_language
(lang_code)[source]¶ Contrôle s’il existe un fichier de langue global pour le code de langue donné (par ex. “fr”, “pt_BR”). Ceci est utilisé pour décider si une langue demandée par un utilisateur est disponible.
-
get_language
()[source]¶ Renvoie le code de langue actuellement sélectionné. Renvoie
None
si les traductions sont temporairement désactivées (pardeactivate_all()
ou lorsqueNone
est passé àoverride()
).
-
get_language_bidi
()[source]¶ Renvoie l’agencement bidirectionnel de la langue sélectionnée :
False
= agencement de gauche à droiteTrue
= agencement de droite à gauche
-
get_language_from_request
(request, check_path=False)[source]¶ Analyse la requête pour trouver quelle est la langue souhaitée par l’utilisateur. Seules les langues figurant dans
settings.LANGUAGES
sont prises en compte. Si l’utilisateur demande un sous-code de langue alors que seule la langue principale est disponible, c’est la langue principale qui est renvoyée.Si
check_path
vautTrue
, la fonction examine d’abord l’URL demandée pour voir si son chemin commence par un code de langue figurant dans le réglageLANGUAGES
.
-
get_supported_language_variant
(lang_code, strict=False)[source]¶ Renvoie
lang_code
s’il figure dans le réglageLANGUAGES
, en choisissant potentiellement une variante plus générique. Par exemple, “es”` est renvoyé silang_code
est'es-ar'
et que'es'
se trouve dansLANGUAGES
mais pas'es-ar'
.La longueur maximale de
lang_code
est de 500 caractères. Une exceptionLookupError
est générée silang_code
dépasse cette limite et questrict
estTrue
, ou s’il n’existe pas de variante générique et questrict
estFalse
.Si
strict
vautFalse
(valeur par défaut), une variante territoriale peut être renvoyée lorsque ni le code de langue, ni sa variante générique n’est trouvée. Par exemple, si seul'es-co'
se trouve dansLANGUAGES
, c’est ce dernier qui est renvoyé pour les codes de langue comme'es'
et'es-ar'
. Ces correspondances ne sont pas renvoyées quandstrict=True
.Génère
LookupError
si rien n’est trouvé.Changed in Django 4.2.15:Dans les anciennes versions, les valeurs de
lang_code
dépassant 500 caractères étaient traitées sans générerLookupError
.