codecs — Registro de códec y clases base

Código fuente: Lib/codecs.py

---

This module defines base classes for standard Python codecs (encoders and decoders) and provides access to the internal Python codec registry, which manages the codec and error handling lookup process. Most standard codecs are text encodings, which encode text to bytes (and decode bytes to text), but there are also codecs provided that encode text to text, and bytes to bytes. Custom codecs may encode and decode between arbitrary types, but some module features are restricted to be used specifically with text encodings or with codecs that encode to bytes.

El módulo define las siguientes funciones para codificar y decodificar con cualquier códec:

codecs.encode(obj, encoding='utf-8', errors='strict')

Codifica obj utilizando el códec registrado para encoding.

Se pueden dar errors para establecer el esquema de manejo de errores deseado. El controlador de errores predeterminado es 'estricto', lo que significa que los errores de codificación provocan ValueError (o una subclase más específica del códec, como UnicodeEncodeError). Consulte Clases Base de Códec para obtener más información sobre el manejo de errores de códec.

codecs.decode(obj, encoding='utf-8', errors='strict')

Decodifica obj utilizando el códec registrado para encoding.

Se pueden dar errors para establecer el esquema de manejo de errores deseado. El controlador de errores predeterminado es 'estricto', lo que significa que los errores de decodificación generan ValueError (o una subclase más específica de códec, como UnicodeDecodeError). Consulte Clases Base de Códec para obtener más información sobre el manejo de errores de códec.

Los detalles completos de cada códec también se pueden consultar directamente:

codecs.lookup(encoding)

Busca la información de códec en el registro de códec de Python y retorna un objeto CodecInfo como se define a continuación.

Las codificaciones se buscan primero en la memoria caché del registro. Si no se encuentran, se explora la lista de funciones de búsqueda registradas. Si no se encuentran objetos CodecInfo, se lanza un LookupError. De lo contrario, el objeto CodecInfo se almacena en la memoria caché y se retorna a quien llama.

class codecs.CodecInfo(encode, decode, streamreader=None, streamwriter=None, incrementalencoder=None, incrementaldecoder=None, name=None)

Detalles de códec al buscar el registro de códec. Los argumentos del constructor se almacenan en atributos del mismo nombre:

name

El nombre de la codificación.

encode

decode

Las funciones de codificación y decodificación sin estado. Deben ser funciones o métodos que tengan la misma interfaz que los métodos encode() y decode() de instancias de Codec (ver Codec Interface). Se espera que las funciones o métodos funcionen en modo sin estado.

incrementalencoder

incrementaldecoder

Clases de codificación y decodificación incremental o funciones de fábrica. Deben proporcionar la interfaz definida por las clases base IncrementalEncoder y IncrementalDecoder, respectivamente. Los códecs incrementales pueden mantener el estado.

streamwriter

streamreader

Las clases stream, tanto writer como reader o funciones de fábrica. Estos tienen que proporcionar la interfaz definida por las clases base StreamWriter y StreamReader, respectivamente. Los códecs de flujo pueden mantener el estado.

Para simplificar el acceso a los diversos componentes de códec, el módulo proporciona estas funciones adicionales que utilizan lookup() para la búsqueda de códec:

codecs.getencoder(encoding)

Busca el códec para la codificación dada y retorna su función de codificador.

Lanza un LookupError en caso de que no se encuentre la codificación.

codecs.getdecoder(encoding)

Busca el códec para la codificación dada y retorna su función de decodificador.

Lanza un LookupError en caso de que no se encuentre la codificación.

codecs.getincrementalencoder(encoding)

Busca el códec para la codificación dada y retorna su clase de codificador incremental o función de fábrica.

Lanza un LookupError en caso de que no se encuentre la codificación o el códec no admita un codificador incremental.

codecs.getincrementaldecoder(encoding)

Busca el códec para la codificación dada y retorna su clase de decodificador incremental o función de fábrica.

Lanza un LookupError en caso de que no se encuentre la codificación o el códec no admita un decodificador incremental.

codecs.getreader(encoding)

Busca el códec para la codificación dada y retorna su clase StreamReader o función de fábrica.

Lanza un LookupError en caso de que no se encuentre la codificación.

codecs.getwriter(encoding)

Busca el códec para la codificación dada y retorna su clase StreamWriter o función de fábrica.

Lanza un LookupError en caso de que no se encuentre la codificación.

Los códecs personalizados se ponen a disposición registrando una función de búsqueda de códecs adecuada:

codecs.register(search_function)

Register a codec search function. Search functions are expected to take one argument, being the encoding name in all lower case letters with hyphens and spaces converted to underscores, and return a CodecInfo object. In case a search function cannot find a given encoding, it should return None.

Distinto en la versión 3.9: Hyphens and spaces are converted to underscore.

Nota

El registro de la función de búsqueda no es reversible actualmente, lo que puede causar problemas en algunos casos, como pruebas unitarias o recarga de módulos.

Mientras que la función incorporada open() y el módulo asociado io son el enfoque recomendado para trabajar con archivos de texto codificados, este módulo proporciona funciones y clases de utilidad adicionales que permiten el uso de una gama más amplia de códecs cuando se trabaja con archivos binarios:

codecs.open(filename, mode='r', encoding=None, errors='strict', buffering=-1)

Abre un archivo codificado utilizando el mode dado y retorna una instancia de StreamReaderWriter, proporcionando codificación/decodificación transparente. El modo de archivo predeterminado es 'r', que significa abrir el archivo en modo de lectura.

Nota

Los archivos codificados subyacentes siempre se abren en modo binario. No se realiza la conversión automática de '\n' en lectura y escritura. El argumento mode puede ser cualquier modo binario aceptable para la función incorporada open(); la 'b' se agrega automáticamente.

encoding especifica la codificación que se utilizará para el archivo. Se permite cualquier codificación que codifique y decodifique desde bytes, y los tipos de datos admitidos por los métodos de archivo dependen del códec utilizado.

errors puede darse para definir el manejo de errores. El valor predeterminado es 'estricto', lo que hace que se genere un ValueError en caso de que ocurra un error de codificación.

buffering tiene el mismo significado que para la función incorporada open(). Su valor predeterminado es -1, lo que significa que se utilizará el tamaño predeterminado del búfer.

codecs.EncodedFile(file, data_encoding, file_encoding=None, errors='strict')

Retorna una instancia de StreamRecoder, una versión envuelta de file que proporciona transcodificación transparente. El archivo original se cierra cuando se cierra la versión empaquetada.

Los datos escritos en el archivo empaquetado se decodifican de acuerdo con la data_encoding dada y luego se escriben en el archivo original como bytes usando file_encoding. Los bytes leídos del archivo original se decodifican según file_encoding, y el resultado se codifica utilizando data_encoding.

Si no se proporciona file_encoding, el valor predeterminado es data_encoding.

Se pueden dar errors para definir el manejo de errores. Su valor predeterminado es 'estricto', lo que hace que se genere ValueError en caso de que ocurra un error de codificación.

codecs.iterencode(iterator, encoding, errors='strict', **kwargs)

Utiliza un codificador incremental para codificar iterativamente la entrada proporcionada por iterator. Esta función es un generator. El argumento errors (así como cualquier otro argumento de palabra clave) se pasa al codificador incremental.

Esta función requiere que el códec acepte texto en objetos str para codificar. Por lo tanto, no admite codificadores de bytes a bytes, como base64_codec.

codecs.iterdecode(iterator, encoding, errors='strict', **kwargs)

Utiliza un decodificador incremental para decodificar iterativamente la entrada proporcionada por iterator. Esta función es un generator. El argumento errors (así como cualquier otro argumento de palabra clave) se pasa al decodificador incremental.

Esta función requiere que el códec acepte objetos bytes para decodificar. Por lo tanto, no admite codificadores de texto a texto como rot_13, aunque rot_13 puede usarse de manera equivalente con iterencode().

El módulo también proporciona las siguientes constantes que son útiles para leer y escribir en archivos dependientes de la plataforma:

codecs.BOM

codecs.BOM_BE

codecs.BOM_LE

codecs.BOM_UTF8

codecs.BOM_UTF16

codecs.BOM_UTF16_BE

codecs.BOM_UTF16_LE

codecs.BOM_UTF32

codecs.BOM_UTF32_BE

codecs.BOM_UTF32_LE

Estas constantes definen varias secuencias de bytes, que son marcas de orden de bytes Unicode (BOM) para varias codificaciones. Se utilizan en flujos de datos UTF-16 y UTF-32 para indicar el orden de bytes utilizado, y en UTF-8 como firma Unicode. BOM_UTF16 es BOM_UTF16_BE o BOM_UTF16_LE dependiendo del orden de bytes nativo de la plataforma, BOM es un alias para BOM_UTF16, BOM_LE para BOM_UTF16_LE y BOM_BE para BOM_UTF16_BE. Los otros representan la lista de materiales en las codificaciones UTF-8 y UTF-32.

Clases Base de Códec

El módulo codecs define un conjunto de clases base que definen las interfaces para trabajar con objetos de códec, y también puede usarse como base para implementaciones de códec personalizadas.

Cada códec tiene que definir cuatro interfaces para que pueda usarse como códec en Python: codificador sin estado, decodificador sin estado, lector de flujo y escritor de flujo. El lector de flujo y los escritores suelen reutilizar el codificador/decodificador sin estado para implementar los protocolos de archivo. Los autores de códecs también necesitan definir cómo manejará los errores de codificación y decodificación.

Manejadores de errores

To simplify and standardize error handling, codecs may implement different error handling schemes by accepting the errors string argument:

>>> 'German ß, ♬'.encode(encoding='ascii', errors='backslashreplace')
b'German \\xdf, \\u266c'
>>> 'German ß, ♬'.encode(encoding='ascii', errors='xmlcharrefreplace')
b'German ß, ♬'

The following error handlers can be used with all Python Codificaciones estándar codecs:

Valor	Significado
'strict'	Raise UnicodeError (or a subclass), this is the default. Implemented in strict_errors().
'ignore'	Ignore los datos mal formados y continúe sin previo aviso. Implementado en ignore_errors().
'replace'	Replace with a replacement marker. On encoding, use ? (ASCII character). On decoding, use � (U+FFFD, the official REPLACEMENT CHARACTER). Implemented in replace_errors().
'backslashreplace'	Replace with backslashed escape sequences. On encoding, use hexadecimal form of Unicode code point with formats \xhh \uxxxx \Uxxxxxxxx. On decoding, use hexadecimal form of byte value with format \xhh. Implemented in backslashreplace_errors().
'surrogateescape'	En la decodificación, reemplace el byte con código sustituto individual que va desde U+DC80 a U+DCFF. Este código se volverá a convertir en el mismo byte cuando se use el controlador de errores 'sustituto de paisaje' al codificar los datos. (Ver PEP 383 para más información).

The following error handlers are only applicable to encoding (within text encodings):

Valor	Significado
'xmlcharrefreplace'	Replace with XML/HTML numeric character reference, which is a decimal form of Unicode code point with format &#num; Implemented in xmlcharrefreplace_errors().
'namereplace'	Replace with \N{...} escape sequences, what appears in the braces is the Name property from Unicode Character Database. Implemented in namereplace_errors().

Además, el siguiente controlador de errores es específico de los códecs dados:

Valor	Códecs	Significado
'surrogatepass'	utf-8, utf-16, utf-32, utf-16-be, utf-16-le, utf-32-be, utf-32-le	Allow encoding and decoding surrogate code point (U+D800 - U+DFFF) as normal code point. Otherwise these codecs treat the presence of surrogate code point in str as an error.

Nuevo en la versión 3.1: Los manejadores de errores 'surrogateescape' y 'surrogatepass'.

Distinto en la versión 3.4: The 'surrogatepass' error handler now works with utf-16* and utf-32* codecs.

Nuevo en la versión 3.5: El controlador de errores 'namereplace'.

Distinto en la versión 3.5: The 'backslashreplace' error handler now works with decoding and translating.

El conjunto de valores permitidos puede ampliarse registrando un nuevo controlador de errores con nombre:

codecs.register_error(name, error_handler)

Registre la función de manejo de errores error_handler bajo el nombre name. Se invocará el argumento error_handler durante la codificación y decodificación en caso de error, cuando name se especifica como el parámetro de errores.

Para la codificación, se llamará a error_handler con una instancia UnicodeEncodeError, que contiene información sobre la ubicación del error. El controlador de errores debe generar esta o una excepción diferente, o retornar una tupla con un reemplazo para la parte no codificable de la entrada y una posición donde la codificación debe continuar. El reemplazo puede ser str o bytes. Si el reemplazo son bytes, el codificador simplemente los copiará en el búfer de salida. Si el reemplazo es una cadena de caracteres, el codificador codificará el reemplazo. La codificación continúa en la entrada original en la posición especificada. Los valores de posición negativos se tratarán como relativos al final de la cadena de entrada. Si la posición resultante está fuera del límite, se generará IndexError.

La decodificación y traducción funcionan de manera similar, excepto que UnicodeDecodeError o UnicodeTranslateError se pasarán al controlador y el reemplazo del controlador de errores se colocará directamente en la salida.

Los controladores de errores registrados previamente (incluidos los controladores de errores estándar) se pueden buscar por nombre:

codecs.lookup_error(name)

Retorna el controlador de errores previamente registrado con el nombre name.

Lanza un LookupError en caso de que no se pueda encontrar el controlador.

Los siguientes controladores de errores estándar también están disponibles como funciones de nivel de módulo:

codecs.strict_errors(exception)

Implements the 'strict' error handling.

Each encoding or decoding error raises a UnicodeError.

codecs.ignore_errors(exception)

Implements the 'ignore' error handling.

Malformed data is ignored; encoding or decoding is continued without further notice.

codecs.replace_errors(exception)

Implements the 'replace' error handling.

Substitutes ? (ASCII character) for encoding errors or � (U+FFFD, the official REPLACEMENT CHARACTER) for decoding errors.

codecs.backslashreplace_errors(exception)

Implements the 'backslashreplace' error handling.

Malformed data is replaced by a backslashed escape sequence. On encoding, use the hexadecimal form of Unicode code point with formats \xhh \uxxxx \Uxxxxxxxx. On decoding, use the hexadecimal form of byte value with format \xhh.

Distinto en la versión 3.5: Works with decoding and translating.

codecs.xmlcharrefreplace_errors(exception)

Implements the 'xmlcharrefreplace' error handling (for encoding within text encoding only).

The unencodable character is replaced by an appropriate XML/HTML numeric character reference, which is a decimal form of Unicode code point with format &#num; .

codecs.namereplace_errors(exception)

Implements the 'namereplace' error handling (for encoding within text encoding only).

The unencodable character is replaced by a \N{...} escape sequence. The set of characters that appear in the braces is the Name property from Unicode Character Database. For example, the German lowercase letter 'ß' will be converted to byte sequence \N{LATIN SMALL LETTER SHARP S} .

Nuevo en la versión 3.5.

Codificación y decodificación sin estado

La clase base Codec define estos métodos que también definen las interfaces de función del codificador y decodificador sin estado:

Codec.encode(input, errors='strict')

Codifica el objeto input y retorna una tupla (objeto de salida, longitud consumida). Por ejemplo text encoding convierte un objeto de cadena de caracteres en un objeto de bytes utilizando una codificación de juego de caracteres particular (por ejemplo,``cp1252`` o iso-8859-1).

El argumento errors define el manejo de errores a aplicar. El valor predeterminado es el manejo estricto.

Es posible que el método no almacene estado en la instancia Codec. Use StreamWriter para códecs que deben mantener el estado para que la codificación sea eficiente.

El codificador debe poder manejar la entrada de longitud cero y retornar un objeto vacío del tipo de objeto de salida en esta situación.

Codec.decode(input, errors='strict')

Decodifica el objeto input y retorna una tupla (objeto de salida, longitud consumida). Por ejemplo, para un codificación de texto, la decodificación convierte un objeto de bytes codificado usando una codificación de juego de caracteres particular en un objeto de cadena de caracteres.

Para codificaciones de texto y códecs de bytes a bytes, input debe ser un objeto de bytes o uno que proporcione la interfaz de búfer de solo lectura, por ejemplo, objetos de búfer y archivos mapeados en memoria.

El argumento errors define el manejo de errores a aplicar. El valor predeterminado es el manejo estricto.

Es posible que el método no almacene estado en la instancia de Codec. Use StreamReader para códecs que deben mantener el estado para que la decodificación sea eficiente.

El decodificador debe poder manejar la entrada de longitud cero y retornar un objeto vacío del tipo de objeto de salida en esta situación.

Codificación y decodificación incrementales

Las clases IncrementalEncoder y IncrementalDecoder proporcionan la interfaz básica para la codificación y decodificación incrementales. La codificación/decodificación de la entrada no se realiza con una llamada a la función de codificador/decodificador sin estado, sino con varias llamadas al método encode()/decode() del codificador incremental /decodificador. El codificador/decodificador incremental realiza un seguimiento del proceso de codificación/decodificación durante las llamadas a métodos.

La salida combinada de las llamadas al método encode()/decode() es el mismo que si todas las entradas individuales se unieran en una, y esta entrada se codificara/decodificara con codificador/decodificador sin estado.

Objetos IncrementalEncoder

La clase IncrementalEncoder se usa para codificar una entrada en varios pasos. Define los siguientes métodos que cada codificador incremental debe definir para ser compatible con el registro de códec Python.

class codecs.IncrementalEncoder(errors='strict')

Constructor para una clase instancia de IncrementalEncoder.

Todos los codificadores incrementales deben proporcionar esta interfaz de constructor. Son libres de agregar argumentos de palabras clave adicionales, pero el registro de códecs de Python solo utiliza los definidos aquí.

La clase IncrementalEncoder puede implementar diferentes esquemas de manejo de errores al proporcionar el argumento de palabra clave errors. Ver Manejadores de errores para posibles valores.

El argumento errors se asignará a un atributo del mismo nombre. La asignación a este atributo hace posible cambiar entre diferentes estrategias de manejo de errores durante la vida útil del objeto IncrementalEncoder.

encode(object, final=False)

Codifica object (teniendo en cuenta el estado actual del codificador) y retorna el objeto codificado resultante. Si esta es la última llamada a encode() final debe ser verdadero (el valor predeterminado es falso).

reset()

Restablece el codificador al estado inicial. La salida se descarta: llama a .encode(object, final=True), pasando un byte vacío o una cadena de texto si es necesario, para restablecer el codificador y obtener la salida.

getstate()

Retorna el estado actual del codificador que debe ser un número entero. La implementación debe asegurarse de que 0 sea el estado más común. (Los estados que son más complicados que los enteros se pueden convertir en un entero al empaquetar/serializar el estado y codificar los bytes de la cadena resultante en un entero).

setstate(state)

Establece el estado del codificador en state. state debe ser un estado de codificador retornado por getstate().

Objetos IncrementalDecoder

La clase IncrementalDecoder se usa para decodificar una entrada en varios pasos. Define los siguientes métodos que cada decodificador incremental debe definir para ser compatible con el registro de códec Python.

class codecs.IncrementalDecoder(errors='strict')

Constructor para una instancia de IncrementalDecoder.

Todos los decodificadores incrementales deben proporcionar esta interfaz de constructor. Son libres de agregar argumentos de palabras clave adicionales, pero el registro de códecs de Python solo utiliza los definidos aquí.

La clase IncrementalDecoder puede implementar diferentes esquemas de manejo de errores al proporcionar el argumento de palabra clave errors. Ver Manejadores de errores para posibles valores.

El argumento errors se asignará a un atributo del mismo nombre. La asignación a este atributo hace posible cambiar entre diferentes estrategias de manejo de errores durante la vida útil del objeto IncrementalDecoder.

decode(object, final=False)

Decodifica object (teniendo en cuenta el estado actual del decodificador) y retorna el objeto decodificado resultante. Si esta es la última llamada a decode() final debe ser verdadero (el valor predeterminado es falso). Si final es verdadero, el decodificador debe decodificar la entrada por completo y debe vaciar todos los búferes. Si esto no es posible (por ejemplo, debido a secuencias de bytes incompletas al final de la entrada), debe iniciar el manejo de errores al igual que en el caso sin estado (lo que podría generar una excepción).

reset()

Restablece el decodificador al estado inicial.

getstate()

Retorna el estado actual del decodificador. Debe ser una tupla con dos elementos, el primero debe ser el búfer que contiene la entrada aún sin codificar. El segundo debe ser un número entero y puede ser información de estado adicional. (La implementación debe asegurarse de que 0 sea la información de estado adicional más común). Si esta información de estado adicional es 0, debe ser posible establecer el decodificador en el estado que no tiene entrada almacenada y 0 como información de estado adicional, de modo que alimentar la entrada previamente almacenada en el búfer al decodificador la retorna al estado anterior sin producir ninguna salida. (La información de estado adicional que es más complicada que los enteros se puede convertir en un entero al empaquetar/serializar la información y codificar los bytes de la cadena resultante en un entero).

setstate(state)

Establezca el estado del decodificador en state. state debe ser un estado de decodificador retornado por getstate().

Codificación y decodificación de flujos

Las clases StreamWriter y StreamReader proporcionan interfaces de trabajo genéricas que se pueden usar para implementar nuevos submódulos de codificación muy fácilmente. Ir a encodings.utf_8 para ver un ejemplo de cómo se hace esto.

Objetos StreamWriter

La clase StreamWriter es una subclase de Codec y define los siguientes métodos que cada escritor del flujo debe definir para ser compatible con el registro de códecs Python.

class codecs.StreamWriter(stream, errors='strict')

Constructor para una instancia de StreamWriter.

Todos los escritores de flujos deben proporcionar esta interfaz de constructor. Son libres de agregar argumentos de palabras clave adicionales, pero el registro de códecs de Python solo utiliza los definidos aquí.

El argumento stream debe ser un objeto tipo archivo abierto para escribir texto o datos binarios, según corresponda para el códec específico.

La clase StreamWriter puede implementar diferentes esquemas de manejo de errores al proporcionar el argumento de palabra clave errors. Consulte Manejadores de errores para ver los controladores de error estándar que puede admitir el códec de flujo subyacente.

El argumento errors se asignará a un atributo del mismo nombre. La asignación a este atributo hace posible cambiar entre diferentes estrategias de manejo de errores durante la vida útil del objeto StreamWriter.

write(object)

Escribe el contenido del objeto codificado en el flujo.

writelines(list)

Writes the concatenated iterable of strings to the stream (possibly by reusing the write() method). Infinite or very large iterables are not supported. The standard bytes-to-bytes codecs do not support this method.

reset()

Restablece los búfers de códec utilizados para mantener el estado interno.

Llamar a este método debería garantizar que los datos en la salida se pongan en un estado limpio que permita agregar datos nuevos sin tener que volver a escanear todo el flujo para recuperar el estado.

Además de los métodos anteriores, la clase StreamWriter también debe heredar todos los demás métodos y atributos del flujo subyacente.

Objetos StreamReader

La clase StreamReader es una subclase de Codec y define los siguientes métodos que cada lector de flujo debe definir para ser compatible con el registro de códecs de Python.

class codecs.StreamReader(stream, errors='strict')

Constructor para una instancia de StreamReader.

Todos los lectores de flujo deben proporcionar esta interfaz de constructor. Son libres de agregar argumentos de palabras clave adicionales, pero el registro de códecs de Python solo utiliza los definidos aquí.

El argumento stream debe ser un objeto tipo archivo abierto para leer texto o datos binarios, según corresponda para el códec específico.

La clase StreamReader puede implementar diferentes esquemas de manejo de errores al proporcionar el argumento de palabra clave errors. Consulte Manejadores de errores para ver los controladores de error estándar que puede admitir el códec de flujo subyacente.

El argumento errors se asignará a un atributo del mismo nombre. La asignación a este atributo hace posible cambiar entre diferentes estrategias de manejo de errores durante la vida útil del objeto StreamReader.

El conjunto de valores permitidos para el argumento errors se puede ampliar con register_error().

read(size=-1, chars=-1, firstline=False)

Decodifica datos del flujo y retorna el objeto resultante.

El argumento chars indica el número de puntos de código decodificados o bytes a retornar. El método read() nunca retornará más datos de los solicitados, pero podría retornar menos, si no hay suficientes disponibles.

El argumento size indica el número máximo aproximado de bytes codificados o puntos de código para leer para la decodificación. El decodificador puede modificar esta configuración según corresponda. El valor predeterminado -1 indica leer y decodificar tanto como sea posible. Este parámetro está diseñado para evitar tener que decodificar archivos grandes en un solo paso.

La bandera firstline indica que sería suficiente retornar solo la primera línea, si hay errores de decodificación en las líneas posteriores.

El método debe usar una estrategia de lectura codiciosa, lo que significa que debe leer la mayor cantidad de datos permitidos dentro de la definición de la codificación y el tamaño dado, por ejemplo si las terminaciones de codificación opcionales o los marcadores de estado están disponibles en la transmisión, también deben leerse.

readline(size=None, keepends=True)

Lee una línea del flujo de entrada y retorna los datos decodificados.

size, si se da, se pasa como argumento de tamaño al método read() del stream.

Si keepends es falso, las terminaciones de línea se eliminarán de las líneas retornadas.

readlines(sizehint=None, keepends=True)

Lee todas las líneas disponibles en el flujo de entrada y las retorna como una lista de líneas.

Los finales de línea se implementan utilizando el método decode() del códec y se incluyen en las entradas de la lista si keepends es verdadero.

sizehint, si se proporciona, se pasa como argumento size al método read() del stream.

reset()

Restablece los búfers de códec utilizados para mantener el estado interno.

Tenga en cuenta que ningún reposicionamiento de flujo debe suceder. Este método está destinado principalmente a poder recuperarse de errores de decodificación.

Además de los métodos anteriores, la clase StreamReader también debe heredar todos los demás métodos y atributos del flujo subyacente.

Objetos StreamReaderWriter

La clase StreamReaderWriter es una clase de conveniencia que permite envolver flujos que funcionan tanto en modo de lectura como de escritura.

El diseño es tal que uno puede usar las funciones de fábrica retornadas por la función lookup() para construir la instancia.

class codecs.StreamReaderWriter(stream, Reader, Writer, errors='strict')

Crea una instancia de StreamReaderWriter. stream debe ser un objeto similar a un archivo. Reader y Writer deben ser funciones o clases de fábrica que proporcionen la interfaz StreamReader y StreamWriter respectivamente. El manejo de errores se realiza de la misma manera que se define para los lectores y escritores de flujos.

Las instancias StreamReaderWriter definen las interfaces combinadas de StreamReader y clases StreamWriter. Heredan todos los demás métodos y atributos del flujo subyacente.

Objetos StreamRecoder

La clase StreamRecoder traduce datos de una codificación a otra, lo que a veces es útil cuando se trata de diferentes entornos de codificación.

El diseño es tal que uno puede usar las funciones de fábrica retornadas por la función lookup() para construir la instancia.

class codecs.StreamRecoder(stream, encode, decode, Reader, Writer, errors='strict')

Crea una instancia de StreamRecoder que implementa una conversión bidireccional: encode y decode funcionan en el frontend: los datos visibles para la llamada de código read() y write(), mientras que Reader y Writer funcionan en el backend — los datos en stream.

Puede usar estos objetos para realizar transcodificaciones transparentes, por ejemplo, de Latin-1 a UTF-8 y viceversa.

El argumento stream debe ser un objeto similar a un archivo.

Los argumentos encode y decode deben cumplir con la interfaz de Codec. Reader y Writer deben ser funciones o clases de fábrica que proporcionen objetos de la interfaz StreamReader y StreamWriter respectivamente.

El manejo de errores se realiza de la misma manera que se define para los lectores y escritores de flujos.

las instancias StreamRecoder definen las interfaces combinadas de las clases StreamReader y StreamWriter. Heredan todos los demás métodos y atributos del flujo subyacente.

Codificaciones y Unicode

Strings are stored internally as sequences of code points in range U+0000–U+10FFFF. (See PEP 393 for more details about the implementation.) Once a string object is used outside of CPU and memory, endianness and how these arrays are stored as bytes become an issue. As with other codecs, serialising a string into a sequence of bytes is known as encoding, and recreating the string from the sequence of bytes is known as decoding. There are a variety of different text serialisation codecs, which are collectivity referred to as text encodings.

La codificación de texto más simple (llamada 'latin-1' o 'iso-8859-1') asigna los puntos de código 0–255 a los bytes 0x0 – 0xff, lo que significa que un objeto de cadena de caracteres que contiene puntos de código encima de U+00FF no se puede codificar con este códec. Al hacerlo, lanzará un UnicodeEncodeError que se parece a lo siguiente (aunque los detalles del mensaje de error pueden diferir): UnicodeEncodeError: 'latin-1' codec can't encode character '\u1234' 'in position 3: ordinal not in range(256).

Hay otro grupo de codificaciones (las llamadas codificaciones de mapa de caracteres) que eligen un subconjunto diferente de todos los puntos de código Unicode y cómo estos puntos de código se asignan a los bytes 0x0 – 0xff. Para ver cómo se hace esto, simplemente abra, por ejemplo encodings/cp1252.py (que es una codificación que se usa principalmente en Windows). Hay una cadena constante con 256 caracteres que le muestra qué carácter está asignado a qué valor de byte.

All of these encodings can only encode 256 of the 1114112 code points defined in Unicode. A simple and straightforward way that can store each Unicode code point, is to store each code point as four consecutive bytes. There are two possibilities: store the bytes in big endian or in little endian order. These two encodings are called UTF-32-BE and UTF-32-LE respectively. Their disadvantage is that if e.g. you use UTF-32-BE on a little endian machine you will always have to swap bytes on encoding and decoding. UTF-32 avoids this problem: bytes will always be in natural endianness. When these bytes are read by a CPU with a different endianness, then bytes have to be swapped though. To be able to detect the endianness of a UTF-16 or UTF-32 byte sequence, there’s the so called BOM («Byte Order Mark»). This is the Unicode character U+FEFF. This character can be prepended to every UTF-16 or UTF-32 byte sequence. The byte swapped version of this character (0xFFFE) is an illegal character that may not appear in a Unicode text. So when the first character in a UTF-16 or UTF-32 byte sequence appears to be a U+FFFE the bytes have to be swapped on decoding. Unfortunately the character U+FEFF had a second purpose as a ZERO WIDTH NO-BREAK SPACE: a character that has no width and doesn’t allow a word to be split. It can e.g. be used to give hints to a ligature algorithm. With Unicode 4.0 using U+FEFF as a ZERO WIDTH NO-BREAK SPACE has been deprecated (with U+2060 (WORD JOINER) assuming this role). Nevertheless Unicode software still must be able to handle U+FEFF in both roles: as a BOM it’s a device to determine the storage layout of the encoded bytes, and vanishes once the byte sequence has been decoded into a string; as a ZERO WIDTH NO-BREAK SPACE it’s a normal character that will be decoded like any other.

There’s another encoding that is able to encode the full range of Unicode characters: UTF-8. UTF-8 is an 8-bit encoding, which means there are no issues with byte order in UTF-8. Each byte in a UTF-8 byte sequence consists of two parts: marker bits (the most significant bits) and payload bits. The marker bits are a sequence of zero to four 1 bits followed by a 0 bit. Unicode characters are encoded like this (with x being payload bits, which when concatenated give the Unicode character):

Rango	Codificación
U-00000000 … U-0000007F	0xxxxxxx
U-00000080 … U-000007FF	110xxxxx 10xxxxxx
U-00000800 … U-0000FFFF	1110xxxx 10xxxxxx 10xxxxxx
U-00010000 … U-0010FFFF	11110xxx 10xxxxxx 10xxxxxx 10xxxxxx

El bit menos significativo del carácter Unicode es el bit x más a la derecha.

Como UTF-8 es una codificación de 8 bits, no se requiere una lista de materiales y cualquier carácter U+FEFF en la cadena decodificada (incluso si es el primer carácter) se trata como un ESPACIO SIN QUIEBRE DE ANCHO CERO` (``ZERO WIDTH NO-BREAK SPACE``).

Without external information it’s impossible to reliably determine which encoding was used for encoding a string. Each charmap encoding can decode any random byte sequence. However that’s not possible with UTF-8, as UTF-8 byte sequences have a structure that doesn’t allow arbitrary byte sequences. To increase the reliability with which a UTF-8 encoding can be detected, Microsoft invented a variant of UTF-8 (that Python calls "utf-8-sig") for its Notepad program: Before any of the Unicode characters is written to the file, a UTF-8 encoded BOM (which looks like this as a byte sequence: 0xef, 0xbb, 0xbf) is written. As it’s rather improbable that any charmap encoded file starts with these byte values (which would e.g. map to

LETRA LATINA PEQUEÑA I CON DIAERESIS

SEÑALADO A LA DERECHA DE DOBLE ÁNGULO MARCA DE CITA

SIGNO DE PREGUNTA INVERTIDO

en iso-8859-1), esto aumenta la probabilidad de que una codificación utf-8-sig pueda adivinarse correctamente a partir de la secuencia de bytes. Por lo tanto, aquí la lista de materiales no se utiliza para poder determinar el orden de bytes utilizado para generar la secuencia de bytes, sino como una firma que ayuda a adivinar la codificación. Al codificar, el códec utf-8-sig escribirá 0xef, 0xbb, 0xbf como los primeros tres bytes del archivo. Al decodificar, utf-8-sig omitirá esos tres bytes si aparecen como los primeros tres bytes en el archivo. En UTF-8, se desaconseja el uso de la lista de materiales y, en general, debe evitarse.

Codificaciones estándar

Python viene con una serie de códecs integrados, ya sea implementados como funciones C o con diccionarios como tablas de mapeo. La siguiente tabla enumera los códecs por nombre, junto con algunos alias comunes y los idiomas para los que probablemente se usa la codificación. Ni la lista de alias ni la lista de idiomas deben ser exhaustivas. Tenga en cuenta que las alternativas de ortografía que solo difieren en el caso o usan un guión en lugar de un guión bajo también son alias válidos; por lo tanto, por ejemplo 'utf-8' es un alias válido para el códec 'utf_8'.

CPython implementation detail: Algunas codificaciones comunes pueden omitir la maquinaria de búsqueda de códecs para mejorar el rendimiento. CPython solo reconoce estas oportunidades de optimización para un conjunto limitado de alias (sin distinción entre mayúsculas y minúsculas): utf-8, utf8, latin-1, latin1, iso-8859-1, iso8859-1, mbcs (solo Windows), ascii, us-ascii, utf-16, utf16, utf-32, utf32, y lo mismo usando guiones bajos en lugar de guiones. El uso de alias alternativos para estas codificaciones puede resultar en una ejecución más lenta.

Distinto en la versión 3.6: Oportunidad de optimización reconocida para us-ascii.

Muchos de los juegos de caracteres admiten los mismos idiomas. Varían en caracteres individuales (por ejemplo, si el SIGNO EURO es compatible o no), y en la asignación de caracteres para codificar posiciones. Para los idiomas europeos en particular, generalmente existen las siguientes variantes:

• un conjunto de códigos ISO 8859

• una página de códigos de Microsoft Windows, que generalmente se deriva de un conjunto de códigos 8859, pero reemplaza los caracteres de control con caracteres gráficos adicionales

• una página de códigos EBCDIC de IBM

• una página de códigos de IBM PC, que es compatible con ASCII

Códec	Aliases	Lenguajes
ascii	646, us-ascii	Inglés
big5	big5-tw, csbig5	Chino Tradicional
big5hkscs	big5-hkscs, hkscs	Chino Tradicional
cp037	IBM037, IBM039	Inglés
cp273	273, IBM273, csIBM273	Alemán Nuevo en la versión 3.4.
cp424	EBCDIC-CP-HE, IBM424	Hebreo
cp437	437, IBM437	Inglés
cp500	EBCDIC-CP-BE, EBCDIC-CP-CH, IBM500	Europa Occidental
cp720		Árabe
cp737		Griego
cp775	IBM775	Lenguajes bálticos
cp850	850, IBM850	Europa Occidental
cp852	852, IBM852	Europa central y del este
cp855	855, IBM855	Búlgaro, Bielorruso, Macedonio, Ruso, Serbio
cp856		Hebreo
cp857	857, IBM857	Turco
cp858	858, IBM858	Europa Occidental
cp860	860, IBM860	Portugués
cp861	861, CP-IS, IBM861	Islandés
cp862	862, IBM862	Hebreo
cp863	863, IBM863	Canadiense
cp864	IBM864	Árabe
cp865	865, IBM865	Danés, Noruego
cp866	866, IBM866	Ruso
cp869	869, CP-GR, IBM869	Griego
cp874		Tailandés
cp875		Griego
cp932	932, ms932, mskanji, ms-kanji	Japonés
cp949	949, ms949, uhc	Coreano
cp950	950, ms950	Chino Tradicional
cp1006		Urdu
cp1026	ibm1026	Turco
cp1125	1125, ibm1125, cp866u, ruscii	Ucraniano Nuevo en la versión 3.4.
cp1140	ibm1140	Europa Occidental
cp1250	windows-1250	Europa central y del este
cp1251	windows-1251	Búlgaro, Bielorruso, Macedonio, Ruso, Serbio
cp1252	windows-1252	Europa Occidental
cp1253	windows-1253	Griego
cp1254	windows-1254	Turco
cp1255	windows-1255	Hebreo
cp1256	windows-1256	Árabe
cp1257	windows-1257	Lenguajes bálticos
cp1258	windows-1258	Vietnamita
euc_jp	eucjp, ujis, u-jis	Japonés
euc_jis_2004	jisx0213, eucjis2004	Japonés
euc_jisx0213	eucjisx0213	Japonés
euc_kr	euckr, korean, ksc5601, ks_c-5601, ks_c-5601-1987, ksx1001, ks_x-1001	Coreano
gb2312	chinese, csiso58gb231280, euc-cn, euccn, eucgb2312-cn, gb2312-1980, gb2312-80, iso-ir-58	Chino simplificado
gbk	936, cp936, ms936	Chino Unificado
gb18030	gb18030-2000	Chino Unificado
hz	hzgb, hz-gb, hz-gb-2312	Chino simplificado
iso2022_jp	csiso2022jp, iso2022jp, iso-2022-jp	Japonés
iso2022_jp_1	iso2022jp-1, iso-2022-jp-1	Japonés
iso2022_jp_2	iso2022jp-2, iso-2022-jp-2	Japonés, Coreano, Chino simplificado, Europa occidental, Griego
iso2022_jp_2004	iso2022jp-2004, iso-2022-jp-2004	Japonés
iso2022_jp_3	iso2022jp-3, iso-2022-jp-3	Japonés
iso2022_jp_ext	iso2022jp-ext, iso-2022-jp-ext	Japonés
iso2022_kr	csiso2022kr, iso2022kr, iso-2022-kr	Coreano
latin_1	iso-8859-1, iso8859-1, 8859, cp819, latin, latin1, L1	Europa Occidental
iso8859_2	iso-8859-2, latin2, L2	Europa central y del este
iso8859_3	iso-8859-3, latin3, L3	Esperanto, Maltés
iso8859_4	iso-8859-4, latin4, L4	Lenguajes bálticos
iso8859_5	iso-8859-5, cyrillic	Búlgaro, Bielorruso, Macedonio, Ruso, Serbio
iso8859_6	iso-8859-6, arabic	Árabe
iso8859_7	iso-8859-7, greek, greek8	Griego
iso8859_8	iso-8859-8, hebrew	Hebreo
iso8859_9	iso-8859-9, latin5, L5	Turco
iso8859_10	iso-8859-10, latin6, L6	Lenguajes nórdicos
iso8859_11	iso-8859-11, thai	Lenguajes tailandeses
iso8859_13	iso-8859-13, latin7, L7	Lenguajes bálticos
iso8859_14	iso-8859-14, latin8, L8	Lenguajes Celtas
iso8859_15	iso-8859-15, latin9, L9	Europa Occidental
iso8859_16	iso-8859-16, latin10, L10	Europa sudoriental
johab	cp1361, ms1361	Coreano
koi8_r		Ruso
koi8_t		Tayiko Nuevo en la versión 3.5.
koi8_u		Ucraniano
kz1048	kz_1048, strk1048_2002, rk1048	Kazajo Nuevo en la versión 3.5.
mac_cyrillic	maccyrillic	Búlgaro, Bielorruso, Macedonio, Ruso, Serbio
mac_greek	macgreek	Griego
mac_iceland	maciceland	Islandés
mac_latin2	maclatin2, maccentraleurope, mac_centeuro	Europa central y del este
mac_roman	macroman, macintosh	Europa Occidental
mac_turkish	macturkish	Turco
ptcp154	csptcp154, pt154, cp154, cyrillic-asian	Kazajo
shift_jis	csshiftjis, shiftjis, sjis, s_jis	Japonés
shift_jis_2004	shiftjis2004, sjis_2004, sjis2004	Japonés
shift_jisx0213	shiftjisx0213, sjisx0213, s_jisx0213	Japonés
utf_32	U32, utf32	todos los lenguajes
utf_32_be	UTF-32BE	todos los lenguajes
utf_32_le	UTF-32LE	todos los lenguajes
utf_16	U16, utf16	todos los lenguajes
utf_16_be	UTF-16BE	todos los lenguajes
utf_16_le	UTF-16LE	todos los lenguajes
utf_7	U7, unicode-1-1-utf-7	todos los lenguajes
utf_8	U8, UTF, utf8, cp65001	todos los lenguajes
utf_8_sig		todos los lenguajes

Distinto en la versión 3.4: Los codificadores utf-16* y utf-32* ya no permiten codificar puntos de código sustitutos (U+D800 – U+DFFF). Los decodificadores utf-32* ya no decodifican secuencias de bytes que corresponden a puntos de código sustituto.

Distinto en la versión 3.8: cp65001 ahora es un alias de utf_8.

Codificaciones específicas de Python

Varios códecs predefinidos son específicos de Python, por lo que sus nombres de códec no tienen significado fuera de Python. Estos se enumeran en las tablas a continuación según los tipos de entrada y salida esperados (tenga en cuenta que si bien las codificaciones de texto son el caso de uso más común para los códecs, la infraestructura de códecs subyacente admite transformaciones de datos arbitrarias en lugar de solo codificaciones de texto). Para los códecs asimétricos, el significado indicado describe la dirección de codificación.

Codificaciones de texto

Los siguientes códecs proporcionan codificación de str a bytes y decodificación de bytes-like object a str, similar a las codificaciones de texto Unicode.

Códec	Aliases	Significado
idna		Implementar RFC 3490, ver también encodings.idna. Solo se admite errors='strict'.
mbcs	ansi, dbcs	Solo Windows: codifique el operando de acuerdo con la página de códigos ANSI (CP_ACP).
oem		Solo Windows: codifique el operando de acuerdo con la página de códigos OEM (CP_OEMCP). Nuevo en la versión 3.6.
palmos		Codificación de PalmOS 3.5.
punycode		Implementar RFC 3492. Los códecs con estado no son compatibles.
raw_unicode_escape		Codificación Latin-1 con \uXXXX y \UXXXXXXXX para otros puntos de código. Las barras invertidas existentes no se escapan de ninguna manera. Se usa en el protocolo Python pickle.
indefinido		Lanza una excepción para todas las conversiones, incluso cadenas vacías. El controlador de errores se ignora.
unicode_escape		Codificación adecuada como contenido de un literal Unicode en código fuente Python codificado en ASCII, excepto que no se escapan las comillas. Decodificar desde el código fuente Latin-1. Tenga en cuenta que el código fuente de Python realmente usa UTF-8 por defecto.

Distinto en la versión 3.8: Se elimina el códec «unicode_internal».

Transformaciones Binarias

Los siguientes códecs proporcionan transformaciones binarias: mapeos de bytes-like object a bytes. No son compatibles con bytes.decode() (que solo produce str de salida).

Códec	Aliases	Significado	Codificador / decodificador
base64_codec 1	base64, base_64	Convierta el operando a MIME base64 multilínea (el resultado siempre incluye un '\n' final). Distinto en la versión 3.4: acepta cualquier bytes-like object como entrada para codificar y decodificar	base64.encodebytes() / base64.decodebytes()
bz2_codec	bz2	Comprime el operando usando bz2.	bz2.compress() / bz2.decompress()
hex_codec	hex	Convierte el operando en representación hexadecimal, con dos dígitos por byte.	binascii.b2a_hex() / binascii.a2b_hex()
quopri_codec	quopri, quotedprintable, quoted_printable	Convierte el operando a MIME citado imprimible.	quopri.encode() con quotetabs=True / quopri.decode()
uu_codec	uu	Convierte el operando usando uuencode.	uu.encode() / uu.decode()
zlib_codec	zip, zlib	Comprime el operando usando gzip.	zlib.compress() / zlib.decompress()

1

Además de objetos similares a bytes, 'base64_codec' también acepta instancias solo ASCII de str para decodificación

Nuevo en la versión 3.2: Restauración de las transformaciones binarias.

Distinto en la versión 3.4: Restauración de los alias para las transformaciones binarias.

Transformaciones de texto

El siguiente códec proporciona una transformación de texto: un mapeo de str a str. No es compatible con str.encode() (que solo produce bytes de salida).

Códec	Aliases	Significado
rot_13	rot13	Retorna el cifrado César (Caesar-cypher) del operando.

Nuevo en la versión 3.2: Restauración de la transformación de texto rot_13.

Distinto en la versión 3.4: Restauración del alias rot13.

encodings.idna — Nombres de dominio internacionalizados en aplicaciones

Este módulo implementa RFC 3490 (nombres de dominio internacionalizados en aplicaciones) y RFC 3492 (Nameprep: un perfil de Stringprep para nombres de dominio internacionalizados (IDN)). Se basa en la codificación punycode y stringprep.

If you need the IDNA 2008 standard from RFC 5891 and RFC 5895, use the third-party idna module.

Estas RFC juntas definen un protocolo para admitir caracteres no ASCII en los nombres de dominio. Un nombre de dominio que contiene caracteres no ASCII (como www.Alliancefrançaise.nu) se convierte en una codificación compatible con ASCII (ACE, como www.xn--alliancefranaise-npb.nu). La forma ACE del nombre de dominio se utiliza en todos los lugares donde el protocolo no permite caracteres arbitrarios, como consultas DNS, campos HTTP Host, etc. Esta conversión se lleva a cabo en la aplicación; si es posible invisible para el usuario: la aplicación debe convertir de forma transparente las etiquetas de dominio Unicode a IDNA en el cable, y volver a convertir las etiquetas ACE a Unicode antes de presentarlas al usuario.

Python admite esta conversión de varias maneras: el códec idna realiza la conversión entre Unicode y ACE, separando una cadena de entrada en etiquetas basadas en los caracteres separadores definidos en la sección 3.1 de RFC 3490 RFC 3490#section-3.1 y convertir cada etiqueta a ACE según sea necesario, y por el contrario, separar una cadena de bytes de entrada en etiquetas basadas en el separador . y convertir cualquier etiqueta ACE encontrada en unicode. Además, el módulo socket convierte de forma transparente los nombres de host Unicode a ACE, por lo que las aplicaciones no necesitan preocuparse por convertir los nombres de host ellos mismos cuando los pasan al módulo de socket. Además de eso, los módulos que tienen nombres de host como parámetros de función, como http.client y ftplib, aceptan nombres de host Unicode (http.client y luego también envían un mensaje transparente IDNA hostname en el campo Host si envía ese campo).

Al recibir nombres de host desde el cable (como en la búsqueda inversa de nombres), no se realiza una conversión automática a Unicode: las aplicaciones que deseen presentar dichos nombres de host al usuario deben decodificarlos en Unicode.

El módulo encodings.idna también implementa el procedimiento nameprep, que realiza ciertas normalizaciones en los nombres de host, para lograr la insensibilidad a mayúsculas y minúsculas de los nombres de dominio internacionales y unificar caracteres similares. Las funciones nameprep se pueden usar directamente si lo desea.

encodings.idna.nameprep(label)

Retorna la versión pasada por nameprep (o versión nameprepped) de label. La implementación actualmente asume cadenas de caracteres de consulta, por lo que AllowUnassigned es verdadero.

encodings.idna.ToASCII(label)

Convierte una etiqueta a ASCII, como se especifica en RFC 3490. Se supone que UseSTD3ASCIIRules es falso.

encodings.idna.ToUnicode(label)

Convierte una etiqueta a Unicode, como se especifica en RFC 3490.

encodings.mbcs — Página de códigos ANSI de Windows

Este módulo implementa la página de códigos ANSI (CP_ACP).

Availability: solo Windows.

Distinto en la versión 3.3: Admite cualquier controlador de errores.

Distinto en la versión 3.2: Antes de 3.2, se ignoraba el argumento errors; 'replace' siempre se usó para codificar e 'ignore' para decodificar.

encodings.utf_8_sig — Códec UTF-8 con firma BOM

Este módulo implementa una variante del códec UTF-8. Al codificar, una lista de materiales codificada en UTF-8 se antepondrá a los bytes codificados en UTF-8. Para el codificador con estado esto solo se hace una vez (en la primera escritura en el flujo de bytes). En la decodificación, se omitirá una lista de materiales opcional codificada en UTF-8 al comienzo de los datos.