10 pasos para un proyecto exitoso de Python

El material, cuya traducción publicamos hoy, está dedicado a herramientas que permiten equipar proyectos de Python con herramientas de formato de código, pruebas, integración continua y análisis de dependencia. Esto ayuda a acelerar el proceso de desarrollo, ayuda a mejorar la calidad, uniformidad y seguridad del código. Se supone que el lector de este material ya tiene cierta experiencia en el desarrollo de Python y un proyecto de Python con el que, durante la lectura, experimentará. Si no tiene un proyecto de este tipo , aquí puede aprender cómo preparar un entorno de desarrollo y crear un paquete de Python. Los ejemplos que se darán aquí se preparan con macOS y Python 3.7.

Paso 1. Instalando Black

El código del proyecto debe seguir las convenciones de estilo de código. Black es un paquete de Python que formatea automáticamente el código, dando su apariencia al estándar PEP 8 . El negro es un proyecto relativamente nuevo, pero ya ha ganado más de un millón de descargas. Su uso se convirtió rápidamente en una señal de buen gusto en el desarrollo de Python. Aquí está el manual de Black.

Yo, como editor de código, uso Atom, así que agregué el paquete Python-Black a Atom. Puede averiguar cómo instalarlo aquí . Después de instalar este paquete, Atom formateará el código después de guardar el archivo.

Mientras hablamos de Black, equipemos esta herramienta con el entorno de desarrollo de aquellos que trabajan con nosotros en el proyecto. Como resultado, todos los que trabajan en el proyecto utilizarán las mismas reglas de formato de código; de lo contrario, no se aceptarán sus solicitudes de extracción.

Agregue el black==18.9b0 a la primera línea libre encontrada del archivo black==18.9b0 y ejecute el comando install -r requirements_dev.txt black==18.9b0 .

Negro, por defecto, establece la longitud de la línea de código en 88 caracteres. Algunas guías de estilo, como Sphinx , requieren una longitud de cadena de 79 caracteres. En la configuración del paquete Black-Atom , puede establecer la longitud de línea deseada.

Ahora que tenemos una herramienta que ayudará a ahorrar tiempo en el formato del código, pensaremos en cómo acelerar y simplificar el envío de código a PyPI.

Paso 2. Crear el archivo .pypirc

Cuando se utiliza el hilo para enviar ensamblajes de aplicaciones a TestPyPI y PyPI, debe ingresar manualmente la información de inicio de sesión. Si no está familiarizado con el hilo, eche un vistazo a este material. Ahora automatizaremos este proceso.

Twine puede funcionar con el archivo .pypirc , que debe estar en nuestro directorio de inicio. Esta herramienta, que descarga datos, toma una URL, nombre de usuario y contraseña de un archivo determinado.

Por lo tanto, cree un archivo .pypirc en su directorio de inicio:

 touch ~/.pypirc 

Agregue el siguiente texto:

 [distutils] index-servers =   pypi   testpypi [testpypi] repository: https://test.pypi.org/legacy username = your_username password = your_pypitest_password [pypi] username = your_username password = your_pypi_password 

Está claro que aquí debe ingresar su nombre de usuario y contraseña reales. Además, verifique que este archivo esté guardado en el directorio de inicio y no en el directorio de trabajo actual. Si desea proteger este archivo de otros usuarios, puede, utilizando las herramientas de línea de comandos, configurar sus permisos:

 chmod 600 ~/.pypirc 

Ahora su paquete puede cargarse en TestPyPI usando el siguiente comando:

 twine upload -r testpypi dist/* 

En PyPI normal, puede cargar paquetes como este:

 twine upload dist/* 

Después de obtener el archivo .pypirc , ya no tiene que ingresar manualmente su nombre de usuario y contraseña.

Ahora agreguemos herramientas de prueba a nuestro entorno de desarrollo que nos permitirán verificar el funcionamiento correcto del paquete que estamos creando.

Paso 3. Instalar y configurar pytest

Pytest es la biblioteca más popular y fácil de usar para probar el código escrito en Python. En este ejemplo, agregaremos pruebas simples al proyecto. Ahora , si está interesado en los detalles de pytest, una buena guía introductoria de esta herramienta.

Agregue detalles de pytest a require_dev.txt:

 pytest==4.3.0 

Instalemos el paquete:

 pip install requirements_dev.txt 

Ahora ejecute el siguiente comando, que permitirá que pytest encuentre nuestro paquete:

 pip install -e . 

Si desactivó su entorno de desarrollo virtual, deberá ejecutar ambos comandos pip nuevamente para ejecutar las pruebas.

Paso 4. Crear pruebas

Agregue la carpeta de test al directorio raíz de su proyecto. Coloque el archivo test_your_package_name.py en él. Mi archivo se llama test_notebookc.py . Si el nombre del archivo comienza con test_ , pytest puede detectar automáticamente dicho archivo.

test_notebookc.py la siguiente prueba al archivo test_notebookc.py , cuyo objetivo es verificar si la función muestra el nombre correcto. Modifique este código para que los nombres de archivo y función utilizados coincidan con los suyos, describa sus propias pruebas en él.

 """Tests for `notebookc` package.""" import pytest from notebookc import notebookc def test_convert(capsys):   """Correct my_name argument prints"""   notebookc.convert("Jill")   captured = capsys.readouterr()   assert "Jall" in captured.out 

¿Qué está pasando aquí?

Primero importamos nuestro módulo aquí. Luego creamos una función cuyo nombre se construye de acuerdo con la plantilla test_my_function_name . Esta convención de nomenclatura de funciones permite que otras personas que lean el código de su proyecto comprendan rápidamente qué se está probando exactamente en las pruebas. Además, esto es necesario para un paquete que ayuda a controlar la cobertura del código con las pruebas, que discutiremos a continuación.

Después de eso, llamamos a la función ( convert ), pasándole el nombre de Jill como argumento. Siguiente: captura lo que muestra la función. Aquí vale la pena decir que la función en cuestión es extremadamente simple. Ella toma el parámetro my_name y hace lo siguiente:

 print(f"I'll convert a notebook for you some day, {my_name}.") 

Pytest verifica si Jall está Jall en lo que genera la función. Esta línea no debería estar allí, ya que pasamos las funciones de Jill . Aquí está la documentación de pytest donde puede encontrar información sobre la salida de interceptación.

Ejecute la prueba escribiendo pytest en el símbolo del sistema. Esta prueba debería fallar. La información del error se muestra en rojo.


Se detectó un error durante la prueba.

Se recomienda verificar la exactitud de las pruebas, describiéndolas para que, bajo ciertas condiciones, terminen con un error. No debe escribir pruebas que solo emitan mensajes verdes, ya que de lo contrario puede resultar que las pruebas no comprueben en absoluto lo que están escritas para verificar.

Después de asegurarnos de que la prueba falló, cambie la declaración de Jall a Jill y vuelva a ejecutar la prueba. Ahora debería completarse con éxito.


Finalización exitosa de la prueba.

Ahora todo está bien. La prueba le permite asegurarse de que si alguien pasa una línea a nuestra función, esta línea caerá en el texto que muestra esta función.

También puede escribir una prueba que verifique la función sobre cómo maneja los datos que se le pasan. Es decir, si recibe datos cuyo tipo es diferente de la cadena, debería causar un error TypeError. Aquí hay algunas cosas buenas sobre excepciones y manejo de errores en Python.

Cuando creamos la prueba anterior, escribimos un código que conduce a la finalización exitosa de la prueba. Esto se llama desarrollo impulsado por pruebas (TDD). TDD es un enfoque de programación probado que lo ayuda a escribir código que tiene menos errores de lo que lo haría sin TDD. Aquí hay material útil de TDD.

Ahora, como ejercicio, intente escribir una prueba que verifique la función convert() para que al pasarle algo diferente de la cadena, arroje un error e implemente los mecanismos apropiados para esta función. Tenga en cuenta que los enteros, las listas y los diccionarios se convierten en cadenas.

Después de que el paquete haya pasado con éxito las pruebas, estamos listos para aprovechar el sistema de integración continua.

Paso 5. Registro en el servicio Travis CI y su configuración

Travis CI es un "servicio web distribuido para crear y probar software". Fue comprado recientemente por Idera . Existen otros sistemas de integración continua, pero Travis CI es una herramienta popular, de código abierto y bien documentada, por lo que la utilizaremos.

Travis CI le permite integrar en su proyecto solo el código que pasa las pruebas y cumple con los estándares. Aquí puede leer más sobre Travis CI, y aquí sobre la integración continua.

Cree una cuenta en https://travis-ci.org/ . A continuación, haga clic en el enlace Review and add your authorized organizations en la página de perfil. Se le pedirá una contraseña para acceder a GitHub. Haga clic en Grant en la sección de Organization access la Organization access .


Configurar una cuenta de Travis CI

Necesitaba sincronizar la cuenta para que la información sobre notebooktoall y el repositorio de notebookc aparecieran en la cuenta. Por lo general, para que Travis CI funcione con código, se tarda aproximadamente un minuto. Después de eso, debe activar el repositorio utilizando el interruptor que se muestra en la siguiente figura.


Activación de repositorio

Ahora haga clic en el botón Settings . Aquí debe indicar si Travis puede construir basándose en solicitudes de extracción o ramas enviadas al repositorio.


Configuración de construcción del proyecto

Ahora es el momento de configurar el proyecto en el que estamos trabajando, lo que permitirá a Travis construir el proyecto para cada solicitud de extracción.

Paso 6. Crear el archivo .travis.yml

En la carpeta raíz del proyecto, cree un archivo .travis.yml con el siguiente contenido:

 dist: xenial language: python python: 3.7.2 install: - pip install -r requirements_dev.txt - pip install -e . script: - pytest 

La línea dist: xenial necesaria para decirle a Travis que use Ubuntu Xenial 16.04 para organizar el entorno virtual. Para probar el código Python 3.7, se necesita Ubuntu Xenial, los detalles sobre esto se pueden encontrar aquí .

La sección de install permite instalar paquetes utilizados en el desarrollo de proyectos. pip install -e . comando realiza la instalación de nuestro paquete en el entorno virtual de Travis. Después de eso, Travis, comenzando pytest, podrá encontrar nuestro paquete.

Paso 7. Pruebas en Travis CI

Confirma los cambios, envíalos a GitHub, haz el PR. Travis debería comenzar a trabajar en segundos.


Travis en el trabajo

Esto es lo que Travis hace al manejar el proyecto.


Acciones realizadas por Travis durante el procesamiento del proyecto

Si el RP no tuvo éxito, Travis lo informará. Tenga en cuenta que si la solicitud de extracción no tiene éxito, puede enviar los cambios a la misma sucursal y Travis comenzará a funcionar automáticamente.

Vaya a su página de repositorio en el sitio web de Travis y mire a su alrededor. Aquí puede encontrar muchas cosas interesantes sobre ensamblajes. Probablemente en el futuro se convertirá en un invitado frecuente de esta página cuando intente comprender qué causó el ensamblaje fallido.

Si suponemos que todo salió bien, si la página contiene etiquetas verdes, la verificación y el montaje del proyecto tuvieron éxito.


Proyecto ensamblado completado con éxito

Si no hay etiquetas verdes o rojas en la página, abra el menú More options y seleccione Requests . Si ve mensajes de error rojos aquí, analícelos. Si ve que el Build config file is required un mensaje de error, significa que Travis no puede encontrar su archivo .travis.yml en el repositorio. Corríjalo y el error desaparecerá.

Travis envía correos electrónicos a los usuarios en los casos en que el ensamblaje del proyecto no tiene éxito y en los casos en que es posible arreglarlo.

Recuerde que puede enviar confirmaciones para abrir relaciones públicas y Travis reiniciará automáticamente el proceso de compilación del proyecto.

Ahora analicemos nuestro proyecto para cubrir el código con pruebas.

Paso 8. Evaluar la cobertura del código con pruebas

El informe sobre la cobertura del código con pruebas le permite averiguar qué parte del código del proyecto, aunque sea pequeño, se ha probado. Para crear dichos informes, utilizaremos el paquete pytest-cov .

Agregue la siguiente línea al archivo require_dev.txt:

 pytest-cov==2.6.1 

Ejecute el siguiente comando:

 pytest --cov=my_project_name 

En mi caso, después de que se pytest --cov=notebookc , se mostró el siguiente informe.


Informe de cobertura de código

Al final resultó que, todo el código del proyecto se proporciona con pruebas. Tales indicadores son muy fáciles de lograr si todo el proyecto consta de varias líneas de código.

Ahora hablemos de una herramienta que le permite mantener un historial público del estado del proyecto en términos de cubrir su código con pruebas.

Paso 9. Usando Overoles

El proyecto Overol le permite mantener información histórica sobre la cobertura del código con las pruebas.


Overoles

Para aprovechar las capacidades de este proyecto, debe registrarse en el sitio https://coveralls.io/ utilizando los datos de su cuenta de GitHub. Entonces necesitas conectar el repositorio.

En el archivo require_dev.txt, agregue los coveralls==1.6.0 línea coveralls==1.6.0 . Este archivo, por cierto, en esta etapa del trabajo en el proyecto debería verse así:

 pip==19.0.3 wheel==0.33.0 twine==1.13.0 pytest==4.3.0 pytest-cov==2.6.1 coveralls==1.6.0 

.travis.yml archivo .travis.yml , llevándolo a este formulario (en su caso, el nombre de su proyecto estará aquí):

 dist: xenial language: python python: 3.7.2 install: — pip install -r requirements_dev.txt — pip install -e . script: — pytest --cov=my_package_name after_success: — coveralls 

Ahora, cuando Travis construirá el proyecto, instalará los paquetes necesarios, ejecutará las pruebas y creará un informe sobre la cobertura del código con las pruebas. Luego, este informe se enviará al servicio de Overoles.

Comprometerse, enviar el código a GitHub y ver qué sucede. Es posible que el informe de la prueba de cobertura del código tarde unos minutos en ingresar a Overol.


Procesamiento del proyecto, informe de cobertura de prueba

Ahora, entre las comprobaciones de relaciones públicas, también hay una comprobación realizada por Overol.

En la página Overoles, puede verificar que el proyecto esté 100% cubierto en las pruebas.


Información de cobertura de prueba

Ahora equipemos nuestro proyecto con otra herramienta útil.

Paso 10. Trabajando con PyUp

El servicio PyUp.io le permite al desarrollador averiguar si las dependencias utilizadas por él están desactualizadas y si tienen vulnerabilidades. Este servicio ejecuta automáticamente solicitudes de extracción destinadas a actualizar el paquete en GitHub. Para aprovechar las capacidades de este proyecto, debe registrarse utilizando una cuenta de GitHub, en su sitio web: https://pyup.io/ . Al agregar un repositorio, se recomienda establecer los Update Schedules every week . Con este enfoque, si su proyecto tiene muchas dependencias, no encontrará demasiadas solicitudes de extracción.


Configurar actualizaciones

Así es como se ve la información del paquete, algunas de las cuales están desactualizadas, en el sitio web PyUp.io.


Detalles del paquete

Con este servicio, siempre sabrá cuándo salen las últimas versiones de los paquetes que utiliza. El conocimiento, como dicen, es la mitad de la victoria. Y la segunda mitad es, obviamente, solicitudes automáticas de extracción para actualizar las dependencias.

Resumen

En este artículo, aprendió a usar herramientas como Black, pytest, Travis CI, Overol y PyUp al desarrollar proyectos de Python. Ayudan a controlar las dependencias del proyecto, formatear y probar el código, y verificar y construir proyectos. Esperamos que encuentre útiles estas herramientas.

Estimados lectores! ¿Qué herramientas utilizas al desarrollar proyectos de Python?