Establecer modos de codificación de códigos QR en Python

Cada generador de QR elige un modo de codificación por defecto, y la mayoría de las veces ese valor predeterminado es suficiente. Deja de ser suficiente en el momento en que necesitas control sobre él — un ID numérico junto a un código de producto, un bloque de texto japonés que no deseas almacenar como UTF-8, o una carga útil donde necesitas los mismos bytes en cada generación. Esta guía muestra cómo establecer los modos de codificación de códigos QR en Python de forma explícita, usando Aspose.BarCode for Python via .NET, de modo que un solo símbolo QR pueda contener un segmento numérico, un segmento alfanumérico, un segmento de bytes y un segmento Kanji — cada uno almacenado en el modo que mejor se adapte.

Aspose.BarCode llama a estos modos de compresión en los nombres de su propia API (QrExtCompactionMode) y la especificación QR los llama modos de codificación. Son los mismos cuatro modos bajo dos nombres, y esta guía utiliza “modo de codificación” a lo largo, ya que ese es el término que la especificación y la mayoría de las bibliotecas QR de Python usan.

Por qué los modos de codificación QR afectan el tamaño del símbolo y la fiabilidad del escaneo

El tamaño físico de un código QR está determinado por la cantidad de bits que necesita su carga útil, y los bits por carácter dependen totalmente del modo de codificación utilizado para ese segmento. La especificación define cuatro modos de datos con densidades marcadamente diferentes:

Un identificador de 30 dígitos cuesta aproximadamente 100 bits en modo numérico y 240 bits en modo byte. Esa diferencia suele ser suficiente para elevar el símbolo varios niveles de versión QR, y una versión más alta implica más módulos en la misma área impresa — módulos más pequeños y una menor tasa de lectura en cámaras de baja resolución, empaques curvos y etiquetas desgastadas.

La selección automática de modo maneja la mayoría de las cargas útiles correctamente. Se vuelve limitante cuando conoces la forma de tus datos y el analizador no lo hace: una larga secuencia numérica interrumpida por una sola letra, texto japonés que el modo de bytes consumiría tres bytes UTF‑8 por carácter, o un identificador de formato fijo donde deseas una salida determinista a través de versiones de la biblioteca.

Cuando vale la pena establecer el modo manualmente

El cambio de modo no es gratuito. Cada límite de segmento escribe un indicador de modo de cuatro bits más un campo de recuento de caracteres de ocho a dieciséis bits, dependiendo de la versión QR. Sobresegmentar una carga útil puede producir un símbolo más grande que dejar que el generador decida.

Establecer el modo explícitamente resulta beneficioso cuando:

• La carga útil contiene secuencias largas y homogéneas — un número de serie de 40 dígitos, un párrafo de kanji.
• Estás codificando texto japonés y deseas el modo Kanji a 13 bits por carácter en lugar del modo byte a 24.
• Necesitas una salida reproducible, idéntica a nivel de bytes, para pruebas de regresión o validación de sumas de verificación.

Por lo general, no vale la pena la complejidad añadida para cargas útiles cortas, datos que alternan tipo cada pocos caracteres o URL, que el análisis automático ya maneja bien. La subsección de medición a continuación muestra cómo verificar en qué caso se encuentra.

Dos formas de establecer modos de codificación QR en Python

Aspose.BarCode ofrece dos rutas al mismo resultado codificado, y vale la pena saber por qué ambas existen antes de escribir código.

El constructor es la mejor opción por defecto. QrExtCompactionMode.NUMERIC o bien existe o genera inmediatamente un AttributeError, mientras que un \numm escrito incorrectamente en una cadena se convierte silenciosamente en datos de carga útil y solo aparece cuando alguien escanea la etiqueta. Ambos enfoques alimentan la misma configuración del generador QREncodeMode.EXTENDED, por lo que puedes cambiar entre ellos sin modificar nada más abajo en la cadena.

Configurar modos de codificación de códigos QR en Python: paso a paso

1. Instalar y preparar el entorno de desarrollo

Aspose.BarCode for Python via .NET es una biblioteca multiplataforma que admite la generación, el reconocimiento y la manipulación de más de 50 simbologías, incluido QR. Instale desde PyPI:

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

Confirme la versión, ya que estas API requieren la 26.6 o una más reciente:

pip show aspose-barcode

Luego verifica que la importación se resuelva. El paquete se enlaza a un tiempo de ejecución .NET, por lo que una importación exitosa indica más que la mera presencia de archivos en el disco:

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 falta, estás en una versión anterior a la 26.6 y necesitas actualizar antes de continuar.

Si tiene un archivo de licencia, aplíquelo una vez al iniciar la aplicación, antes de cualquier llamada de generación o reconocimiento:

from aspose.barcode import License

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

2. Establecer el modo de codificación para cada segmento con QrExtCodetextBuilder

QrExtCodetextBuilder mantiene una lista ordenada de segmentos. Cada llamada agrega datos junto con el modo de codificación que debe almacenarlos, y get_extended_codetext() los ensambla en la cadena de formato extendido que entiende el generador.

1. Importe las clases de generación.
2. Cree un QrExtCodetextBuilder.
3. Añada un segmento numérico con QrExtCompactionMode.NUMERIC.
4. Añada un segmento alfanumérico con QrExtCompactionMode.ALPHA_NUMERIC.
5. Añada un segmento de bytes con QrExtCompactionMode.BYTES.
6. Añada un segmento Kanji con QrExtCompactionMode.KANJI.
7. Recupere el codetext extendido combinado.

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))

Explicación

• Cada llamada a add_codetext_with_compaction_mode establece el modo de codificación para un segmento. El orden importa — el decodificador devuelve los segmentos concatenados en la secuencia en que los agregaste.
• El conjunto alfanumérico es deliberadamente estrecho: dígitos, mayúsculas A‑Z, espacio y $%*+-./:. Por eso ASPOSE2026 encaja en el modo alfanumérico pero aspose2026 no. Las letras minúsculas están fuera del conjunto, por lo que ese segmento debe usar BYTES. Pasar minúsculas a ALPHA_NUMERIC es el error más común al establecer los modos de esta manera.
• El segmento Kanji utiliza \u3062 en adelante, que son hiragana y no kanji propiamente dicho. El modo Kanji cubre el rango de doble byte Shift‑JIS, que incluye kana, por lo que estos se codifican en 13 bits cada uno en lugar de los 24 bits que el modo byte gastaría en cada uno como UTF‑8.
• get_extended_codetext() produce la cadena que el generador analiza en modo EXTENDED. Imprimirla con repr() vale la pena hacerlo una vez — muestra la sintaxis del selector que emite el constructor, que es exactamente lo que la siguiente subsección escribe a mano.

3. Configurar el modo de codificación en línea, sin el Builder

Cuando el texto de código se origina fuera de su código Python, puede establecer el modo de cada segmento directamente con un selector. Cada marcador con prefijo de barra invertida controla cada carácter hasta que aparezca el siguiente marcador:

# 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"
)

Observe el escape. En una cadena normal de Python, "\num" no es un selector — es un salto de línea seguido de um. Las cadenas crudas (r"...") evitan el problema, pero una cadena cruda también bloquea las secuencias de escape \u, por lo que la línea Kanji anterior usa una cadena convencional con \\kanji en su lugar. Esta trampa de escape es el argumento práctico para preferir el constructor en la sección 2.

4. Generar el código QR en modo EXTENDED

Configurar los modos por segmento no tiene efecto hasta que se indique al generador que los lea. Sin QREncodeMode.EXTENDED, la información del segmento se ignora y los marcadores de selector se codifican como texto de carga útil literal.

1. Crear un BarcodeGenerator con EncodeTypes.QR y el texto de código extendido.
2. Establecer encode_mode a QREncodeMode.EXTENDED.
3. Configurar la resolución y, opcionalmente, el nivel de corrección de errores y el margen.
4. Guardar el código de barras en un PNG sin pérdida.

# 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")

Explicación

• gen.parameters.barcode.qr.encode_mode = QREncodeMode.EXTENDED es la línea que activa el análisis de segmentos. Omitirla y el generador producirá un código QR válido y escaneable que contiene el texto literal \num1234567... — por eso la siguiente subsección verifica en lugar de asumir.
• gen.parameters.resolution = 300 se renderiza a resolución de impresión. Los símbolos destinados a impresoras de etiquetas o a arte de empaques deben generarse al tamaño final, sin escalar después, lo que suaviza los bordes de los módulos.
• save escribe un PNG sin pérdida. Evite JPEG para cualquier simbología 2D — sus artefactos de compresión difuminan la cuadrícula de módulos que el decodificador muestrea.

5. Verificar que se aplicó el modo de codificación

La generación exitosa no demuestra nada sobre si los modos por segmento tuvieron efecto. El paso de decodificación es lo que separa un símbolo codificado correctamente de uno que lleva marcadores de selector como datos.

1. Inicializar un BarCodeReader con la ruta del archivo y DecodeType.QR.
2. Materializar los resultados para que una lectura fallida sea visible.
3. Comparar el texto decodificado con la concatenación esperada.

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)

Explicación

• DecodeType.QR restringe el reconocimiento a símbolos QR, lo que es más rápido que escanear cada simbología compatible y evita que un símbolo malformado se decodifique como otra cosa.
• list(...) hace explícito el caso de fallo. Un fallo de reconocimiento devuelve un iterable vacío en lugar de lanzar una excepción, por lo que un bucle for sin protección sobre una lectura fallida termina silenciosamente y se interpreta como éxito.
• Comprobar un literal \num captura el error más común en este flujo de trabajo: establecer los segmentos correctamente y olvidar establecer encode_mode.
• La carga útil decodificada es los segmentos crudos concatenados, con toda la información de modo consumida durante la codificación. Los modos de codificación son instrucciones para el codificador, no forman parte de los datos.

6. Medir si configurar el modo manualmente ayudó

Configurar el modo de codificación manualmente es una optimización, así que mídelo en lugar de asumirlo. Genera la misma carga útil de ambas maneras y compárala:

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.")

Cuente los módulos a lo largo de un borde de cada imagen. Un símbolo QR de versión n es 17 + 4n módulos cuadrado, por lo que la versión 2 es 25×25 y la versión 3 es 29×29. Si ambos caen en la misma versión, el análisis automático ya encontró la segmentación óptima y establecer el modo manualmente era una carga de mantenimiento sin beneficio. Descubrir eso antes del envío es un resultado útil, no un paso desperdiciado.

Obtén una licencia gratuita

Aspose ofrece una licencia temporal gratuita que elimina las restricciones de evaluación y desbloquea la funcionalidad completa para pruebas. Solicite una en la página de licencia temporal de Aspose y aplíquela antes de cualquier llamada de generación o reconocimiento.

Recursos Adicionales Gratuitos

• Documentación del producto
• Referencia de API
• Aplicaciones de códigos de barras en línea gratuitas

Conclusión

Configurar los modos de codificación de códigos QR en Python se reduce a dos preguntas: qué segmento recibe qué modo y cómo indicar al generador que respete esa elección. QrExtCodetextBuilder y QrExtCompactionMode responden la primera pregunta en el código de la aplicación; QREncodeMode.EXTENDED responde la segunda en el generador. Esta guía cubre tanto la API del constructor como la sintaxis del selector en línea que produce, generando un símbolo QR de cuatro segmentos, verificando la carga útil decodificada y midiendo la diferencia de tamaño respecto al modo automático.

Prefiere el constructor para el código de la aplicación — captura los errores de modo en el sitio de llamada en lugar de en el escáner. Y mantén el paso de medición. Configurar el modo manualmente es una verdadera ventaja en cargas útiles largas y homogéneas y una pérdida neta en cargas cortas y mixtas donde la sobrecarga del cambio de modo supera el ahorro. Genera ambos, compara los recuentos de módulos y deja que el resultado decida qué código mantienes.

Preguntas frecuentes

1. ¿Qué es un modo de codificación de código QR y por qué usaría uno? Un modo de codificación indica al generador QR cómo tratar un segmento de datos — numérico, alfanumérico, byte o Kanji. Cada modo tiene una densidad de datos diferente, por lo que elegir el adecuado por segmento mantiene la versión QR, y por ende el símbolo, lo más pequeño posible. Aspose.BarCode llama a estos modos de compresión; la especificación QR los llama modos de codificación.

2. ¿Qué modos de codificación admite QrExtCompactionMode? QrExtCompactionMode proporciona NUMERIC, ALPHA_NUMERIC, BYTES y KANJI, coincidiendo con los cuatro modos de datos QR definidos en ISO/IEC 18004.

3. ¿Debería usar QrExtCodetextBuilder o selectores EXTENDED en línea para establecer el modo? Utilice el constructor para el código de la aplicación. Está verificado por tipos, evita errores de escape de barras invertidas y ensambla el codetext extendido por usted. Los selectores en línea son útiles cuando el codetext proviene de la configuración, una base de datos o otro sistema que no puede llamar al constructor.

4. ¿Cómo difiere el modo de codificación EXTENDED del modo de codificación QR estándar? El modo EXTENDED hace que el generador lea el texto del código como una serie de segmentos predefinidos, cada uno con su propio modo de codificación, en lugar de ejecutar la detección automática de modo en toda la cadena.

5. ¿Puedo establecer diferentes modos de codificación para diferentes partes de un mismo código QR? Sí. Añada varios segmentos a QrExtCodetextBuilder, cada uno con un QrExtCompactionMode diferente, y el generador produce un único codetext extendido que cubre todos ellos.

6. ¿Es compatible un código QR generado con modos de codificación mixtos con lectores estándar? Sí. La codificación de varios segmentos es parte de la especificación QR, por lo que cualquier escáner compatible decodifica la carga útil correctamente y devuelve los datos concatenados.

7. ¿Establecer el modo de codificación manualmente siempre produce un código QR más pequeño? No. Cada límite de segmento cuesta un indicador de modo y un campo de recuento de caracteres, por lo que dividir los datos en muchos segmentos cortos puede hacer que el símbolo sea más grande. La selección manual del modo resulta ventajosa en corridas largas y homogéneas de datos numéricos o Kanji.

8. ¿Necesito una licencia para establecer modos de codificación QR con QrExtCodetextBuilder?
   Puedes evaluar la API sin una licencia, sujeto a restricciones de evaluación. Una licencia temporal gratuita del sitio web de Aspose elimina esas restricciones durante las pruebas, y el uso en producción requiere una licencia completa.

9. ¿Qué versión de Aspose.BarCode for python-net admite estas API? QrExtCodetextBuilder, QrExtCompactionMode y QREncodeMode.EXTENDED están disponibles en Aspose.BarCode for Python via .NET 26.6 y posteriores.

Leer más

• Generar código de barras MaxiCode en Python
• Crear generador de código de barras Code 93 en Python
• Generar código de barras y código QR con logotipo en Python