Pour décoder un flux UTF-8 en Python, conservez le même décodeur incrémental pendant toute la lecture. Un bloc d’octets peut s’arrêter au milieu d’un caractère : le décodeur garde cette fin incomplète jusqu’au bloc suivant. À la véritable fin du flux, appelez decode(b"", final=True) pour refuser une séquence qui resterait tronquée.
Cette précaution concerne notamment les programmes qui reçoivent progressivement un texte, avant son affichage ou son analyse. Elle intervient à la frontière entre les octets et une chaîne Python. Un assistant qui produit une réponse correcte ne peut pas empêcher un consommateur de l’abîmer à cette étape.
Réponse en bref
Recevez les blocs sous forme de bytes, passez-les à une instance créée avec codecs.getincrementaldecoder("utf-8")(errors="strict"), puis transmettez les fragments de texte obtenus au lecteur de votre protocole. Terminez explicitement le décodage quand l’entrée est entièrement consommée. Une fin de bloc, un délai et une fin de réponse sont trois événements différents.
Votre premier geste : cherchez un bloc.decode("utf-8") dans la boucle qui lit votre flux. Exécutez ensuite l’exercice ci-dessous en coupant les octets à chaque position. Le texte reconstitué doit rester identique, quelle que soit la répartition des octets entre les blocs.
Une coupure de transport ne dessine pas une lettre
Le guide Unicode de Python distingue une chaîne de texte de sa représentation encodée. Dans notre exercice, Aé€🧭Z contient cinq points de code et occupe onze octets en UTF-8. Le nombre affiché par len dépend donc de l’objet auquel vous l’appliquez : la chaîne ou sa représentation en octets.
Le choix de ces signes est volontaire. Il permet de rencontrer des séquences de plusieurs longueurs dans un support minuscule. Le texte est entièrement fictif ; il ne représente ni une réponse enregistrée d’un modèle ni un résultat métier. La RFC 3629 décrit les séquences de une à quatre unités utilisées par UTF-8.
| Signe de l’exercice | Octets hexadécimaux | Longueur de la séquence |
|---|---|---|
| A | 41 | 1 |
| é | c3 a9 | 2 |
| € | e2 82 ac | 3 |
| 🧭 | f0 9f a7 ad | 4 |
| Z | 5a | 1 |
Supposons que le premier bloc s’arrête après c3. Cet octet commence la représentation de é, mais ne la termine pas. Déclarer ce bloc comme un document complet provoque un refus légitime. Le défaut vient de la frontière choisie par le programme, alors que les onze octets de l’entrée sont valides lorsqu’ils sont réunis.
Découper le texte en blocs plus gros peut masquer l’erreur pendant une démonstration. Cela ne donne pas au consommateur un contrat sur les frontières futures. Un changement de lecteur, de taille de tampon ou de comportement du réseau pourrait faire réapparaître le défaut sans modifier le contenu envoyé.
Placer la conversion à la bonne couche
Le laboratoire commence avec les octets du texte à décoder. Il ne lit pas une connexion chiffrée, une compression ou des trames de transport. Dans une application, identifiez ce que fournit effectivement votre bibliothèque : des octets de corps déjà décompressés, du texte, des lignes, ou des événements déjà interprétés.
Si le composant vous remet une chaîne str, la conversion étudiée ici a déjà eu lieu. La réencoder puis la redécoder ajoute une transformation sans restaurer les octets originaux. Placez le contrôle au premier composant qui possède réellement les octets, ou utilisez le lecteur de texte incrémental documenté de votre bibliothèque.
Le standard Server-sent events de WHATWG décrit un flux UTF-8 et des règles supplémentaires d’interprétation. Obtenir des caractères ne suffit donc pas à reconnaître un événement SSE. Une ligne, un champ data et la terminaison d’un événement appartiennent à cette autre lecture.
De même, un fragment décodé n’est pas nécessairement un document JSON complet. Il peut contenir seulement le début d’une chaîne ou la moitié d’un objet. Gardez le décodage des caractères, l’assemblage du message et son analyse syntaxique dans des étapes identifiables. Vous saurez ainsi quelle couche doit refuser une entrée et laquelle peut encore attendre sa suite.
Faire vivre un décodeur aussi longtemps que l’entrée
La documentation de codecs expose une fabrique de décodeurs incrémentaux. Le résultat conserve un état entre deux appels. Le codec UTF-8 de CPython utilise précisément un décodeur avec tampon pour ce travail.
Créez une instance par flux logique. La recréer dans chaque tour de boucle supprimerait la mémoire de la séquence commencée au tour précédent. La partager entre deux réponses indépendantes pourrait, inversement, faire terminer le caractère de la première avec les octets de la seconde. L’état doit suivre l’entrée, sans être attaché à un utilisateur ou à un worker réutilisable.
Choisir errors="strict" rend les défauts visibles : une séquence illégale déclenche une exception. Une séquence encore susceptible d’être complétée peut rester en attente pendant la lecture. L’absence de texte à un appel ne prouve donc ni une absence de données reçues ni une fin de production.
Nous ajoutons une enveloppe de 4 096 octets pour rendre ce petit exemple maîtrisable. Il s’agit d’un plafond pédagogique sur le total fourni à la fonction. Il ne limite pas une réponse avant sa réception et ne remplace pas une borne dans le lecteur amont. Le programme suppose des blocs bytes et un plafond entier positif choisi par son appelant.
Exécuter le laboratoire des onze octets
Le bloc suivant se copie dans un fichier Python vide. Il n’installe aucune dépendance, ne contacte aucun serveur et ne produit aucun effet externe. La fonction génère du texte progressivement ; les assertions le réunissent seulement pour comparer le résultat final à une référence indépendante des coupures.
import codecs
def iter_utf8(blocs, *, maximum=4096):
decodeur = codecs.getincrementaldecoder("utf-8")(errors="strict")
total = 0
for bloc in blocs:
if type(bloc) is not bytes:
raise TypeError("octets_requis")
total += len(bloc)
if total > maximum:
raise ValueError("plafond_octets")
texte = decodeur.decode(bloc, final=False)
if texte:
yield texte
dernier = decodeur.decode(b"", final=True)
if dernier:
yield dernier
attendu = "Aé€🧭Z"
brut = attendu.encode("utf-8")
assert brut.hex(" ") == "41 c3 a9 e2 82 ac f0 9f a7 ad 5a"
assert len(brut) == 11
for coupure in range(len(brut) + 1):
blocs = [brut[:coupure], brut[coupure:]]
assert "".join(iter_utf8(blocs)) == attendu
assert "".join(iter_utf8(bytes([b]) for b in brut)) == attendu
assert "".join(iter_utf8([b"", brut, b""])) == attendu
assert "".join(iter_utf8([])) == ""
assert "".join(iter_utf8([brut], maximum=11)) == attendu
for mauvais in [b"\xff", b"\xc0\xaf", b"\xed\xa0\x80", b"\xf4\x90\x80\x80"]:
try:
"".join(iter_utf8([mauvais]))
except UnicodeDecodeError:
pass
else:
raise AssertionError("Sequence invalide acceptee")
for tronque in [b"\xc3", b"\xe2\x82", b"\xf0\x9f\xa7"]:
try:
"".join(iter_utf8([b"debut ", tronque]))
except UnicodeDecodeError:
pass
else:
raise AssertionError("Fin incomplete acceptee")
try:
"".join(iter_utf8([brut], maximum=10))
except ValueError as erreur:
assert str(erreur) == "plafond_octets"
else:
raise AssertionError("Plafond depasse")
print("12 coupures, blocs unitaires, fermetures et refus : OK")
Ce code a été exécuté sur CPython 3.14.3. Le manuel de la branche 3.14 consulté affiche 3.14.10 ; ne confondez pas la version du document avec celle de votre interpréteur. Les assertions de démonstration servent au banc d’essai. Les refus de la fonction utilisent des exceptions explicites, même si les assertions sont désactivées par l’interpréteur.
Les douze coupures incluent les deux extrémités : un premier bloc vide ou un second bloc vide. Certaines coupures tombent entre deux caractères et d’autres à l’intérieur de leurs octets. Toutes doivent produire le même texte. L’essai en blocs unitaires impose ensuite le cas où chaque octet arrive séparément.
Lire séparément l’attente et la fermeture
Pendant les appels ordinaires, final=False indique qu’une suite reste possible. Après réception de b"\xe2\x82", le décodeur strict ne peut pas encore produire le signe euro, mais peut attendre son troisième octet. Recevoir ensuite b"\xac" complète la séquence et autorise sa conversion en €.
L’appel avec final=True retire cette possibilité d’attendre. Si les octets manquants ne sont jamais arrivés, l’entrée est incomplète et le mode strict la refuse. Oublier cette étape pourrait laisser une application annoncer une réussite après avoir simplement abandonné les derniers octets non décodés.
Dans le laboratoire, la fin de l’itérable représente la véritable fin des octets à traiter. Une itération vide n’est pas ce signal : b"" reste un bloc admissible et n’arrête pas la fonction. De même, le décodeur n’interprète aucun délai. Le composant qui lit le réseau doit distinguer attente temporaire, annulation, erreur et épuisement normal de son entrée.
Un arrêt peut aussi survenir exactement entre deux caractères. Le décodage se termine alors sans erreur, même si le message métier est incomplet. La phrase « Prévoir » est un UTF-8 valide ; sa validité ne prouve pas que la réponse attendue « Prévoir deux salles » a été reçue en entier. Cette complétude doit être vérifiée au niveau du protocole ou du contrat applicatif.
Résister aux corrections qui font disparaître le défaut
Le mode ignore supprime les portions qu’il ne parvient pas à décoder. Le mode replace insère un caractère de remplacement. Sur une interface de lecture tolérante, une politique explicite de substitution peut avoir un sens. Pour vérifier la conservation exacte du texte, ces deux stratégies changent toutefois la question posée au test.
Si vous appliquez une telle correction à chaque bloc indépendant, un seul caractère réparti sur plusieurs blocs peut être supprimé ou remplacé plusieurs fois. Le programme obtient alors une chaîne affichable, tandis que son contenu dépend des coupures. Un test réduit à « aucune exception » manquerait précisément cette corruption.
La même prudence s’applique au changement automatique d’encodage. Une entrée refusée en UTF-8 peut souvent être transformée avec un autre codec, sans que ce codec corresponde à celui de l’expéditeur. Notre fonction ne devine rien : elle applique le contrat UTF-8 annoncé. Une incohérence remonte au composant responsable au lieu d’être transformée en texte apparemment acceptable.
Refuser le flux ne retire pas forcément ce qu’un consommateur a déjà affiché. La fonction est un générateur : elle peut émettre un préfixe correct avant de rencontrer une erreur. Si le texte alimente une décision, gardez cet état provisoire visible et attendez les validations nécessaires avant d’enregistrer un résultat définitif.
Changer toutes les frontières sans changer l’oracle
Les douze essais simples ne couvrent qu’une coupure à la fois. Notre entrée de onze octets possède dix frontières intérieures. En choisissant de couper ou non à chacune, on obtient 1 024 partitions contiguës en blocs non vides. Un banc complémentaire a parcouru ces partitions : la concaténation du texte est restée égale à Aé€🧭Z dans chaque cas.
Cet oracle reste la chaîne attendue, écrite avant le découpage. Il ne reprend ni les fragments retournés par la fonction ni un texte préalablement « réparé ». Ajoutez des blocs vides entre les fragments pour vérifier qu’ils ne deviennent pas une fausse terminaison. Répétez ensuite avec une séquence illégale, pour éviter qu’une fonction acceptant tout passe le test.
| Famille d’essai | Résultat exigé | Défaut recherché |
|---|---|---|
| entrée valide, frontières déplacées | texte strictement identique | dépendance au découpage |
| dernière séquence incomplète | refus à la fermeture | abandon du tampon final |
| octet de continuation isolé | refus | admission d’une séquence impossible |
| séquence surlongue ou valeur interdite | refus | interprétation permissive |
| entrée de onze octets, plafond dix | refus de l’enveloppe | limite contrôlée trop tard |
| deux flux indépendants | deux instances distinctes | état partagé entre réponses |
Pour examiner l’attente sans la confondre avec du texte reçu, getstate() expose notamment les octets non décodés. Gardez cet outil pour un diagnostic local sur les données fictives. Il n’est pas nécessaire de journaliser le tampon brut d’une réponse réelle pour prouver que votre programme termine correctement sa lecture.
Situer le refus sans inventer une position globale
Une erreur comporte plusieurs repères qui ne répondent pas à la même question. Le total reçu indique le nombre d’octets fournis par l’appelant. Le numéro du bloc désigne une livraison dans ce découpage particulier. Le texte déjà émis décrit ce que le consommateur a pu afficher. Aucun de ces compteurs ne correspond automatiquement à la position d’un caractère dans une phrase.
La documentation des exceptions Unicode définit notamment object, start, end et reason. Les indices se rapportent à l’objet ayant causé l’exception. Dans un décodage incrémental, cet objet peut réunir des octets gardés en tampon et ceux du nouvel appel. Traiter start comme un décalage absolu dans toute la réponse donnerait donc une localisation trompeuse.
Prenons un préfixe ASCII déjà traité, suivi du seul octet c3. Le décodeur peut garder ce dernier en attente. Si la fermeture intervient immédiatement, l’objet en erreur porte cette séquence incomplète, et son indice local commence à zéro. Cela ne veut pas dire que le premier octet de la réponse entière était défectueux : l’erreur se situe après le préfixe.
Pour votre diagnostic, enregistrez d’abord la phase : alimentation ordinaire, fermeture ou refus du plafond. Conservez un identifiant de lecture opaque et des compteurs utiles, plutôt qu’une copie systématique du texte. Si vous avez besoin d’une position globale en octets, définissez son calcul à partir des octets déjà consommés et vérifiez-le avec un défaut à plusieurs emplacements connus.
Déplacez ensuite les frontières tout en gardant la séquence fautive au même endroit dans l’entrée complète. Un diagnostic global bien défini doit retrouver cet emplacement. Le numéro de bloc, lui, changera normalement. Cette séparation évite de présenter à un collègue une « erreur au caractère 2 » alors que le programme connaît seulement un indice local dans un tampon d’octets.
Passer un texte entier au bon consommateur
Quand l’objectif est une réponse unique courte, réunir les fragments puis valider le résultat peut être plus lisible qu’une interface complexe. Cela conserve la mémoire de tout le texte et exige donc une enveloppe adaptée. Si l’objectif est un affichage progressif, transmettez les fragments sans prétendre que chacun constitue une phrase ou un message complet.
Pour un JSON, poursuivez avec un assembleur respectant votre protocole, puis un parseur qui contrôle les noms répétés et les nombres. La réussite UTF-8 n’autorise pas à sauter cette étape. Le générateur accepte par exemple un texte quelconque qui ne comporte aucune structure JSON.
Si vous rapprochez ensuite des libellés, la normalisation Unicode et la gestion des collisions traitent un autre problème, sur des chaînes déjà obtenues. Notre fonction conserve les points de code ; elle ne décide pas que deux écritures sont équivalentes. Elle ne fusionne aucun identifiant et ne corrige aucune formulation.
Dans un projet d’automatisation IA, le livrable utile est une petite carte des frontières : ce qui reçoit les octets, ce qui les décode, ce qui reconnaît les messages et ce qui accepte leur contenu. Ajoutez à cette carte vos cas de coupure et vos règles de fin. Vous pourrez alors modifier une couche sans attribuer à la suivante une garantie qu’elle n’a jamais fournie.
Limites
Ce décodeur ne répare pas un octet perdu, ne réordonne pas une entrée et ne détecte pas une réponse écourtée sur une frontière de caractères valide. Il ne gère ni décompression, ni reconnexion, ni délimitation des événements. La politique de BOM dépend du protocole ; le codec utf-8 employé ici conserve un éventuel caractère initial U+FEFF au lieu de le retirer.
Un point de code complet n’est pas toujours un symbole visuel complet : accents combinants et séquences d’emoji peuvent demander un traitement d’affichage supplémentaire. Le plafond total borne l’enveloppe de ce laboratoire, sans borner les allocations déjà réalisées en amont. Un consommateur qui cesse d’itérer avant la fin n’exécute pas la fermeture du générateur et ne peut pas conclure à la validité de l’entrée entière.
Historique des mises à jour
- 5 novembre 2026 : publication de l’exercice UTF-8, du décodeur strict et des essais sur les frontières, les entrées invalides et la fin de flux.
Sources vérifiées
- codecs : Codec registry and base classes, Python 3.14 , consultée le 5 novembre 2026
- Unicode HOWTO, Python 3.14 , consultée le 5 novembre 2026
- CPython 3.14 : encodings/utf_8.py , consultée le 5 novembre 2026
- RFC 3629 : UTF-8, a transformation format of ISO 10646 , consultée le 5 novembre 2026
- HTML Living Standard : Server-sent events , consultée le 5 novembre 2026
- Built-in Exceptions : UnicodeError, Python 3.14 , consultée le 5 novembre 2026