# Documentation Django 5.2.8

# Données Unicode

Django prend en charge l’Unicode partout.

Ce document présente ce qu’il faut savoir si vous écrivez des applications qui utilisent des données ou des gabarits qui sont codés dans d’autres formats que l’ASCII.

## Création de la base de données

Assurez-vous que la base de données que vous utilisez est configurée pour pouvoir stocker des données textuelles arbitraires. Normalement, cela implique de permettre les données codées en UTF-8 ou UTF-16. Si vous utilisez un codage plus limité, par exemple latin1 (iso8859-1), vous ne pourrez pas stocker certains caractères dans la base de données et des informations seront perdues.

- Les utilisateurs de MySQL doivent se référer au manuel MySQL pour des détails sur la façon de définir ou de modifier le codage de caractères.

- Pour les utilisateurs de PostgreSQL, référez-vous au manuel PostgreSQL pour plus de détails sur la création de bases de données avec le bon codage.

- Les utilisateurs d’Oracle doivent se référer au manuel Oracle pour des détails sur la façon de définir (section 2) ou de modifier (section 11) le codage de caractères de la base de données.

- Il n’y a rien à savoir pour les utilisateurs de SQLite. SQLite utilise toujours UTF-8 pour son codage interne.

Tous les moteurs de base de données de Django convertissent automatiquement les chaînes dans le codage convenant au dialogue avec la base de données. Ils convertissent aussi automatiquement les chaînes chargées de la base de données dans des chaînes. Vous n’avez même pas besoin de dire à Django le codage utilisé par la base de données : tout est géré de manière transparente.

Pour en savoir plus, lisez la section « L’API de base de données » ci-dessous.

## Traitement général des chaînes

Chaque fois que vous utilisez des chaînes de caractères avec Django, par ex. dans des interrogations en base de données, dans l’affichage des gabarits ou partout ailleurs, vous avez deux choix pour le codage de ces chaînes. Vous pouvez utiliser des chaînes normales ou des chaînes d’octets (bytestrings, commençant par `b'`).

Avertissement

Une chaîne d’octets ne comporte aucune information en elle-même à propos de son codage. Pour cette raison, il faut se baser sur une supposition lors de leur interprétation et Django suppose que toutes les chaînes d’octets sont en UTF-8.

Si vous passez à Django une chaîne qui a été codée dans un autre format, des choses bizarres risquent bien de se produire. En principe, Django produira une exception `UnicodeDecodeError` à un moment ou à un autre.

Si votre code n’utilise que des données ASCII, vous pouvez sans problème faire transiter des chaînes normales dans la mesure où l’ASCII est un sous-ensemble de UTF-8.

Ne vous méprenez pas en pensant qu’en définissant le réglage `DEFAULT_CHARSET` à quelque chose d’autre que `'utf-8'` vous pourrez utiliser cet autre codage dans vos chaînes d’octets. `DEFAULT_CHARSET` ne s’applique qu’aux chaînes produites par l’affichage des gabarits (et des courriels). Django suppose toujours que les chaînes d’octets internes sont en UTF-8. La raison en est que le réglage `DEFAULT_CHARSET` n’est pas vraiment sous votre contrôle (si vous êtes développeur d’application). Il est plutôt sous le contrôle de la personne installant et utilisant votre application, et si cette personne choisit un réglage différent, votre code doit continuer de fonctionner. En conséquence, Django ne peut pas se baser sur ce réglage.

Dans la plupart des cas, quand Django traite des chaînes, il les convertit en chaînes avant toute chose. Ainsi en règle générale, si vous transmettez une chaîne d’octets, ne soyez pas surpris de recevoir une chaîne en retour.

### Chaînes traduites

À part les chaînes et les chaînes d’octets, il existe un troisième type d’objet apparenté aux chaînes que l’on peut rencontrer en utilisant Django. Le système d’internationalisation introduit le concept de « traduction différée », une chaîne marquée comme traduite mais dont le résultat traduit n’est déterminé qu’au moment où l’objet est réellement utilisé comme chaîne. Cette fonctionnalité est utile dans les cas où la langue de traduction n’est connue qu’au moment de l’utilisation de la chaîne, alors que l’objet chaîne peut avoir été initialement créé au moment de la première importation du code.

Il n’y a normalement pas besoin de se préoccuper des traductions différées. Il faut juste savoir que si l’on examine un objet et que celui-ci s’identifie comme objet `django.utils.functional.__proxy__`, il s’agit d’une traduction différée. En appelant `str()` avec la traduction différée en paramètre, une chaîne sera produite dans la langue actuellement active.

Pour plus de détails sur les objets de traduction différée, référez-vous à la documentation sur l’internationalisation.

### Fonctions utilitaires

Comme certaines opérations sur les chaînes reviennent fréquemment, Django fournit quelques fonctions utiles qui devraient faciliter quelque peu la manipulation d’objets chaînes et chaînes d’octets.

#### Fonctions de conversion

Le module `django.utils.encoding` contient quelques fonctions bien pratiques pour la conversion entre chaînes et chaînes d’octets.

- `smart_str(s, encoding='utf-8', strings_only=False, errors='strict')` convertit son premier paramètre en chaîne. Le paramètre `encoding` définit le codage en entrée. Par exemple, Django utilise cette fonction en interne lorsqu’il traite des données de saisies de formulaires qui pourraient ne pas être codées en UTF-8. Le paramètre `strings_only`, lorsqu’il vaut `True`, évite que les contenus Python de type nombre, booléen et `None` ne soient convertis en chaînes de caractères (ils conservent leur type de base). Le paramètre `errors` accepte les mêmes valeurs que la fonction Python `str()` pour sa gestion d’erreurs.

- `force_str(s, encoding='utf-8', strings_only=False, errors='strict')` est identique à `smart_str()` dans presque tous les cas. La différence est quand le premier paramètre est une instance de traduction différée. Alors que `smart_str()` préserve les traductions différées, `force_str()` force ces objets en chaînes (provoquant le processus de traduction). Normalement, c’est plutôt `smart_str()` qui est souhaité. Cependant, `force_str()` est utile dans les balises et filtres de gabarits qui doivent absolument obtenir une chaîne à traiter, et pas simplement quelque chose qui peut être converti en une chaîne.

- `smart_bytes(s, encoding='utf-8', strings_only=False, errors='strict')` est essentiellement l’inverse de `smart_str()`. Elle force le premier paramètre à une chaîne d’octets. Le paramètre `strings_only` se comporte comme pour `smart_str()` et `force_str()`. La sémantique est légèrement différente de la fonction Python intégrée `str()`, mais cette différence est nécessaire à quelques endroits dans le code interne de Django.

Normalement vous n’aurez besoin que de `force_str()`. Appelez-la aussi tôt que possible pour toute donnée saisie qui peut indifféremment être une chaîne ou une chaîne d’octets, et à partir de cet instant, vous pouvez traiter le résultat comme étant toujours une chaîne.

#### Traitement d’URI et d’IRI

Les infrastructures web doivent gérer des URL (qui sont un type d’IRI). L’une des exigences quant aux URL est qu’elles ne doivent être codées qu’avec des caractères ASCII. Cependant, dans un environnement international, il peut être nécessaire de construire une URL à partir d’une IRI – dit de manière très raccourcie, une URI contenant des caractères Unicode. Utilisez ces fonctions pour le codage et la conversion d’IRI vers une URI :

- The `django.utils.encoding.iri_to_uri()` function, which implements the conversion from IRI to URI as required by RFC 3987 Section 3.1.

- Les fonctions `urllib.parse.quote()` et `urllib.parse.quote_plus()` de la bibliothèque Python standard.

Ces deux groupes de fonctions ont des objectifs légèrement différents, et il est important de bien les différencier. Normalement, on utilise `quote()` sur des parties individuelles de chemins d’IRI et d’URI afin que tout caractère réservé tels que « & » ou « % » soit codé correctement. Puis, on applique `iri_to_uri()` à l’IRI complète pour que tout caractère non ASCII soit converti dans les bonnes valeurs codées.

Note

Techniquement, il est incorrect de dire que `iri_to_uri()` implémente l’algorithme complet de la spécification IRI. Elle n’implémente pas (encore) la partie de codage des noms de domaine internationalisés de l’algorithme.

La fonction `iri_to_uri()` ne touche pas aux caractères ASCII qui sont normalement autorisés dans les URL. Ainsi, par exemple, le caractère « % » n’est pas recodé lorsqu’il est transmis à `iri_to_uri()`. Cela signifie que vous pouvez transmettre une URL complète à cette fonction et qu’elle ne corrompra pas la chaîne de requête ou toute autre partie.

Un exemple va clarifier les choses :

    >>> from urllib.parse import quote
    >>> from django.utils.encoding import iri_to_uri
    >>> quote("Paris & Orléans")
    'Paris%20%26%20Orl%C3%A9ans'
    >>> iri_to_uri("/favorites/François/%s" % quote("Paris & Orléans"))
    '/favorites/Fran%C3%A7ois/Paris%20%26%20Orl%C3%A9ans'

Si vous regardez attentivement, vous pouvez voir que la portion générée par `quote()` dans le deuxième exemple n’a pas été doublement échappée lors de son passage dans `iri_to_uri()`. Il s’agit d’une fonctionnalité importante et utile. Cela signifie que vous pouvez construire des IRI sans vous soucier de la présence de caractères non ASCII, puis, tout à la fin, appeler `iri_to_uri()` sur le résultat.

Similarly, Django provides `django.utils.encoding.uri_to_iri()` which implements the conversion from URI to IRI as per RFC 3987 Section 3.2.

Un exemple pour démontrer cela :

    >>> from django.utils.encoding import uri_to_iri
    >>> uri_to_iri("/%E2%99%A5%E2%99%A5/?utf8=%E2%9C%93")
    '/♥♥/?utf8=✓'
    >>> uri_to_iri("%A9hello%3Fworld")
    '%A9hello%3Fworld'

Dans le premier exemple, les caractères UTF-8 sont décodés. Dans le second, le codage en pour-cent reste inchangé car le résultat serait hors de la plage UTF-8 valide ou qu’il représenterait un caractère réservé.

Les fonctions `iri_to_uri()` et `uri_to_iri()` sont toutes deux idempotentes, ce qui signifie que l’assertion suivante est toujours vraie :

    iri_to_uri(iri_to_uri(some_string)) == iri_to_uri(some_string)
    uri_to_iri(uri_to_iri(some_string)) == uri_to_iri(some_string)

Vous pouvez donc sans crainte l’appeler plusieurs fois sur le même contenu URI/IRI sans risquer d’éventuels problèmes de double échappement.

## Modèles

Comme toutes les chaînes sont renvoyées de la base de données sous forme d’objets `str`, les champs de modèles basés sur des caractères (CharField, TextField, URLField, etc.) contiennent des valeurs Unicode lorsque Django récupère des données à partir de la base de données. C’est toujours le cas, même si les données pourraient convenir pour une chaîne d’octets ASCII.

Vous pouvez passer des chaînes d’octets lors de la création d’un modèle ou de l’attribution d’une valeur à un champ, et Django se charge de les convertir en chaînes au moment où c’est nécessaire.

### Précautions dans `get_absolute_url()`

Les URL ne peuvent contenir que des caractères ASCII. Si vous construisez une URL à partir de morceaux de données pas forcément ASCII, prenez soin de coder le résultat d’une façon qui convienne à une URL. La fonction `reverse()` se charge automatiquement de cela à votre place.

Si vous construisez une URL manuellement (c’est-à-dire sans utiliser la fonction `reverse()`), vous devrez vous charger vous-même du codage. Dans ce cas, utilisez les fonctions `iri_to_uri()` et `quote()` qui ont été documentées ci-dessus. Par exemple :

    from urllib.parse import quote
    from django.utils.encoding import iri_to_uri

    def get_absolute_url(self):
        url = "/person/%s/?x=0&y=0" % quote(self.location)
        return iri_to_uri(url)

Cette fonction renvoie une URL correctement codée, même si `self.location` contient quelque chose comme « Jack a visité Paris & Orléans ». En fait, l’appel à `iri_to_uri()` n’est pas absolument nécessaire dans l’exemple ci-dessus, car tous les caractères non ASCII auront été remplacés durant l’échappement à la première ligne.

## Gabarits

Utilisez des chaînes lors de la création manuelle de gabarits :

    from django.template import Template

    t2 = Template("This is a string template.")

But the common case is to read templates from the filesystem. If your template files are not stored with a UTF-8 encoding, adjust the `TEMPLATES` setting. The built-in `django` backend provides the `'file_charset'` option to change the encoding used to read files from disk.

Le réglage `DEFAULT_CHARSET` contrôle le codage des gabarits produits. Il est défini par défaut à UTF-8.

### Balises et filtres de gabarit

Quelques astuces à garder en tête lors de l’écriture de vos propres balises et filtres de gabarits :

- Toujours renvoyer des chaînes à partir de la méthode `render()` d’une balise de gabarit et à partir des filtres de gabarit.

- Préférer l’utilisation de `force_str()` à `smart_str()` à ces endroits. La production de balises et l’appel aux filtres se produisent lors de la phase de rendu des gabarits, il n’y a donc pas d’avantage à différer la conversion d’objets de traduction différée en chaînes. Il est plus simple de travailler uniquement avec des chaînes à ce stade.

## Fichiers

Si vous prévoyez de permettre aux utilisateurs d’envoyer des fichiers, vous devez vous assurer que l’environnement utilisé pour faire fonctionner Django est bien configuré pour fonctionner avec des noms de fichiers non ASCII. Si votre environnement n’est pas configuré correctement, vous allez recevoir des exceptions `UnicodeEncodeError` lors de l’enregistrement de fichiers ou de contenu dont le nom contient des caractères non ASCII.

La prise en charge de noms de fichiers UTF-8 par le système de fichiers est variable et peut dépendre de l’environnement. Contrôlez votre configuration actuelle dans un shell Python interactif en exécutant :

    import sys

    sys.getfilesystemencoding()

Cela devrait afficher « UTF-8 ».

Sur les plates-formes Unix, c’est la variable d’environnement `LANG` qui est responsable de définir le codage souhaité. Consultez la documentation de votre système d’exploitation et de votre serveur d’applications pour la syntaxe et l’emplacement appropriés pour définir cette variable. Consultez Django avec Apache et mod_wsgi pour voir des exemples.

Dans votre environnement de développement, il pourrait être nécessaire d’ajouter un réglage à votre fichier `~.bashrc` du style :

    export LANG="en_US.UTF-8"

## Envoi de formulaire

L’envoi de formulaire HTML est un domaine délicat. Il n’existe aucune garantie que les données envoyées contiennent des informations sur le codage, ce qui signifie que le système peut avoir à deviner le codage de ces données.

Django adopte une approche « différée » du décodage des données de formulaires. Les données d’un objet `HttpRequest` ne sont décodées qu’au moment où l’on tente d’y accéder. En fait, la plupart des données ne sont même pas décodées du tout. Le décodage ne s’applique qu’aux seules structures de données `HttpRequest.GET` et `HttpRequest.POST`. Ces deux champs renvoient leur contenu sous forme de données Unicode. Tous les autres attributs et méthodes de `HttpRequest` renvoient les données exactement comme elles ont été envoyées par le client.

Par défaut, le réglage `DEFAULT_CHARSET` est utilisé comme le codage supposé des données de formulaires. Si vous avez besoin de le modifier pour un formulaire particulier, vous pouvez définir l’attribut `encoding` de l’instance `HttpRequest`. Par exemple :

    def some_view(request):
        # We know that the data must be encoded as KOI8-R (for some reason).
        request.encoding = "koi8-r"
        ...

Il est même possible de modifier le codage après avoir accédé à `request.GET` ou `request.POST`, et tous les accès suivants utiliseront le nouveau codage.

Il n’est généralement pas nécessaire de se préoccuper de modifier le codage des formulaires, mais c’est une fonctionnalité utile lorsque des applications doivent communiquer avec des systèmes existants dont on ne maîtrise pas le codage.

Django ne décode pas les données des téléversements de fichiers, car les données sont normalement considérées comme des suites d’octets et pas comme des chaînes. Tout décodage automatique à ce niveau pourrait altérer la signification du flux d’octets.