Portando código de Python 2 a Python 3

autor

Brett Cannon

Resumen

Dado que Python 3 es el futuro de Python mientras Python 2 todavía está en uso activo, es bueno tener su proyecto disponible para ambas versiones principales de Python. Esta guía está diseñada para ayudarle a averiguar la mejor manera de admitir Python 2 y 3 simultáneamente.

Si está buscando portar un módulo de extensión en lugar de código Python puro, consulte Portar módulos de extensión a Python 3.

Si desea leer la opinión de un desarrollador central de Python sobre por qué Python 3 nació, puede leer las Python 3 Q & A de Nick Coghlan o el artículo de Brett Cannon Why Python 3 exists.

For help with porting, you can view the archived python-porting mailing list.

La breve explicación

Para que su proyecto sea compatible con Python 2/3 de una sola fuente, los pasos básicos son:

1. Sólo preocúpate por admitir Python 2.7

2. Asegúrese de tener una buena cobertura de prueba (coberturas.py puede ayudar; python -m pip install coverage)

3. Aprende las diferencias entre Python 2 & 3

4. Utilice Futurize (o Modernize) para actualizar su código (por ejemplo, python -m pip install future)

5. Use Pylint para asegurarse de que no retrocede en su compatibilidad con Python 3 (python -m pip install pylint)

6. Use caniusepython3 para averiguar cuáles de sus dependencias están bloqueando el uso de Python 3 (python -m pip install caniusepython3)

7. Una vez que sus dependencias ya no lo bloqueen, use la integración continua para asegurarse de que sigue siendo compatible con Python 2 y 3 (tox puede ayudar a probar contra múltiples versiones de Python; python -m pip install tox)

8. Considere usar la verificación de tipo estática opcional para asegurarse de que su uso de tipo funcione tanto en Python 2 como en 3 (por ejemplo, use mypy para verificar su escritura en Python 2 y Python 3; python -m pip install mypy).

Nota

Nota: El uso de python -m pip install garantiza que el pip que invoca es el que está instalado para el Python actualmente en uso, ya sea un pip de todo el sistema o uno instalado dentro de un entorno virtual.

Detalles

Un punto clave sobre el soporte de Python 2 & 3 simultáneamente es que se puede empezar hoy! Incluso si sus dependencias no son compatibles con Python 3 todavía eso no significa que no puede modernizar el código ahora para admitir Python 3. La mayoría de los cambios necesarios para admitir Python 3 conducen a código más limpio utilizando prácticas más recientes incluso en código Python 2.

Otro punto clave es que la modernización del código de Python 2 para que también admita Python 3 está en gran medida automatizada para usted. Si bien es posible que tenga que tomar algunas decisiones de API gracias a python 3 aclarando los datos de texto frente a los datos binarios, el trabajo de nivel inferior ahora se realiza principalmente por usted y, por lo tanto, al menos puede beneficiarse de los cambios automatizados inmediatamente.

Tenga en cuenta esos puntos clave mientras lee sobre los detalles de la migración del código para admitir Python 2 & 3 simultáneamente.

Compatibilidad con Python 2.6 y versiones anteriores

Si bien puede hacer que Python 2.5 funcione con Python 3, es mucho más fácil si solo tiene que trabajar con Python 2.7. Si eliminar Python 2.5 no es una opción, entonces el proyecto six puede ayudarlo a admitir Python 2.5 y 3 simultáneamente (python -m pip install six). Sin embargo, tenga en cuenta que casi todos los proyectos enumerados en este COMO no estarán disponibles para usted.

Si puede omitir Python 2.5 y versiones anteriores, los cambios necesarios en el código deben seguir pareciendo código Python idiomático. En el peor de los casos tendrá que utilizar una función en lugar de un método en algunos casos o tendrá que importar una función en lugar de usar una integrada, pero de lo contrario la transformación general no debería sentirse ajena a usted.

Pero usted debe apuntar a sólo apoyar Python 2.7. Python 2.6 ya no se admite libremente y, por lo tanto, no recibe correcciones de errores. Esto significa que usted tendrá que solucionar cualquier problema que encuentre con Python 2.6. También hay algunas herramientas mencionadas en este HOWTO que no son compatibles con Python 2.6 (por ejemplo, Pylint), y esto se volverá más común a medida que pasa el tiempo. Simplemente será más fácil para usted si sólo admite las versiones de Python que tiene que admitir.

Asegúrese de especificar el soporte de versión adecuado en su archivo setup.py

En su archivo setup.py debe tener el trove classifier adecuado especificando qué versiones de Python admite. Como su proyecto no es compatible con Python 3, al menos debe tener Programming Language :: Python :: 2 :: Only especificado. Idealmente también debe especificar cada versión principal/menor de Python que admita, por ejemplo, Programming Language :: Python :: 2.7.

Tener una buena cobertura de prueba

Una vez que tenga su código compatible con la versión más antigua de Python 2 que desee, querrá asegurarse de que su conjunto de pruebas tenga una buena cobertura. Una buena regla general es que si desea tener la suficiente confianza en su conjunto de pruebas, cualquier falla que aparezca después de que las herramientas reescriban su código son errores reales en las herramientas y no en su código. Si desea un número al que apuntar, intente obtener una cobertura superior al 80% (y no se sienta mal si le resulta difícil obtener una cobertura superior al 90%). Si aún no tiene una herramienta para medir la cobertura de la prueba, se recomienda cover.py.

Aprende las diferencias entre Python 2 & 3

Una vez que tenga su código bien probado, ¡está listo para comenzar a migrar su código a Python 3! Pero para comprender completamente cómo va a cambiar el código y qué desea tener en cuenta mientras codifica, querrá aprender qué cambios produce Python 3 en términos de Python 2. Típicamente las dos mejores maneras de hacer eso es leer la documentación «What’s New» para cada versión de Python 3 y el libro Porting to Python 3 (que es gratis en línea). También hay una práctica cheat sheet del proyecto Python-Future.</whatsnew-index>.

Actualiza tu código

Una vez que sientas que sabes lo que es diferente en Python 3 en comparación con Python 2, ¡es hora de actualizar tu código! Puede elegir entre dos herramientas para migrar el código automáticamente: Futurize y Modernize. La herramienta que elija dependerá de la cantidad similar a Python 3 que desea que sea el código. Futurize hace todo lo posible para que Python 3 modismos y prácticas existan en Python 2, por ejemplo, backporting el tipo bytes de Python 3 para que tenga paridad semántica entre las versiones principales de Python. Modernize, por otro lado, es más conservador y se dirige a un subconjunto de Python 2/3 de Python, basándose directamente en six para ayudar a proporcionar compatibilidad. Como Python 3 es el futuro, podría ser mejor considerar Futurize para comenzar a adaptarse a cualquier nueva práctica que Python 3 introduce a la que aún no está acostumbrado.

Independientemente de la herramienta que elija, actualizarán el código para que se ejecute en Python 3 mientras se mantienen compatibles con la versión de Python 2 con la que comenzó. Dependiendo de lo conservador que desee ser, es posible que desee ejecutar la herramienta sobre el conjunto de pruebas primero e inspeccionar visualmente la diferencia para asegurarse de que la transformación es precisa. Después de transformar el conjunto de pruebas y comprobar que todas las pruebas siguen pasando según lo esperado, puede transformar el código de la aplicación sabiendo que cualquier prueba que falle es un error de traducción.

Desafortunadamente, las herramientas no pueden automatizar todo para que su código funcione bajo Python 3 y por lo que hay un puñado de cosas que tendrá que actualizar manualmente para obtener soporte completo de Python 3 (cuáles de estos pasos son necesarios varían entre las herramientas). Lea la documentación de la herramienta que elige utilizar para ver lo que corrige de forma predeterminada y lo que puede hacer opcionalmente para saber lo que (no) se fijará para usted y lo que puede tener que corregir por su cuenta (por ejemplo, usando io.open() sobre la función incorporada open() está desactivada por defecto en Modernizar). Afortunadamente, sin embargo, sólo hay un par de cosas a tener en cuenta por las cuales se pueden considerar grandes problemas que pueden ser difíciles de depurar si no se observan.

División

En Python 3, 5 / 2 == 2.5 y no 2; toda división entre los valores int da lugar a un float. Este cambio ha sido planeado desde Python 2.2, que fue lanzado en 2002. Desde entonces, se ha alentado a los usuarios a añadir from __future__ import division a todos y cada uno de los archivos que utilizan los operadores / y // o que ejecuten el intérprete con el indicador -Q. Si no ha estado haciendo esto, entonces tendrá que ir a través de su código y hacer dos cosas:

1. Añadir from __future__ import division a sus archivos

2. Actualice cualquier operador de división según sea necesario para utilizar // para usar la división de suelo o continuar usando / y esperar un número flotante

La razón por la que / no se traduce simplemente a // automáticamente es que si un objeto define un método __truediv__ pero no __floordiv__ entonces su código comenzaría a fallar (por ejemplo, una clase definida por el usuario que utiliza / para significar alguna operación pero no // para la misma cosa o en absoluto).

Texto frente a datos binarios

En Python 2 puede usar el tipo str tanto para texto como para datos binarios. Desafortunadamente, esta confluencia de dos conceptos diferentes podría conducir a código frágil que a veces funcionaba para cualquier tipo de datos, a veces no. También podría dar lugar a API confusas si las personas no declaraban explícitamente que algo que aceptaba str aceptaba datos binarios o de texto en lugar de un tipo específico. Esto complicó la situación especialmente para cualquier persona que admita varios idiomas, ya que las API no se molestarían explícitamente en admitir explícitamente Unicode cuando reclamaban compatibilidad con datos de texto.

Para hacer la distinción entre texto y datos binarios más claros y pronunciados, Python 3 hizo lo que la mayoría de los lenguajes creados en la era de Internet han hecho y ha hecho texto y datos binarios distintos tipos que no se pueden mezclar ciegamente (Python es anterior al acceso generalizado a Internet). Para cualquier código que se ocupe solo de texto o solo de datos binarios, esta separación no plantea un problema. Pero para el código que tiene que lidiar con ambos, significa que es posible que tenga que preocuparse ahora cuando está utilizando texto en comparación con los datos binarios, por lo que esto no se puede automatizar por completo.

Para empezar, tendrá que decidir qué API toman texto y cuáles toman binario (es altamente recomendado no diseñar API que pueden tomar ambos debido a la dificultad de mantener el código funcionando; como se indicó anteriormente es difícil hacerlo bien). En Python 2 esto significa asegurarse de que las API que toman texto pueden trabajar con unicode y las que funcionan con datos binarios funcionan con el tipo bytes de Python 3 (que es un subconjunto de str en Python 2 y actúa como un alias para bytes tipo en Python 2). Por lo general, el mayor problema es darse cuenta de qué métodos existen en qué tipos en Python 2 y 3 simultáneamente (para el texto que es Unicode en Python 2 y str en Python 3, para binario que es str/bytes en Python 2 y bytes en Python 3). En la tabla siguiente se enumeran los métodos unicos de cada tipo de datos en Python 2 y 3 (por ejemplo, el método decode() se puede utilizar en el tipo de datos binarios equivalente en Python 2 o 3, pero no puede ser utilizado por el tipo de datos textuales consistentemente entre Python 2 y 3 porque str en Python 3 no tiene el método). Tenga en cuenta que a partir de Python 3.5 se agregó el método __mod__ al tipo bytes.

Datos de texto	Datos binarios
	decode
encode
format
isdecimal
isnumeric

La creación de la distinción más fácil de controlar se puede realizar mediante la codificación y descodificación entre datos binarios y texto en el borde del código. Esto significa que cuando reciba texto en datos binarios, debe descodificarlo inmediatamente. Y si el código necesita enviar texto como datos binarios, codificarlo lo más tarde posible. Esto permite que el código funcione solo con texto internamente y, por lo tanto, elimina tener que realizar un seguimiento del tipo de datos con los que está trabajando.

El siguiente problema es asegurarse de saber si los literales de cadena en el código representan texto o datos binarios. Debe agregar un prefijo b a cualquier literal que presente datos binarios. Para el texto debe agregar un prefijo u al literal de texto. (hay una importación __future__ para forzar que todos los literales no especificados sean Unicode, pero el uso ha demostrado que no es tan eficaz como agregar un prefijo b o u a todos los literales explícitamente)

Como parte de esta dicotomía también hay que tener cuidado con la apertura de archivos. A menos que haya estado trabajando en Windows, existe la posibilidad de que no siempre se haya molestado en agregar el modo b al abrir un archivo binario (por ejemplo, rb para la lectura binaria). En Python 3, los archivos binarios y los archivos de texto son claramente distintos y mutuamente incompatibles; ver el módulo io para más detalles. Por lo tanto, debe tomar una decisión de si un archivo se utilizará para el acceso binario (permitiendo que los datos binarios se lean y/o escriban) o el acceso textual (permitiendo que los datos de texto sean leídos y/o escritos). También debe utilizar io.open() para abrir archivos en lugar de la función incorporada open() como el módulo io es consistente de Python 2 a 3, mientras que la función incorporada open() no es (en Python 3 es en realidad io.open()). No se moleste con la práctica obsoleta de usar codecs.open() ya que sólo es necesario para mantener la compatibilidad con Python 2.5.

Los constructores de str y bytes tienen una semántica diferente para los mismos argumentos entre Python 2 y 3. Pasar un entero a bytes en Python 2 le dará la representación de cadena de texto del entero: bytes(3) == '3'. Pero en Python 3, un argumento entero para “”bytes”” le dará un objeto bytes siempre y cuando el entero especificado, lleno de bytes nulos: bytes(3) == b'\x00\x00\x00'. Una preocupación similar es necesaria cuando se pasa un objeto bytes a str. En Python 2, solo se obtiene el objeto bytes: str(b'3') == b'3'. Pero en Python 3 se obtiene la representación de cadena de texto del objeto bytes: str(b'3') == "b'3'".

Por último, la indexación de datos binarios requiere un control cuidadoso (el corte no requiere ningún control especial). En Python 2, b'123'[1] == b'2' mientras que en Python 3 b'123'[1] == 50. Dado que los datos binarios son simplemente una colección de números binarios, Python 3 devuelve el valor entero para el byte en el que indexa. Pero en Python 2, ya que bytes == str, la indexación devuelve un segmento de bytes de un solo elemento. El proyecto six tiene una función denominada six.indexbytes() que devolverá un entero como en Python 3: six.indexbytes(b'123', 1).

Para resumir:

1. Decida cuál de sus API toma texto y cuáles toman datos binarios

2. Asegúrese de que el código que funciona con texto también funciona con unicode y el código para datos binarios funciona con bytes en Python 2 (consulte la tabla anterior para los métodos que no puede usar para cada tipo)

3. Marque todos los literales binarios con un prefijo b, literales textuales con un prefijo u

4. Descodificar datos binarios en texto tan pronto como sea posible, codificar texto como datos binarios tan tarde como sea posible

5. Abra los archivos con io.open() y asegúrese de especificar el modo b cuando sea apropiado

6. Tenga cuidado al indexar en datos binarios

Utilice la detección de funciones en lugar de la detección de versiones

Inevitablemente tendrá código que tiene que elegir qué hacer en función de qué versión de Python se está ejecutando. La mejor manera de hacerlo es con la detección de características de si la versión de Python en la que se ejecuta es compatible con lo que necesita. Si por alguna razón eso no funciona, entonces usted debe hacer que la comprobación de la versión sea contra Python 2 y no Python 3. Para ayudar a explicar esto, veamos un ejemplo.

Supongamos que necesita acceso a una característica de importlib que está disponible en la biblioteca estándar de Python desde Python 3.3 y disponible para Python 2 a través de importlib2 en PyPI. Es posible que tenga la tentación de escribir código para acceder, por ejemplo, al módulo importlib.abc haciendo lo siguiente:

import sys

if sys.version_info[0] == 3:
    from importlib import abc
else:
    from importlib2 import abc

El problema con este código es ¿qué sucede cuando sale Python 4? Sería mejor tratar Python 2 como el caso excepcional en lugar de Python 3 y asumir que las futuras versiones de Python serán más compatibles con Python 3 que Python 2:

import sys

if sys.version_info[0] > 2:
    from importlib import abc
else:
    from importlib2 import abc

La mejor solución, sin embargo, es no hacer ninguna detección de versiones en absoluto y en su lugar confiar en la detección de características. Esto evita cualquier problema potencial de conseguir la detección de la versión incorrecta y le ayuda a mantenerse compatible con el futuro:

try:
    from importlib import abc
except ImportError:
    from importlib2 import abc

Evitar regresiones de compatibilidad

Una vez que haya traducido completamente el código para que sea compatible con Python 3, querrá asegurarse de que el código no retroceda y deje de funcionar bajo Python 3. Esto es especialmente cierto si tiene una dependencia que le está bloqueando para que no se ejecute realmente en Python 3 en este momento.

Para ayudar a mantenerse compatible, los módulos nuevos que cree deben tener al menos el siguiente bloque de código en la parte superior del misma:

from __future__ import absolute_import
from __future__ import division
from __future__ import print_function

También puede ejecutar Python 2 con el indicador -3 para recibir una advertencia sobre varios problemas de compatibilidad que el código desencadena durante la ejecución. Si convierte las advertencias en errores con -Werror, puede asegurarse de que no se pierda accidentalmente una advertencia.

También puede usar el proyecto de Pylint y su indicador --py3k para lintar el código para recibir advertencias cuando el código comienza a desviarse de la compatibilidad con Python 3. Esto también evita que tenga que ejecutar Modernize o Futurize sobre el código con regularidad para detectar las regresiones de compatibilidad. Esto requiere que solo admita Python 2.7 y Python 3.4 o posterior, ya que es la compatibilidad mínima de la versión mínima de Python de Pylint.

Compruebe qué dependencias bloquean la transición

Después de que haya hecho que su código sea compatible con Python 3, debe empezar a preocuparse por si sus dependencias también se han portado. El proyecto caniusepython3 se creó para ayudarle a determinar qué proyectos – directa o indirectamente – le impiden admitir Python 3. Hay una herramienta de línea de comandos, así como una interfaz web en https://caniusepython3.com.

El proyecto también proporciona código que puede integrar en el conjunto de pruebas para que tenga una prueba con errores cuando ya no tenga dependencias que le impidan usar Python 3. Esto le permite evitar tener que comprobar manualmente sus dependencias y recibir notificaciones rápidamente cuando puede empezar a ejecutarse en Python 3.

Actualice su archivo setup.py para denotar compatibilidad con Python 3

Una vez que el código funciona en Python 3, debe actualizar los clasificadores en su setup.py para que contenga Programming Language :: Python :: 3 y no especificar solo compatibilidad con Python 2. Esto le dirá a cualquier persona que use su código que admite Python 2 y 3. Lo ideal es que también desee agregar clasificadores para cada versión principal/menor de Python que ahora admita.

Utilice la integración continua para seguir siendo compatible

Una vez que pueda ejecutar completamente bajo Python 3, querrá asegurarse de que el código siempre funciona en Python 2 y 3. Probablemente la mejor herramienta para ejecutar las pruebas en varios intérpretes de Python es tox. A continuación, puede integrar tox con su sistema de integración continua para que nunca interrumpa accidentalmente la compatibilidad con Python 2 o 3.

También es posible que desee utilizar el indicador -bb con el intérprete de Python 3 para desencadenar una excepción cuando se comparan bytes con cadenas o bytes con un int (este último está disponible a partir de Python 3.5). De forma predeterminada, las comparaciones de tipos diferentes simplemente devuelven False, pero si cometió un error en la separación del control de datos de texto/binario o la indexación en bytes, no encontraría fácilmente el error. Esta marca generará una excepción cuando se produzcan este tipo de comparaciones, lo que hace que el error sea mucho más fácil de rastrear.

¡Y eso es sobre todo! En este punto, la base de código es compatible con Python 2 y 3 simultáneamente. Las pruebas también se configurarán para que no interrumpa accidentalmente la compatibilidad de Python 2 o 3, independientemente de la versión en la que ejecute normalmente las pruebas durante el desarrollo.

Considere la posibilidad de usar la comprobación de tipos estáticos opcionales

Otra forma de ayudar a transferir el código es usar un comprobador de tipos estáticos como mypy o pytype en el código. Estas herramientas se pueden utilizar para analizar el código como si se estuviera ejecutando en Python 2, puede ejecutar la herramienta por segunda vez como si el código se ejecutara en Python 3. Al ejecutar un comprobador de tipos estáticos dos veces como este, puede descubrir si, por ejemplo, está usando incorrectamente el tipo de datos binarios en una versión de Python en comparación con otra. Si agrega sugerencias de tipo opcionales al código, también puede indicar explícitamente si las API usan datos textuales o binarios, lo que ayuda a asegurarse de que todo funciona según lo esperado en ambas versiones de Python.