--- title: "Utilitaires Django" version: 1.9 locale: fr source: https://docs.djangoproject.com/fr/1.9/ref/utils/ canonical: https://djangodocs.dev/fr/1.9/ref/utils/ --- # 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](/fr/1.9/internals/release-process/#internal-release-deprecation-policy). ## `django.utils.cache` Ce module contient des fonctions utilitaires pour le contrôle du cache. 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. For information on the `Vary` header, see [**RFC 7231 Section 7.1.4**](https://datatracker.ietf.org/doc/html/rfc7231.html#section-7.1.4). À 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](/fr/1.9/topics/i18n/) doit pouvoir mettre en cache des versions différentes en fonction de l’en-tête `Accept-language`. #### `patch_cache_control(response, **kwargs)` 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` (exactement `True`, 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)` Renvoie la valeur `max-age` de l’en-tête de réponse `Cache-Control` sous forme de nombre entier (ou `None` s’il n’existe pas ou qu’il n’est pas un nombre entier). #### `patch_response_headers(response, cache_timeout=None)` Ajoute certains en-têtes utiles à l’objet `HttpResponse` donné : - `ETag` - `Last-Modified` - `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églage [`CACHE_MIDDLEWARE_SECONDS`](/fr/1.9/ref/settings/#std-setting-CACHE_MIDDLEWARE_SECONDS) est utilisé par défaut. #### `add_never_cache_headers(response)` Ajoute un en-tête `Cache-Control: max-age=0, no-cache, no-store, must-revalidate` à une réponse pour indiquer que la page ne doit jamais être mise en cache. > **Changed in Django 1.8.8** > > Dans les versions plus anciennes, l’en-tête envoyé contenait `Cache-Control: max-age=0`. Cela n’empêchait pas le cache de manière fiable dans tous les navigateurs. #### `patch_vary_headers(response, newheaders)` Ajoute (ou met à jour) l’en-tête `Vary` dans l’objet `HttpResponse` donné. `newheaders` est une liste de noms d’en-têtes qui doivent se trouver dans `Vary`. Les en-têtes existants dans `Vary` ne sont pas enlevés. #### `get_cache_key(request, key_prefix=None)` 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)` 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 simplement 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 génèrent une exception [`ValueError`](https://docs.python.org/3/library/exceptions.html#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)` Analyse une chaîne et renvoie un objet [`datetime.date`](https://docs.python.org/3/library/datetime.html#datetime.date). #### `parse_time(value)` Analyse une chaîne et renvoie un objet [`datetime.time`](https://docs.python.org/3/library/datetime.html#datetime.time). Les décalages UTC ne sont pas pris en charge ; si `value` en contient un, le résultat sera `None`. #### `parse_datetime(value)` Analyse une chaîne et renvoie un objet [`datetime.datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime). Les décalages UTC sont pris en charge ; si `value` en contient un, l’attribut `tzinfo` du résultat sera une instance [`FixedOffset`](#django.utils.timezone.FixedOffset). #### `parse_duration(value)` > **New in Django 1.8** Analyse une chaîne et renvoie un objet [`datetime.timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta). S’attend à recevoir des données au format `"JJ HH:MM:SS.uuuuuu"` ou tel que défini par ISO 8601 (par ex. `P4DT1H15M20S` ce qui est équivalent à `4 1:15:20`). ## `django.utils.decorators` #### `method_decorator(decorator, name='')` 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` may also be a list or tuple of functions. They are wrapped in reverse order so that the call order is the order in which the functions appear in the list/tuple. Voir [décoration des vues fondées sur les classes](/fr/1.9/topics/class-based-views/intro/#id1) pour un exemple d’utilisation. > **Changed in Django 1.9** > > La possibilité de décorer des classes, le paramètre `name` ainsi que la capacité de `decorator` d’accepter une liste ou un tuple de fonctions à décorer ont été ajoutés. #### `decorator_from_middleware(middleware_class)` 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. #### `decorator_from_middleware_with_args(middleware_class)` Comme `decorator_from_middleware`, mais renvoie une fonction qui accepte des paramètres à transmettre à la classe `middleware_class`. Par exemple, le décorateur [`cache_page()`](/fr/1.9/topics/cache/#django.views.decorators.cache.cache_page) est créé à partir de `CacheMiddleware` comme ceci : ``` cache_page = decorator_from_middleware_with_args(CacheMiddleware) @cache_page(3600) def my_view(request): pass ``` ## `django.utils.encoding` #### `python_2_unicode_compatible()` Un décorateur qui définit les méthodes `__unicode__` et `__str__` avec Python 2. Avec Python 3, il ne fait rien. Pour pouvoir prendre en charge à la fois Python 2 et 3 avec une seule base de code, définissez une méthode `__str__` renvoyant du texte et appliquez ce décorateur à la classe. #### `smart_text(s, encoding='utf-8', strings_only=False, errors='strict')` Renvoie un objet texte représentant `s`, c’est-à-dire de type `unicode` avec Python 2 et de type `str` avec Python 3. Traite les chaînes d’octets en utilisant le codage `encoding`. Si `strings_only` est `True`, ne convertit pas certains objets non assimilables à des chaînes. #### `smart_unicode(s, encoding='utf-8', strings_only=False, errors='strict')` Nom historique de [`smart_text()`](#django.utils.encoding.smart_text). Seulement disponible avec Python 2. #### `is_protected_type(obj)` 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_text(strings_only=True)`. #### `force_text(s, encoding='utf-8', strings_only=False, errors='strict')` Semblable à `smart_text`, 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` est `True`, ne convertit pas certains objets non assimilables à des chaînes. #### `force_unicode(s, encoding='utf-8', strings_only=False, errors='strict')` Nom historique de [`force_text()`](#django.utils.encoding.force_text). Seulement disponible avec Python 2. #### `smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict')` Renvoie une version de `s` sous forme de chaîne d’octets, en utilisant le codage indiqué dans `encoding`. Si `strings_only` est `True`, ne convertit pas certains objets non assimilables à des chaînes. #### `force_bytes(s, encoding='utf-8', strings_only=False, errors='strict')` 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` est `True`, ne convertit pas certains objets non assimilables à des chaînes. #### `smart_str(s, encoding='utf-8', strings_only=False, errors='strict')` Alias de [`smart_bytes()`](#django.utils.encoding.smart_bytes) avec Python 2 et de [`smart_text()`](#django.utils.encoding.smart_text) avec Python 3. Cette fonction renvoie un type `str` ou une chaîne différée. Cela convient par exemple à l’écriture vers [`sys.stdout`](https://docs.python.org/3/library/sys.html#sys.stdout) aussi bien pour Python 2 que Python 3. #### `force_str(s, encoding='utf-8', strings_only=False, errors='strict')` Alias de [`force_bytes()`](#django.utils.encoding.force_bytes) avec Python 2 et de [`force_text()`](#django.utils.encoding.force_text) avec Python 3. Cette fonction renvoie toujours un type `str`. #### `iri_to_uri(iri)` 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**](https://datatracker.ietf.org/doc/html/rfc3987.html#section-3.1). Cependant, comme nous partons du principe que la valeur d’entrée est déjà soit en UTF-8, soit en unicode, nous pouvons simplifier un peu les choses par rapport à la méthode complète. Accepte une IRI sous forme d’octets UTF-8 et renvoie une chaîne d’octets ASCII contenant le résultat encodé. #### `uri_to_iri(uri)` > **New in Django 1.8** 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**](https://datatracker.ietf.org/doc/html/rfc3987.html#section-3.2). Accepte une URI en octets ASCII et renvoie une chaîne unicode contenant le résultat encodé. #### `filepath_to_uri(path)` 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 de l’UTF-8, soit de l’unicode. 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é. #### `escape_uri_path(path)` > **New in Django 1.8** Échappe les caractères non sûrs de la portion de chemin d’un URI (Uniform Resource Identifier). ## `django.utils.feedgenerator` Exemple d’utilisation : ``` >>> from django.utils import feedgenerator >>> feed = feedgenerator.Rss201rev2Feed( ... title="Poynter E-Media Tidbits", ... link="http://www.poynter.org/column.asp?id=31", ... description="A group Weblog by the sharpest minds in online media/journalism/publishing.", ... language="en", ... ) >>> feed.add_item( ... title="Hello", ... link="http://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 #### `get_tag_uri(url, date)` Crée un `TagURI`. Voir ### `SyndicationFeed` #### `class SyndicationFeed` 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)` 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é dans `self.feed`. Tous les paramètres doivent être des objets Unicode, à l’exception de `categories`, qui doit être une liste d’objets Unicode. #### `add_item(title, link, description, author_email=None, author_name=None, author_link=None, pubdate=None, comments=None, unique_id=None, enclosure=None, categories=(), item_copyright=None, ttl=None, updateddate=None, enclosures=None, **kwargs)` Ajoute un élément au flux. Tous les paramètres sont censés être des objets Python `unicode`, sauf `pubdate` et `updateddate` qui doivent être des objets `datetime.datetime`, `enclosure` qui est une instance `Enclosure`, et\`\`enclosures\`\` qui est une liste d’instances de la classe `Enclosure`. > **Deprecated since Django 1.9** > > Obsolète depuis la version 1.9: Le paramètre nommé `enclosure` est obsolète et remplacé par le nouveau paramètre nommé `enclosures` qui accepte une liste d’objets `Enclosure`. #### `num_items()` #### `root_attributes()` Renvoie des attributs supplémentaires à ajouter à l’élément racine (c’est-à-dire le flux ou canal). Appelé depuis `write()`. #### `add_root_elements(handler)` Ajoute des éléments à l’élément racine (c’est-à-dire le flux ou canal). Appelé depuis `write()`. #### `item_attributes(item)` Renvoie des attributs supplémentaires à placer dans chaque élément du flux. #### `add_item_elements(handler, item)` Ajoute des éléments pour chaque élément du flux. #### `write(outfile, encoding)` Exporte le flux dans le codage indiqué vers `outfile` qui est un objet de type fichier. Les sous-classes sont censées surcharger cette méthode. #### `writeString(encoding)` Renvoie le flux dans le codage indiqué sous forme de chaîne. #### `latest_post_date()` Renvoie la dernière date `pubdate` ou `updateddate` parmi tous les éléments du flux. Si aucun de ces attributs n’est trouvé sur aucun élément, la date/heure actuelle est renvoyée. ### `Enclosure` #### `class Enclosure` Représente une annexe RSS. ### `RssFeed` #### `class RssFeed(SyndicationFeed)` ### `Rss201rev2Feed` #### `class Rss201rev2Feed(RssFeed)` Spécification : ### `RssUserland091Feed` #### `class RssUserland091Feed(RssFeed)` Spécification : ### `Atom1Feed` #### `class Atom1Feed(SyndicationFeed)` Spécification : ## `django.utils.functional` #### `class cached_property(object, name)` Le décorateur `@cached_property` met en cache le résultat d’une méthode ayant un seul paramètre `self` 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 : ```html+django {% for friend in person.friends %} ``` Ici, `friends()` est appelée deux fois. Comme l’instance `person` est la même dans la vue que dans le gabarit, `@cached_property` peut éviter ce double travail : ``` from django.utils.functional import cached_property @cached_property def friends(self): # expensive computation ... return friends ``` Notez que la méthode étant maintenant devenue une propriété, le code Python doit l’invoquer 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 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é sur `datetime.now()`, ou simplement 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. > **New in Django 1.8** Vous pouvez utiliser le paramètre `name` pour créer des propriétés en cache pour d’autres 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, name='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 ``` #### `allow_lazy(func, *resultclasses)` 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.allow_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 allow_lazy def fancy_utility_function(s, ...): # Do some conversion on string 's' ... # Replace unicode by str on Python 3 fancy_utility_function = allow_lazy(fancy_utility_function, unicode) ``` Le décorateur `allow_lazy()` accepte en paramètre, en plus de la fonction à décorer, un nombre de paramètres supplémentaires (`*args`) indiquant le ou les types que la fonction d’origine est susceptible de renvoyer. Il est normalement suffisant d’inclure `unicode` (ou `str` avec Python 3) et de vérifier que la fonction renvoie bel et bien des chaînes Unicode uniquement. 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. ## `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`](#module-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)` 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 passé dans la fonction [`force_text()`](#django.utils.encoding.force_text) et le résultat final est marqué comme sûr avec [`mark_safe()`](#django.utils.safestring.mark_safe). #### `conditional_escape(text)` 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)` This is similar to [`str.format()`](https://docs.python.org/3/library/stdtypes.html#str.format), except that it is appropriate for building up HTML fragments. All args and kwargs are passed through [`conditional_escape()`](#django.utils.html.conditional_escape) before being passed to `str.format()`. For the case of building up small HTML fragments, this function is to be preferred over string interpolation using `%` or `str.format()` directly, because it applies escaping to all arguments - just like the template system applies escaping by default. Donc au lieu d’écrire : ``` mark_safe("%s %s %s" % ( some_html, escape(some_text), escape(some_other_text), )) ``` Il est préférable d’écrire : ``` format_html("{} {} {}", mark_safe(some_html), some_text, some_other_text, ) ``` Ceci présente l’avantage de ne pas devoir appliquer soi-même [`escape()`](#django.utils.html.escape) à chacun des paramètres et de risquer une anomalie ou une vulnérabilité XSS si on en oublie un. Note that although this function uses `str.format()` to do the interpolation, some of the formatting options provided by `str.format()` (e.g. number formatting) will not work, since all arguments are passed through [`conditional_escape()`](#django.utils.html.conditional_escape) which (ultimately) calls [`force_text()`](#django.utils.encoding.force_text) on the values. #### `format_html_join(sep, format_string, args_generator)` Une adaptateur de [`format_html()`](#django.utils.html.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 avec `sep`. `sep` passe lui-même aussi par [`conditional_escape()`](#django.utils.html.conditional_escape). `args_generator` doit être un itérateur renvoyant la liste de paramètres `args` qui seront transmis à [`format_html()`](#django.utils.html.format_html). Par exemple : ``` format_html_join( '\n', "
  • {} {}
    • ", ((u.first_name, u.last_name) for u in users) ) ``` #### `strip_tags(value)` 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 avec [`escape()`](#django.utils.html.escape). Par exemple : ``` strip_tags(value) ``` Si `value` vaut `"Joël une limace"`, la valeur renvoyée sera `"Joël est une limace"`. Si vous recherchez une solution plus robuste, regardez du côté de la bibliothèque Python [bleach](https://pypi.python.org/pypi/bleach). #### `remove_tags(value, tags)` > **Deprecated since Django 1.8** > > Obsolète depuis la version 1.8: `removetags()` ne peut pas garantir que le résultat soit un contenu HTML sûr ; la balise a été rendue obsolète pour des raisons de sécurité. Envisagez plutôt l’emploi de [bleach](https://pypi.python.org/pypi/bleach). Enlève de la valeur fournie une liste de noms de balises \[X\]HTML séparés par des espaces. Il n’y a absolument AUCUNE garantie que la chaîne résultante sera vraiment sûre du point de vue HTML. En particulier, cette fonction n’agit pas récursivement, ce qui fait que le résultat de `remove_tags("ript>alert('XSS')ript>", "script")` ne supprimera pas la balise script « imbriquée ». Si la valeur provient d’une source non certifiée, ne marquez JAMAIS comme sûr le résultat d’un appel à `remove_tags()` sans l’avoir préalablement échappé, par exemple avec [`escape()`](#django.utils.html.escape). Par exemple : ``` remove_tags(value, "b span") ``` Si `value` contient `"Joël une limace"`, la valeur renvoyée sera `"Joël une limace"`. Notez que ce filtre est sensible à la casse. Si `value` contient `"Joël une limace"`, la valeur renvoyée sera `"Joël une limace"`. #### `html_safe()` > **New in Django 1.8** 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 `__unicode__()` (Python 2) ou `__str__()` (Python 3) dans [`mark_safe()`](#django.utils.safestring.mark_safe). Assurez-vous que la méthode `__unicode__()` ou `__str__()` renvoie effectivement du texte qui ne demande pas d’échappement HTML. ## `django.utils.http` #### `urlquote(url, safe='/')` Une version de la fonction Python `urllib.quote()` pouvant agir sur des chaînes Unicode. L’URL est d’abord codée en UTF-8 avant d’être traitée. La chaîne renvoyée peut être utilisée sans crainte comme partie d’un paramètre à un appel `iri_to_uri()` sans se préoccuper de double-échappement. Utilise l’exécution différée. #### `urlquote_plus(url, safe='')` Une version de la fonction Python `urllib.quote_plus()` pouvant agir sur des chaînes Unicode. L’URL est d’abord codée en UTF-8 avant d’être traitée. La chaîne renvoyée peut être utilisée sans crainte comme partie d’un paramètre à un appel `iri_to_uri()` sans se préoccuper de double-échappement. Utilise l’exécution différée. #### `urlencode(query, doseq=0)` Une version de la fonction Python `urllib.urlencode()` pouvant agir sur des chaînes Unicode. Les paramètres sont d’abord transformés en chaînes codées en UTF-8, puis codées de manière attendue. #### `cookie_date(epoch_seconds=None)` Met en forme la date pour garantir la compatibilité avec le standard de cookie Netscape. 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 est `None`, c’est la date actuelle qui est renvoyée. Produit une chaîne au format `Wdy, DD-Mon-YYYY HH:MM:SS GMT`. #### `http_date(epoch_seconds=None)` Formats the time to match the [**RFC 1123**](https://datatracker.ietf.org/doc/html/rfc1123.html) date format as specified by HTTP [**RFC 7231 Section 7.1.1.1**](https://datatracker.ietf.org/doc/html/rfc7231.html#section-7.1.1.1). 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 est `None`, c’est la date actuelle qui est renvoyée. Produit une chaîne au format `Wdy, DD Mon YYYY HH:MM:SS GMT`. #### `base36_to_int(s)` Convertit une chaîne en base 36 en un nombre entier. Avec Python 2, le résultat est toujours de type `int`, jamais un `long`. #### `int_to_base36(i)` Convertit un nombre entier positif en une chaîne en base 36. Avec Python 2, `i` doit être plus petit que [sys.maxint](https://docs.python.org/2/library/sys.html#sys.maxint). #### `urlsafe_base64_encode(s)` Code une chaîne d’octets en base64 pour être utilisée dans les URL, en enlevant d’éventuels signes « égal » finaux. #### `urlsafe_base64_decode(s)` Décode une chaîne codée en base64, ajoutant d’éventuels signes « égal » finaux qui pourraient avoir été enlevés. ## `django.utils.module_loading` Fonctions pour manipuler les modules Python. #### `import_string(dotted_path)` 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 SafeBytes` Une sous-classe de `bytes` pour des chaînes ayant été explicitement marquées comme « sûres » (plus besoin d’échappement) à des fins d’affichage HTML. #### `class SafeString` 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. Cela correspond à [`SafeBytes`](#django.utils.safestring.SafeBytes) avec Python 2 et [`SafeText`](#django.utils.safestring.SafeText) avec Python 3. #### `class SafeText` Une sous-classe de `str` (avec Python 3) ou de `unicode` (avec Python 2) pour des chaînes ayant été explicitement marquées comme « sûres » (plus besoin d’échappement) à des fins d’affichage HTML. #### `class SafeUnicode` Nom historique de [`SafeText`](#django.utils.safestring.SafeText). Seulement disponible avec Python 2. #### `mark_safe(s)` 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 ou un objet unicode peut être utilisé. Cette fonction peut être utilisée plusieurs fois sur la même chaîne. Pour la construction de fragments de HTML, il est généralement préférable d’utiliser plutôt [`django.utils.html.format_html()`](#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 = 'Hello World ' >>> mystr = mark_safe(mystr) >>> type(mystr) >>> mystr = mystr.strip() # removing whitespace >>> type(mystr) ``` #### `mark_for_escaping(s)` Marque explicitement une chaîne comme devant être échappée en vue de son affichage HTML. Ceci n’a pas d’effet sur les sous-classes de `SafeData`. Cette fonction peut être utilisée plusieurs fois sur la même chaîne (au final, l’échappement n’est appliqué qu’une seule fois). ## `django.utils.text` #### `slugify(allow_unicode=False)` Convertit en ASCII si `allow_unicode` vaut `False` (par défaut). Convertit les espaces en tirets. Enlève les caractères qui ne sont ni alphanumériques, ni soulignements, ni tirets. Convertit en minuscules. Les espaces en début et fin de chaîne sont aussi enlevés. Par exemple : ``` slugify(value) ``` Si `value` contient `"Joël est une limace"`, le résultat sera `joel-est-une-limace`. Vous pouvez définir le paramètre `allow_unicode` à `True`, si vous souhaitez permettre les caractères Unicode : ``` slugify(value, allow_unicode=True) ``` Si `value` contient `"你好 World"`, le résultat sera `"你好-world"`. > **Changed in Django 1.9** > > Le paramètre `allow_unicode` a été ajouté. ## `django.utils.timezone` #### `utc` Instance [`tzinfo`](https://docs.python.org/3/library/datetime.html#datetime.tzinfo) qui représente le temps UTC. #### `class FixedOffset(offset=None, name=None)` Une sous-classe de [`tzinfo`](https://docs.python.org/3/library/datetime.html#datetime.tzinfo) simulant un décalage fixe par rapport au temps UTC. `offset` est un nombre entier de minutes à l’est d’UTC. #### `get_fixed_timezone(offset)` Renvoie une instance [`tzinfo`](https://docs.python.org/3/library/datetime.html#datetime.tzinfo) représentant un fuseau horaire avec un décalage UTC fixe. `offset` est une différence de temps [`datetime.timedelta`](https://docs.python.org/3/library/datetime.html#datetime.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()` Renvoie une instance [`tzinfo`](https://docs.python.org/3/library/datetime.html#datetime.tzinfo) qui représente le [fuseau horaire par défaut](/fr/1.9/topics/i18n/timezones/#default-current-time-zone). #### `get_default_timezone_name()` Renvoie le nom du [fuseau horaire par défaut](/fr/1.9/topics/i18n/timezones/#default-current-time-zone). #### `get_current_timezone()` Renvoie une instance [`tzinfo`](https://docs.python.org/3/library/datetime.html#datetime.tzinfo) qui représente le [fuseau horaire en cours](/fr/1.9/topics/i18n/timezones/#default-current-time-zone). #### `get_current_timezone_name()` Renvoie le nom du [fuseau horaire en cours](/fr/1.9/topics/i18n/timezones/#default-current-time-zone). #### `activate(timezone)` Définit le [fuseau horaire actif](/fr/1.9/topics/i18n/timezones/#default-current-time-zone). Le paramètre `timezone` doit être une instance d’une sous-classe de [`tzinfo`](https://docs.python.org/3/library/datetime.html#datetime.tzinfo) ou, si [pytz](http://pytz.sourceforge.net/) est disponible, un nom de fuseau horaire. #### `deactivate()` Désactive le [fuseau horaire actuel](/fr/1.9/topics/i18n/timezones/#default-current-time-zone). #### `override(timezone)` Gestionnaire de contexte Python qui définit le [fuseau horaire actif](/fr/1.9/topics/i18n/timezones/#default-current-time-zone) lorsqu’il entre en action avec [`activate()`](#django.utils.timezone.activate), puis restaure le fuseau horaire précédemment actif en quittant. Si le paramètre `timezone` vaut `None`, le [fuseau horaire actif](/fr/1.9/topics/i18n/timezones/#default-current-time-zone) est alors désactivé à l’entrée du gestionnaire avec [`deactivate()`](#django.utils.timezone.deactivate). > **Changed in Django 1.8** > > `override` est dorénavant utilisable comme décorateur de fonction. #### `localtime(value, timezone=None)` Convertit un objet [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) conscient vers un fuseau horaire différent, par défaut le [fuseau horaire actif](/fr/1.9/topics/i18n/timezones/#default-current-time-zone). Cette fonction ne fonctionne pas avec des objets date/heure naïfs ; utilisez alors plutôt [`make_aware()`](#django.utils.timezone.make_aware). #### `now()` Renvoie un objet [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) représentant le moment actuel dans le temps (« maintenant »). La valeur précisément renvoyée dépend de la valeur de [`USE_TZ`](/fr/1.9/ref/settings/#std-setting-USE_TZ): - Si [`USE_TZ`](/fr/1.9/ref/settings/#std-setting-USE_TZ) est `False`, il s’agira d’une date/heure [naïve](/fr/1.9/topics/i18n/timezones/#naive-vs-aware-datetimes) (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`](/fr/1.9/ref/settings/#std-setting-USE_TZ) est `True`, il s’agira d’une date/heure [consciente](/fr/1.9/topics/i18n/timezones/#naive-vs-aware-datetimes) représentant le temps actuel en UTC. Notez que [`now()`](#django.utils.timezone.now) renvoie toujours le temps UTC quelle que soit la valeur de [`TIME_ZONE`](/fr/1.9/ref/settings/#std-setting-TIME_ZONE); vous pouvez utiliser [`localtime()`](#django.utils.timezone.localtime) pour convertir vers une date/heure dans le fuseau horaire actif. #### `is_aware(value)` Renvoie `True` si `value` est consciente, `False` si elle est naïve. Cette fonction présuppose que `value` est un objet [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime). #### `is_naive(value)` Renvoie `True` si `value` est naïve, `False` si elle est consciente. Cette fonction présuppose que `value` est un objet [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime). #### `make_aware(value, timezone=None, is_dst=None)` Renvoie un objet [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) conscient représentant le même moment dans le temps que `value` dans le fuseau `timezone`, `value` étant un objet [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) naïf. Si `timezone` est défini à `None`, il prend le [fuseau horaire actuel](/fr/1.9/topics/i18n/timezones/#default-current-time-zone) comme valeur par défaut. Lorsque [pytz](http://pytz.sourceforge.net/) est installée, l’exception `pytz.AmbiguousTimeError` est générée quand on essaie de rendre `value` consciente pendant une transition d’heure d’été/hiver et quand la même heure survient deux fois (passage heure d’été à hiver). En définissant `is_dst` à `True` ou `False`, l’exception est évitée en choisissant si l’heure est celle qui précède ou celle qui suit la transition, respectivement. Lorsque [pytz](http://pytz.sourceforge.net/) est installée, l’exception `pytz.NonExistentTimeError` est générée quand on essaie de rendre `value` consciente pendant une transition d’heure d’été/hiver et quand l’heure concernée ne survient jamais (passage heure d’hiver à été). En définissant `is_dst` à `True` ou `False`, l’exception est évitée en décalant l’heure de 1 heure en arrière ou en avant, respectivement. Par exemple, `is_dst=True` change une heure impossible de 2:30 à 1:30 et `is_dst=False` change la même heure à 3:30. `is_dst` n’a aucun effet si `pytz` n’est pas installée. > **Changed in Django 1.8** > > Dans les versions précédentes de Django, `timezone` était un paramètre obligatoire. > **Changed in Django 1.9** > > Le paramètre `is_dst` a été ajouté. #### `make_naive(value, timezone=None)` Renvoie un objet [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) naïf représentant le même moment dans le temps que `value` dans le fuseau `timezone`, `value` étant un objet [`datetime`](https://docs.python.org/3/library/datetime.html#datetime.datetime) conscient. Si `timezone` est défini à `None`, il prend le [fuseau horaire actuel](/fr/1.9/topics/i18n/timezones/#default-current-time-zone) comme valeur par défaut. > **Changed in Django 1.8** > > Dans les versions précédentes de Django, `timezone` était un paramètre obligatoire. ## `django.utils.translation` Pour une discussion complète sur l’utilisation de ce qui suit, consultez la [documentation sur la traduction](/fr/1.9/topics/i18n/translation/). #### `gettext(message)` Traduit `message` et renvoie le résultat dans une chaîne d’octets UTF-8 #### `ugettext(message)` Traduit `message` et renvoie le résultat dans une chaîne unicode #### `pgettext(context, message)` Traduit `message` selon `context` et renvoie le résultat dans une chaîne unicode. Pour plus d’informations, voir [Marqueurs contextuels](/fr/1.9/topics/i18n/translation/#contextual-markers). #### `gettext_lazy(message)` #### `ugettext_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. Voir [la documentation sur les traductions différées](/fr/1.9/topics/i18n/translation/#lazy-translations). #### `gettext_noop(message)` #### `ugettext_noop(message)` 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)` Traduit `singular` et `plural` et renvoie la chaîne appropriée en fonction de `number` dans une chaîne d’octets UTF-8. #### `ungettext(singular, plural, number)` Traduit `singular` et `plural` et renvoie la chaîne appropriée en fonction de `number` dans une chaîne unicode. #### `npgettext(context, singular, plural, number)` Traduit `singulier` et `pluriel` et renvoie la chaîne appropriée en fonction de `nombre` et de `context` dans une chaîne unicode. #### `ngettext_lazy(singular, plural, number)` #### `ungettext_lazy(singular, plural, number)` #### `npgettext_lazy(context, singular, plural, number)` Même comportement que les versions non différées ci-dessus, mais en utilisant une exécution différée. Voir [la documentation sur les traductions différées](/fr/1.9/topics/i18n/translation/#lazy-translations). #### `string_concat(*strings)` Variante différée de la concaténation de chaînes, nécessaire pour les traductions qui sont formées de plusieurs parties. #### `activate(language)` 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()` 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()` 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)` Un gestionnaire de contexte Python qui utilise [`django.utils.translation.activate()`](#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ètre `deactivate` à `True` si l’on souhaite que la langue de traduction temporaire soit simplement désactivée à la sortie du gestionnaire avec [`django.utils.translation.deactivate()`](#django.utils.translation.deactivate). Si le paramètre `language` vaut `None`, une instance de `NullTranslations()` est activée dans le code affecté par le gestionnaire de contexte. > **Changed in Django 1.8** > > `override` est dorénavant utilisable comme décorateur de fonction. #### `check_for_language(lang_code)` 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()` Renvoie le code de langue actuellement sélectionné. Renvoie `None` si les traductions sont temporairement désactivées (par [`deactivate_all()`](#django.utils.translation.deactivate_all) ou lorsque `None` est passé à [`override()`](#django.utils.translation.override)). > **Changed in Django 1.8** > > Avant Django 1.8, `get_language()` renvoyait toujours [`LANGUAGE_CODE`](/fr/1.9/ref/settings/#std-setting-LANGUAGE_CODE) lorsque les traductions étaient désactivées. #### `get_language_bidi()` Renvoie l’agencement bidirectionnel de la langue sélectionnée : - `False` = agencement de gauche à droite - `True` = agencement de droite à gauche #### `get_language_from_request(request, check_path=False)` 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` vaut `True`, la fonction examine d’abord l’URL demandée pour voir si son chemin commence par un code de langue figurant dans le réglage [`LANGUAGES`](/fr/1.9/ref/settings/#std-setting-LANGUAGES). #### `to_locale(language)` Transforme un nom de langue (en-us) en un nom de locale (en\_US). #### `templatize(src)` Transforme un gabarit Django en un contenu analysable par `xgettext`. Ce processus traduit les balises de traduction de Django en invocations de fonctions `gettext` standard. #### `LANGUAGE_SESSION_KEY` Clé de session servant à stocker la langue active de la session en cours.