Définir les modes d’encodage du code QR en Python

Chaque générateur de QR choisit un mode d’encodage par défaut, et la plupart du temps ce défaut convient. Il cesse d’être adéquat dès que vous avez besoin de le contrôler — un ID numérique à côté d’un code produit, un bloc de texte japonais que vous ne voulez pas stocker en UTF-8, ou une charge utile où vous avez besoin des mêmes octets à chaque génération. Ce guide montre comment définir les modes d’encodage du code QR en Python explicitement, en utilisant Aspose.BarCode for Python via .NET, afin qu’un seul symbole QR puisse contenir un segment numérique, un segment alphanumérique, un segment d’octets et un segment Kanji — chacun stocké dans le mode qui lui convient le mieux.

Aspose.BarCode appelle ces modes de compaction dans ses propres noms d’API (QrExtCompactionMode) et la spécification QR les désigne comme modes de codage. Ce sont les mêmes quatre modes sous deux noms, et ce guide utilise “mode de codage” tout au long, car c’est le terme utilisé par la spécification et la plupart des bibliothèques QR Python.

Pourquoi les modes d’encodage QR affectent la taille du symbole et la fiabilité du scan

La taille physique d’un code QR est déterminée par le nombre de bits nécessaires à sa charge utile, et le nombre de bits par caractère dépend entièrement du mode d’encodage utilisé pour ce segment. La spécification définit quatre modes de données avec des densités nettement différentes :

Un identifiant de 30 chiffres coûte environ 100 bits en mode numérique et 240 bits en mode octet. Cet écart suffit souvent à faire passer le symbole à plusieurs versions QR, et une version supérieure signifie plus de modules dans la même zone imprimée — des modules plus petits, et un taux de lecture plus faible avec des caméras basse résolution, des emballages courbés et des étiquettes usées.

La sélection automatique du mode gère la plupart des charges utiles correctement. Elle devient limitative lorsque vous connaissez la forme de vos données et que l’analyseur ne le sait pas : une longue séquence numérique interrompue par une seule lettre, du texte japonais pour lequel le mode octet consommerait trois octets UTF‑8 par caractère, ou un identifiant à format fixe où vous souhaitez une sortie déterministe entre les versions de la bibliothèque.

Lorsque la configuration manuelle du mode en vaut la peine

Le changement de mode n’est pas gratuit. Chaque frontière de segment écrit un indicateur de mode de quatre bits ainsi qu’un champ de comptage de caractères de huit à seize bits selon la version du QR. Un sur‑segmentation d’une charge utile peut produire un symbole plus grand que de laisser le générateur décider.

Définir le mode explicitement est avantageux lorsque :

• Le chargement utile contient de longues séquences homogènes — un numéro de série de 40 chiffres, un paragraphe de kanji.
• Vous encodez du texte japonais et vous souhaitez le mode Kanji à 13 bits par caractère plutôt que le mode octet à 24.
• Vous avez besoin d’une sortie reproductible, identique octet par octet pour les tests de régression ou la validation de checksum.

Il n’est généralement pas utile d’ajouter de la complexité pour des charges utiles courtes, des données qui changent de type tous les quelques caractères, ou des URL, que l’analyse automatique gère déjà bien. La sous‑section de mesure ci‑dessous montre comment vérifier dans quel cas vous vous trouvez.

Deux manières de définir les modes d’encodage QR en Python

Aspose.BarCode offre deux voies vers le même résultat encodé, et il vaut la peine de savoir pourquoi les deux existent avant d’écrire du code.

Le builder est le meilleur défaut. QrExtCompactionMode.NUMERIC existe ou lève immédiatement une AttributeError, tandis qu’une faute de frappe \numm dans une chaîne devient silencieusement des données de charge utile et ne se manifeste que lorsque quelqu’un scanne l’étiquette. Les deux approches alimentent le même paramètre de générateur QREncodeMode.EXTENDED, vous pouvez donc passer de l’une à l’autre sans modifier quoi que ce soit en aval.

Définir les modes d’encodage QR Code en Python : étape par étape

1. Installer et préparer l’environnement de développement

Aspose.BarCode for Python via .NET est une bibliothèque multiplateforme prenant en charge la génération, la reconnaissance et la manipulation de plus de 50 symbologies, QR inclus. Installez‑la depuis PyPI :

pip install aspose-barcode-for-python-via-net

Confirmez la version, car ces API nécessitent la version 26.6 ou supérieure :

pip show aspose-barcode

Ensuite, vérifiez que l’importation se résout. Le package se lie à un runtime .NET, donc une importation réussie vous indique plus que la simple présence de fichiers sur le disque :

from aspose.barcode.generation import QREncodeMode, QrExtCompactionMode

print("Aspose.BarCode imported successfully.")
print("EXTENDED mode available:", hasattr(QREncodeMode, "EXTENDED"))
print("Encoding modes:", [m for m in dir(QrExtCompactionMode) if m.isupper()])

Output:

Aspose.BarCode imported successfully.
EXTENDED mode available: True
Encoding modes: ['ALPHA_NUMERIC', 'AUTO', 'BYTES', 'KANJI', 'NUMERIC']

Si EXTENDED est manquant, vous utilisez une version antérieure à 26.6 et devez mettre à jour avant de continuer.

Si vous disposez d’un fichier de licence, appliquez‑le une fois au démarrage de l’application, avant tout appel de génération ou de reconnaissance :

from aspose.barcode import License

license = License()
license.set_license("Aspose.BarCode.Python.NET.lic")

2. Définir le mode d’encodage pour chaque segment avec QrExtCodetextBuilder

QrExtCodetextBuilder contient une liste ordonnée de segments. Chaque appel ajoute des données avec le mode d’encodage qui doit les stocker, et get_extended_codetext() les assemble en une chaîne au format étendu que le générateur comprend.

1. Importez les classes de génération.
2. Créez un QrExtCodetextBuilder.
3. Ajoutez un segment numérique avec QrExtCompactionMode.NUMERIC.
4. Ajoutez un segment alphanumérique avec QrExtCompactionMode.ALPHA_NUMERIC.
5. Ajoutez un segment d’octets avec QrExtCompactionMode.BYTES.
6. Ajoutez un segment Kanji avec QrExtCompactionMode.KANJI.
7. Récupérez le texte de code étendu combiné.

from aspose.barcode.barcoderecognition import BarCodeReader, DecodeType
from aspose.barcode.generation import (
    BarcodeGenerator,
    EncodeTypes,
    QREncodeMode,
    QrExtCodetextBuilder,
    QrExtCompactionMode,
)

# Instantiate the Builder.
text_builder = QrExtCodetextBuilder()

# Numeric Segment — 3 Digits per 10 Bits.
text_builder.add_codetext_with_compaction_mode(
    QrExtCompactionMode.NUMERIC, "1234567"
)

# Alphanumeric Segment — Uppercase and Digits Only, 2 Characters per 11 Bits.
text_builder.add_codetext_with_compaction_mode(
    QrExtCompactionMode.ALPHA_NUMERIC, "ASPOSE2026"
)

# Byte Segment — Lowercase Forces Byte Mode, 8 Bits per Character.
text_builder.add_codetext_with_compaction_mode(
    QrExtCompactionMode.BYTES, "aspose2026"
)

# Kanji Segment — Shift-JIS Double-Byte Characters, 13 Bits Each.
text_builder.add_codetext_with_compaction_mode(
    QrExtCompactionMode.KANJI,
    "\u3062\u3063\u3064\u3065\u3066\u3067\u3068\u3069\u306A",
)

# Assemble the Final Extended Codetext.
codetext = text_builder.get_extended_codetext()
print("Extended codetext:", repr(codetext))

Explication

• Chaque appel add_codetext_with_compaction_mode définit le mode d’encodage pour un segment. L’ordre est important — le décodeur renvoie les segments concaténés dans la séquence dans laquelle vous les avez ajoutés.
• L’ensemble alphanumérique est délibérément restreint : chiffres, lettres majuscules A‑Z, espace et $%*+-./:. C’est pourquoi ASPOSE2026 convient au mode alphanumérique alors que aspose2026 ne le fait pas. Les lettres minuscules sont hors de cet ensemble, de sorte que ce segment doit utiliser BYTES. Passer des minuscules à ALPHA_NUMERIC est l’erreur la plus courante lorsqu’on définit les modes de cette manière.
• Le segment Kanji utilise \u3062 et suivants, qui sont des hiragana plutôt que des kanji réels. Le mode Kanji couvre la plage double octet Shift‑JIS, qui inclut les kana, de sorte que ceux‑ci s’encodent sur 13 bits chacun au lieu des 24 bits que le mode octet dépenserait pour chaque caractère en UTF‑8.
• get_extended_codetext() génère la chaîne que le générateur analyse en mode EXTENDED. L’imprimer avec repr() vaut la peine de le faire une fois — cela vous montre la syntaxe du sélecteur que le constructeur émet, qui est exactement ce que la sous‑section suivante écrit manuellement.

3. Définir le mode d’encodage en ligne, sans le constructeur

Lorsque le texte de code provient de l’extérieur de votre code Python, vous pouvez définir le mode de chaque segment directement avec un sélecteur. Chaque marqueur préfixé d’une barre oblique inverse contrôle chaque caractère jusqu’à ce que le marqueur suivant apparaisse :

# Equivalent to the Builder Output Above, Written Directly.
codetext = (
    r"\num1234567"
    r"\alnumASPOSE2026"
    r"\byteaspose2026"
    "\\kanji\u3062\u3063\u3064\u3065\u3066\u3067\u3068\u3069\u306A"
)

Notez l’échappement. Dans une chaîne Python normale, "\num" n’est pas un sélecteur — c’est un saut de ligne suivi de um. Les chaînes brutes (r"...") évitent le problème, mais une chaîne brute bloque également les échappements \u, ce qui explique pourquoi la ligne Kanji ci‑dessus utilise une chaîne conventionnelle avec \\kanji à la place. Ce piège d’échappement est l’argument pratique en faveur de la préférence du constructeur dans la section 2.

4. Générer le code-barres QR en mode EXTENDED

La configuration des modes par segment n’a aucun effet tant que le générateur n’est pas indiqué de les lire. Sans QREncodeMode.EXTENDED, les informations de segment sont ignorées et les marqueurs de sélecteur sont encodés en tant que texte de charge utile littéral.

1. Créez un BarcodeGenerator avec EncodeTypes.QR et le texte de code étendu.
2. Définissez encode_mode sur QREncodeMode.EXTENDED.
3. Configurez la résolution, ainsi que, éventuellement, le niveau de correction d’erreur et la marge.
4. Enregistrez le code‑barres au format PNG sans perte.

# Create the QR Generator with the Extended Codetext.
gen = BarcodeGenerator(EncodeTypes.QR, codetext)

# Switch to EXTENDED Mode So the Per-Segment Modes Are Respected.
gen.parameters.barcode.qr.encode_mode = QREncodeMode.EXTENDED

# Render at Print Resolution Rather Than Upscaling Later.
gen.parameters.resolution = 300

# Save the Generated QR Code.
gen.save("extended_qr.png")

print("QR code generated and saved as extended_qr.png")

Explication

• gen.parameters.barcode.qr.encode_mode = QREncodeMode.EXTENDED est la ligne qui active l’analyse des segments. Laissez‑la de côté et le générateur produit un code QR valide et scannable contenant le texte littéral \num1234567... — c’est pourquoi la sous‑section suivante vérifie plutôt que de supposer.
• gen.parameters.resolution = 300 rend à la résolution d’impression. Les symboles destinés aux imprimantes d’étiquettes ou aux illustrations d’emballage doivent être générés à la taille finale, pas agrandis après, ce qui adoucit les bords des modules.
• save écrit un PNG sans perte. Évitez le JPEG pour toute symbologie 2D — ses artefacts de compression floutent la grille des modules que le décodeur échantillonne.

5. Vérifier que le mode d’encodage a été appliqué

La génération réussie ne prouve rien quant à savoir si les modes par segment ont été appliqués. L’étape de décodage est ce qui sépare un symbole correctement encodé d’un symbole portant des marqueurs de sélecteur comme données.

1. Initialisez un BarCodeReader avec le chemin du fichier et DecodeType.QR.
2. Matérialisez les résultats afin qu’une lecture échouée soit visible.
3. Comparez le texte décodé avec la concaténation attendue.

EXPECTED = (
    "1234567"
    "ASPOSE2026"
    "aspose2026"
    "\u3062\u3063\u3064\u3065\u3066\u3067\u3068\u3069\u306A"
)

# Initialise the QR Code Reader.
reader = BarCodeReader("extended_qr.png", DecodeType.QR)
results = list(reader.read_bar_codes())

if not results:
    raise ValueError("No QR code was detected in extended_qr.png.")

for result in results:
    decoded = result.code_text
    print("BarCode CodeText:", decoded)

if "\\num" in decoded or "\\alnum" in decoded:
        print("Selectors were encoded literally — check that encode_mode is EXTENDED.")
    elif decoded == EXPECTED:
        print("Verified: all four segments decoded and concatenated as expected.")
    else:
        print("Mismatch. Expected:", EXPECTED)

Explication

• DecodeType.QR restreint la reconnaissance aux symboles QR, ce qui est plus rapide que de scanner chaque symbologie prise en charge et empêche qu’un symbole malformé soit décodé comme autre chose.
• list(...) rend le cas d’échec explicite. Un échec de reconnaissance renvoie un itérable vide plutôt que de lever une exception, ainsi une boucle for non protégée sur une lecture échouée se termine silencieusement et est interprétée comme un succès.
• Vérifier la présence d’un littéral \num détecte l’erreur la plus courante dans ce flux de travail : définir correctement les segments et oublier de définir encode_mode.
• La charge utile décodée est les segments bruts concaténés, toutes les informations de mode étant consommées lors de l’encodage. Les modes d’encodage sont des instructions pour l’encodeur, et ne font pas partie des données.

6. Mesurer si le réglage manuel du mode a aidé

Définir le mode d’encodage manuellement est une optimisation, il faut donc le mesurer plutôt que de le supposer. Générez la même charge utile de deux manières et comparez :

RAW = "1234567ASPOSE2026aspose2026"

# Automatic Mode Selection.
auto = BarcodeGenerator(EncodeTypes.QR, RAW)
auto.save("qr_auto.png")

# Manually Set Modes per Segment.
builder = QrExtCodetextBuilder()
builder.add_codetext_with_compaction_mode(QrExtCompactionMode.NUMERIC, "1234567")
builder.add_codetext_with_compaction_mode(QrExtCompactionMode.ALPHA_NUMERIC, "ASPOSE2026")
builder.add_codetext_with_compaction_mode(QrExtCompactionMode.BYTES, "aspose2026")

manual = BarcodeGenerator(EncodeTypes.QR, builder.get_extended_codetext())
manual.parameters.barcode.qr.encode_mode = QREncodeMode.EXTENDED
manual.save("qr_manual.png")

print("Compare qr_auto.png and qr_manual.png — count modules along one edge.")

Comptez les modules le long d’un bord de chaque image. Un symbole QR de version n mesure 17 + 4n modules de côté, ainsi la version 2 est de 25×25 et la version 3 de 29×29. Si les deux aboutissent à la même version, l’analyse automatique a déjà trouvé la segmentation optimale et régler le mode manuellement était une charge de maintenance sans bénéfice. Découvrir cela avant la mise en production est un résultat utile, pas une étape perdue.

Obtenez une licence gratuite

Aspose propose une licence temporaire gratuite qui supprime les restrictions d’évaluation et débloque toutes les fonctionnalités pour les tests. Demandez‑en une sur la page de licence temporaire Aspose et appliquez‑la avant tout appel de génération ou de reconnaissance.

Ressources supplémentaires gratuites

• Documentation du produit
• Référence API
• Applications de code-barres en ligne gratuites

Conclusion

Configurer les modes d’encodage des codes QR en Python se résume à deux questions : quel segment reçoit quel mode, et comment indiquer au générateur de respecter ce choix. QrExtCodetextBuilder et QrExtCompactionMode répondent à la première question dans le code de l’application ; QREncodeMode.EXTENDED répond à la seconde au niveau du générateur. Ce guide couvre à la fois l’API du builder et la syntaxe du sélecteur en ligne qu’il produit, générant un symbole QR à quatre segments, vérifiant la charge utile décodée et mesurant la différence de taille par rapport au mode automatique.

Privilégiez le builder pour le code d’application — il détecte les erreurs de mode au point d’appel plutôt qu’au scanner. Et conservez l’étape de mesure. Configurer le mode manuellement est un réel avantage sur les charges utiles longues et homogènes et une perte nette sur les courtes et mixtes où le surcoût du changement de mode dépasse les économies. Générez les deux, comparez le nombre de modules et laissez le résultat décider quel code vous maintenez.

FAQ

1. Qu’est-ce qu’un mode d’encodage QR code et pourquoi l’utiliser ?
   Un mode d’encodage indique au générateur QR comment traiter un segment de données — numérique, alphanumérique, octet ou Kanji. Chaque mode possède une densité de données différente, ainsi choisir le bon mode pour chaque segment permet de garder la version QR, et donc le symbole, aussi petit que possible. Aspose.BarCode appelle ces modes de compaction ; la spécification QR les appelle modes d’encodage.

2. Quels modes d’encodage QrExtCompactionMode prend‑il en charge ? QrExtCompactionMode fournit NUMERIC, ALPHA_NUMERIC, BYTES et KANJI, correspondant aux quatre modes de données QR définis dans la norme ISO/IEC 18004.

3. Dois-je utiliser QrExtCodetextBuilder ou les sélecteurs EXTENDED en ligne pour définir le mode ? Utilisez le builder pour le code d’application. Il est vérifié au moment de la compilation, évite les erreurs d’échappement des barres obliques inverses et assemble le codetext étendu pour vous. Les sélecteurs en ligne sont utiles lorsque le codetext provient d’une configuration, d’une base de données ou d’un autre système qui ne peut pas appeler le builder.

4. Comment le mode d’encodage EXTENDED diffère-t-il du mode d’encodage QR standard ? Le mode EXTENDED fait en sorte que le générateur lise le texte du code comme une série de segments pré‑définis, chacun avec son propre mode d’encodage, au lieu d’exécuter une détection automatique du mode sur l’ensemble de la chaîne.

5. Puis-je définir différents modes d’encodage pour différentes parties d’un même code QR ? Oui. Ajoutez plusieurs segments à QrExtCodetextBuilder, chacun avec un QrExtCompactionMode différent, et le constructeur produit un texte codé étendu unique couvrant l’ensemble.

6. Un code QR généré avec des modes d’encodage mixtes est‑il compatible avec les lecteurs standards ?
   Oui. L’encodage multi‑segments fait partie de la spécification QR, de sorte que tout scanner conforme décode correctement la charge utile et renvoie les données concaténées.

7. Le réglage manuel du mode d’encodage produit-il toujours un QR code plus petit ? Non. Chaque frontière de segment coûte un indicateur de mode et un champ de comptage de caractères, de sorte que diviser les données en de nombreux segments courts peut agrandir le symbole. La sélection manuelle du mode est avantageuse pour de longues séquences homogènes de données numériques ou Kanji.

8. Ai-je besoin d’une licence pour définir les modes d’encodage QR avec QrExtCodetextBuilder ?
   Vous pouvez évaluer l’API sans licence, sous réserve des restrictions d’évaluation. Une licence temporaire gratuite depuis le site Web d’Aspose lève ces restrictions pendant les tests, et l’utilisation en production nécessite une licence complète.

9. Quelle version d’Aspose.BarCode pour python-net prend en charge ces API ? QrExtCodetextBuilder, QrExtCompactionMode et QREncodeMode.EXTENDED sont disponibles dans Aspose.BarCode pour Python via .NET 26.6 et versions ultérieures.

En savoir plus

• Générer un code-barres MaxiCode en Python
• Créer un générateur de code-barres Code 93 en Python
• Générer un code-barres et un QR Code avec logo en Python