Categorías
Python

Python formato de cadenas de Buenas Prácticas

 

Tabla de Contenidos

  • de línea de comandos de aplicaciones LayoutsOne-Off ScriptInstallable individual PackageApplication con Interno Paquetes
  • una sola vez Guión
  • instalable solo paquete
  • Aplicación

  • con Interno Paquetes
  • de aplicaciones web LayoutsDjangoFlask
  • Django
  • Frasco
  • conclusiones y Avisos de
  • una sola vez Guión
  • instalable solo paquete
  • de aplicación con interno Paquetes
  • Django
  • Frasco

Python, aunque obstinado sobre la sintaxis y el estilo, es sorprendentemente flexible cuando se trata de la estructuración de sus aplicaciones.

Por un lado, esta flexibilidad es grande: permite diferentes casos de uso para utilizar estructuras que son necesarias para los casos de uso. Por otro lado, sin embargo, puede ser muy confuso para el nuevo desarrollador.

Internet no es de mucha ayuda, ya sea: hay tantas opiniones como hay blogs Python. En este artículo, quiero darle una guía de referencia diseño de la aplicación Python confiable que puede hacer referencia a la gran mayoría de los casos de uso .

Vas a ver ejemplos de estructuras comunes de aplicación de Python, incluyendo las aplicaciones de línea de comandos (CLI), aplicaciones de una sola vez guiones, paquetes instalables y diseños de aplicaciones web con marcos populares como Frasco y Django.

Nota: Esta guía de referencia supone un conocimiento práctico de los módulos y paquetes de Python. Visita nuestra introducción a los módulos y paquetes de Python para una actualización si se siente un poco oxidado.

de línea de comandos Distribución de Aplicación

Muchos de nosotros trabajamos principalmente con aplicaciones de Python que se ejecutan a través de interfaces de línea de comandos (CLI). Aquí es donde se suelen partir de un lienzo en blanco, y la flexibilidad de los diseños de aplicaciones Python puede ser un verdadero dolor de cabeza.

A partir de una carpeta de proyecto vacío puede ser intimidante y conducir a la escasez de bloqueo del codificador. En esta sección, quiero compartir algunos diseños probados que personalmente uso como punto de partida para todas mis aplicaciones Python CLI.

Vamos a empezar con un diseño muy básico para un caso de uso muy básico: un simple script que se ejecuta en su propio. A continuación, verá cómo construir el diseño como el avance casos de uso.

una sola vez Guión

Usted acaba de hacer un script .py, y de salsa, ¿verdad? No es necesario instalar-basta con ejecutar la secuencia de comandos en su directorio!

Bueno, eso está bien si sólo está haciendo una secuencia de comandos para su propio uso, o uno que no tiene ninguna dependencia externa, pero lo que si hay que distribuirlo? Especialmente a un usuario menos experto en tecnología?

El siguiente distribución funcionará para todos estos casos y puede ser fácilmente modificado para reflejar cualquier instalación o otras herramientas que utiliza en su flujo de trabajo. En este diseño se le cubrirá si va a crear un script Python puro (es decir, uno sin dependencias) o el uso de una herramienta como PIP o Pipenv.

Mientras usted lee esta guía de referencia, tenga en cuenta que la ubicación exacta de los archivos en los asuntos de diseño menos que la razón por la que se colocan donde están. Todos estos archivos deben estar en un directorio del proyecto lleva el nombre de su proyecto. Para este ejemplo, vamos a utilizar (¿qué otra cosa?) Holamundo como el nombre del proyecto y el directorio raíz.

Aquí está la estructura del proyecto Python Me suelen utilizar para una aplicación CLI:

helloworld/

├── .gitignore
├── helloworld.py
├── LICENSE
├── README.md
├── requirements.txt
├── setup.py
└── tests.py

Esto es muy sencillo: todo está en el mismo directorio. Los archivos que se muestran aquí no son necesariamente exhaustiva, pero se recomienda mantener el número de archivos a un mínimo si se desea usar un diseño básico como este. Algunos de estos archivos será nuevo para ti, así que vamos a echar un vistazo rápido a lo que cada uno de ellos hace.

  • .gitignore: Este es un archivo que le dice a Git qué tipos de archivos de ignorar, como el desorden IDE o archivos de configuración local. Nuestra Git tutorial tiene todos los detalles, y se pueden encontrar los archivos de muestra .gitignore para proyectos pitón aquí.
  • helloworld.py: Este es el script que se está distribuyendo. Por lo que el nombre del archivo principal de la escritura va, le recomiendo que vaya con el nombre de su proyecto (que es el mismo que el nombre del directorio de nivel superior).
  • LICENCIA: Este archivo de texto plano describe la licencia que está utilizando para un proyecto. Es siempre una buena idea tener uno si usted está distribuyendo código. El nombre del archivo es en todas las tapas de convention.Note: Ayuda de la necesidad de seleccionar una licencia para su proyecto? Salida ChooseALicense.
  • README.md: Este es un archivo de rebajas (o reStructuredText) documentar el propósito y el uso de su aplicación. La elaboración de un buen README es un arte, pero se puede encontrar un acceso directo a la maestría aquí.
  • requirements.txt: Este archivo define fuera de las dependencias de Python y sus versiones para su aplicación.
  • setup.py: Este archivo también puede ser usado para definir las dependencias, pero realmente brilla para otros trabajos que hay que hacer durante la instalación. Puede leer más sobre ambos setup.py y requirements.txt en nuestra guía de Pipenv.
  • tests.py: Este script alberga sus pruebas, si tiene alguno. Usted debe tener alguna.

.gitignore: Este es un archivo que le dice a Git qué tipos de archivos de ignorar, como el desorden IDE o archivos de configuración local. Nuestra Git tutorial tiene todos los detalles, y se pueden encontrar los archivos de muestra .gitignore para proyectos pitón aquí.

helloworld.py: Este es el script que se está distribuyendo. Por lo que el nombre del archivo principal de la escritura va, le recomiendo que vaya con el nombre de su proyecto (que es el mismo que el nombre del directorio de nivel superior).

LICENCIA: Este archivo de texto plano describe la licencia que está utilizando para un proyecto. Es siempre una buena idea tener uno si usted está distribuyendo código. El nombre de archivo es en todos los casquillos por convención.

Nota: necesita ayuda para elegir una licencia para su proyecto? Salida ChooseALicense.

README.md: Este es un archivo de rebajas (o reStructuredText) documentar el propósito y el uso de su aplicación. La elaboración de un buen README es un arte, pero se puede encontrar un acceso directo a la maestría aquí.

requirements.txt: Este archivo define fuera de las dependencias de Python y sus versiones para su aplicación.

setup.py: Este archivo también puede ser usado para definir las dependencias, pero realmente brilla para otros trabajos que hay que hacer durante la instalación. Puede leer más sobre ambos setup.py y requirements.txt en nuestra guía de Pipenv.

tests.py: Este script alberga sus pruebas, si tiene alguno. Usted debe tener alguna.

Pero ahora que su aplicación está creciendo, y que ha roto a cabo en varias piezas dentro del mismo paquete, en caso de que mantener todas las piezas en el directorio de nivel superior? Ahora que su aplicación es más compleja, es el momento de organizar las cosas de forma más limpia. Imaginemos que helloworld.py sigue siendo el script principal para ejecutar, pero se ha movido todos los métodos de ayuda a un nuevo archivo llamado helpers.py

solo paquete instalable

Let.

Vamos a empaquetar el holamundo archivos Python juntos, pero mantener todos los archivos varios, tales como el README, .gitignore, y así sucesivamente, en el directorio superior. La toma del

Let un vistazo a la estructura de actualización:

helloworld/

├── helloworld/
│ ├── __init__.py
│ ├── helloworld.py
│ └── helpers.py

├── tests/
│ ├── helloworld_tests.py
│ └── helpers_tests.py

├── .gitignore
├── LICENSE
├── README.md
├── requirements.txt
└── setup.py

La única diferencia aquí es que el código de aplicación ahora se mantenía a todos en el holamundo subdirectorio de este directorio es el nombre de su paquete y que hemos añadido un archivo llamado __init__ .py. Vamos a introducir estos nuevos archivos:

  • holamundo / __ init__.py: Este archivo tiene muchas funciones, pero para nuestros propósitos que le dice al intérprete de Python que este directorio es un directorio de paquetes. Puede configurar este archivo __init__.py de una manera que le permite importar las clases y los métodos del paquete en su conjunto, en lugar de conocer la estructura del módulo interna y la importación de helloworld.helloworld o helloworld.helpers. Nota: Para una discusión más profunda sobre los paquetes y __init__.py internos, nuestros módulos de Python y paquetes panorama, se ha cubierto.
  • holamundo / helpers.py: Como se mencionó anteriormente, nos hemos movido gran parte de la lógica de negocio de helloworld.py a este archivo. Gracias a __init__.py, módulos externos podrán acceder a estos ayudantes simplemente mediante la importación del paquete holamundo. pruebas
  • / nos hemos movido nuestras pruebas en su propio directorio, un patrón que seguirá viendo como nuestras estructuras programa de aumento de la complejidad. También hemos dividido nuestras pruebas en módulos separados, lo que refleja la estructura de nuestro paquete.

holamundo / __ init__.py: Este archivo tiene muchas funciones, pero para nuestros propósitos que le dice al intérprete de Python que este directorio es un directorio de paquetes. Puede configurar este archivo __init__.py de una manera que le permite importar las clases y los métodos del paquete en su conjunto, en lugar de conocer la estructura del módulo interna y la importación de helloworld.helloworld o helloworld.helpers.

Nota: Para una discusión más profunda sobre los paquetes y __init__.py internos, nuestros módulos de Python y paquetes panorama, se ha cubierto.

holamundo / helpers.py: Como se mencionó anteriormente, nos hemos movido gran parte de la lógica de negocio de helloworld.py a este archivo. Gracias a __init__.py, módulos externos podrán acceder a estos ayudantes simplemente mediante la importación del paquete holamundo. pruebas

/ nos hemos movido nuestras pruebas en su propio directorio, un patrón que seguirá viendo como nuestras estructuras programa de aumento de la complejidad. También hemos dividido nuestras pruebas en módulos separados, lo que refleja la estructura de nuestro paquete.

Este diseño es una versión simplificada de la estructura de la aplicación samplemod de Kenneth Reitz. Es otro gran punto de partida para las aplicaciones de CLI, especialmente para los proyectos más expansivas.

Aplicación

con Interno Paquetes

En aplicaciones de mayor tamaño, que puede tener uno o más internos paquetes que están bien atados junto con un script principal corredor o que proporcionan una funcionalidad específica a una biblioteca más grande que está empaquetando. Vamos a ampliar las convenciones establecidas anteriormente para dar cabida a esto:

helloworld/

├── bin/

├── docs/
│ ├── hello.md
│ └── world.md

├── helloworld/
│ ├── __init__.py
│ ├── runner.py
│ ├── hello/
│ │ ├── __init__.py
│ │ ├── hello.py
│ │ └── helpers.py
│ │
│ └── world/
│ ├── __init__.py
│ ├── helpers.py
│ └── world.py

├── data/
│ ├── input.csv
│ └── output.xlsx

├── tests/
│ ├── hello
│ │ ├── helpers_tests.py
│ │ └── hello_tests.py
│ │
│ └── world/
│ ├── helpers_tests.py
│ └── world_tests.py

├── .gitignore
├── LICENSE
└── README.md

hay un poco más de digerir aquí, pero siempre y cuando se recuerda que se desprende del diseño anterior, tendrá un tiempo más fácil siguiendo a lo largo. Voy a pasar por las adiciones y modificaciones con el fin, sus usos, y las razones por las que podría querer ellos.

    bin

  • /: Este directorio contiene los archivos ejecutables. He adaptado este clásico de la estructura posterior de Jean-Paul Calderone, y sus prescripciones para el uso de un directorio bin / siguen siendo importantes. El punto más importante a recordar es que el ejecutable no debe tener una gran cantidad de código, sólo una importación y una llamada a una función principal en el script corredor. Si está utilizando Python puro o no tiene ningún archivo ejecutable, puede dejar de lado este directorio.
  • / docs: Con una aplicación más avanzada, tendrá que mantener una buena documentación de todas sus partes. Me gusta poner toda la documentación para los módulos internos aquí, que es por eso que ver documentos separados para los paquetes de hola y mundiales. Si utiliza cadenas de documentación en sus módulos internos (y debe!), La documentación de todo el módulo debe al menos dar una visión integral del propósito y la función del módulo.
  • holamundo /: Esto es similar a holamundo / de la estructura anterior, pero ahora hay subdirectorios. A medida que agrega más complejidad, tendrá que utilizar una táctica de “divide y vencerás” y dividir a cabo las partes de su lógica de la aplicación en partes más manejables. Recuerde que el nombre del directorio se refiere al nombre del paquete global, por lo que los nombres de los subdirectorios (hola / y el mundo /) debe reflejar sus nombres de paquetes. datos
  • /: Tener este directorio es útil para la prueba. Es una ubicación central para todos los archivos que la aplicación va a ingerir o de un producto. En función de cómo implementar la aplicación, puede mantener las entradas y salidas “a nivel de producción” apuntaron a este directorio, o sólo lo uso para las pruebas internas. pruebas
  • /: Aquí, puede poner todas sus pruebas pruebas unitarias, pruebas de ejecución, pruebas de integración, y así sucesivamente. Siéntase libre para estructurar este directorio de la manera más conveniente para sus estrategias de ensayo, las estrategias de importación, y mucho más. Para un repaso de probar aplicaciones de línea de comandos con Python, echa un vistazo a mi artículo 4 Técnicas para la prueba de Python de línea de comandos (CLI) Aplicaciones.

bin

/: Este directorio contiene los archivos ejecutables. He adaptado este clásico de la estructura posterior de Jean-Paul Calderone, y sus prescripciones para el uso de un directorio bin / siguen siendo importantes. El punto más importante a recordar es que el ejecutable no debe tener una gran cantidad de código, sólo una importación y una llamada a una función principal en el script corredor. Si está utilizando Python puro o no tiene ningún archivo ejecutable, puede dejar de lado este directorio.

/ docs: Con una aplicación más avanzada, tendrá que mantener una buena documentación de todas sus partes. Me gusta poner toda la documentación para los módulos internos aquí, que es por eso que ver documentos separados para los paquetes de hola y mundiales. Si utiliza cadenas de documentación en sus módulos internos (y debe!), La documentación de todo el módulo debe al menos dar una visión integral del propósito y la función del módulo.

holamundo /: Esto es similar a holamundo / de la estructura anterior, pero ahora hay subdirectorios. A medida que agrega más complejidad, tendrá que utilizar una táctica de “divide y vencerás” y dividir a cabo las partes de su lógica de la aplicación en partes más manejables. Recuerde que el nombre del directorio se refiere al nombre del paquete global, por lo que los nombres de los subdirectorios (hola / y el mundo /) debe reflejar sus nombres de paquetes. datos

/: Tener este directorio es útil para la prueba. Es una ubicación central para todos los archivos que la aplicación va a ingerir o de un producto. En función de cómo implementar la aplicación, puede mantener las entradas y salidas “a nivel de producción” apuntaron a este directorio, o sólo lo uso para las pruebas internas. pruebas

/: Aquí, puede poner todas sus pruebas pruebas unitarias, pruebas de ejecución, pruebas de integración, y así sucesivamente. Siéntase libre para estructurar este directorio de la manera más conveniente para sus estrategias de ensayo, las estrategias de importación, y mucho más. Para un repaso de probar aplicaciones de línea de comandos con Python, echa un vistazo a mi artículo 4 Técnicas para la prueba de Python de línea de comandos (CLI) Aplicaciones.

Los archivos de alto nivel siguen siendo prácticamente los mismos que en la disposición anterior. Estos tres diseños deben cubrir la mayoría de los casos de uso de las aplicaciones de línea de comandos y aplicaciones GUI, incluso con la advertencia de que puede que tenga que jugar con algunas cosas en función del marco de interfaz gráfica de usuario que utilice.

Nota: Tenga en cuenta que estos son sólo diseños. Si un directorio o archivo no tiene sentido para su caso de uso específico (como pruebas / Si aún no está distribuyendo pruebas con su código), no dude en dejarlo fuera. Pero trate de no dejar de lado docs /. Es siempre una buena idea para documentar su trabajo.

de aplicaciones web Presentaciones

Otro caso de uso principal de Python es aplicaciones web. Django y Frasco son, posiblemente, la mayor cantidad de frameworks web populares para Python y por suerte son un poco más obstinado cuando se trata de diseño de la aplicación.

Con el fin de asegurarse de que este artículo es una referencia completa de diseño, de pleno derecho, quería resaltar la estructura común a estos marcos. Ir

Django

Vamos por orden alfabético y se inicia con Django. Una de las buenas cosas de Django es que se va a crear un esqueleto proyecto para usted después de ejecutar el proyecto startproject django-admin, donde el proyecto es el nombre del proyecto. Esto creará un directorio en el directorio de trabajo actual llamado proyecto con la siguiente estructura interna:

project/

├── project/
│ ├── __init__.py
│ ├── settings.py
│ ├── urls.py
│ └── wsgi.py

└── manage.py

Esto parece un poco vacío, no es cierto? ¿De dónde viene todo el camino lógica? ¿Las vistas? Ni siquiera hay ninguna prueba!

En Django, este es un proyecto que une el otro concepto de Django, aplicaciones. Las aplicaciones son donde la lógica, modelos, puntos de vista, y así sucesivamente todo en vivo, y al hacerlo, lo hacen algunas tareas, tales como el mantenimiento de un blog. aplicaciones

Django se pueden importar en proyectos y utilizados a través de proyectos, y se estructuran como paquetes especializados Python. Al igual que los proyectos

, Django hace que la generación de diseños de aplicaciones Django realmente fácil. Después de configurar su proyecto, todo lo que tiene que hacer es navegar a la ubicación de manage.py y ejecutar aplicaciones python manage.py startapp, donde aplicación es el nombre de su aplicación.

Esto resultará en un directorio llamado aplicación con la siguiente distribución:

app/

├── migrations/
│ └── __init__.py

├── __init__.py
├── admin.py
├── apps.py
├── models.py
├── tests.py
└── views.py

Esto se puede importar directamente en su proyecto. Los detalles de lo que hacen estos archivos, cómo aprovechar ellos para su proyecto, y así sucesivamente están fuera del alcance de esta referencia, pero se puede obtener toda esa información y más en nuestro tutorial de Django y también en los documentos oficiales de Django.

Esta estructura de archivos y carpetas es muy barebones y los requisitos básicos para Django. Para cualquier proyecto de Django de código abierto, puede (y debe) adaptar las estructuras de los diseños de aplicaciones de línea de comandos. Me suelen terminar con algo como esto en el proyecto / directorio externo:

project/

├── app/
│ ├── __init__.py
│ ├── admin.py
│ ├── apps.py
│ │
│ ├── migrations/
│ │ └── __init__.py
│ │
│ ├── models.py
│ ├── tests.py
│ └── views.py

├── docs/

├── project/
│ ├── __init__.py
│ ├── settings.py
│ ├── urls.py
│ └── wsgi.py

├── static/
│ └── style.css

├── templates/
│ └── base.html

├── .gitignore
├── manage.py
├── LICENSE
└── README.md

Para una discusión más profunda sobre los diseños más avanzados de aplicaciones Django, este hilo de desbordamiento de pila tiene cubierto. La documentación del proyecto django-proyecto-esqueleto explica algunos de los directorios que encontrará en el hilo de desbordamiento de pila. Una inmersión completa en Django se puede encontrar en las páginas de dos bolas de Django, que le enseñará todas las últimas mejores prácticas para el desarrollo de Django.

Para más tutoriales de Django, visita nuestra sección de Django en el Real Python.

Frasco

frasco es una web “microframework.” Python Uno de los principales puntos de venta es que es muy rápido de instalar con un mínimo de gastos. La documentación frasco tiene un ejemplo de aplicación web que está debajo de 10 líneas de código y en una única secuencia de comandos. Por supuesto, en la práctica, es muy poco probable que usted estará escribiendo una aplicación web esta pequeña.

Por suerte, las redadas de documentación frasco en que nos salve con un diseño sugerido para su proyecto tutorial (una aplicación web de blogs llamado Flaskr), y examinaremos que aquí desde dentro del directorio principal del proyecto:

flaskr/

├── flaskr/
│ ├── ___init__.py
│ ├── db.py
│ ├── schema.sql
│ ├── auth.py
│ ├── blog.py
│ ├── templates/
│ │ ├── base.html
│ │ ├── auth/
│ │ │ ├── login.html
│ │ │ └── register.html
│ │ │
│ │ └── blog/
│ │ ├── create.html
│ │ ├── index.html
│ │ └── update.html
│ │
│ └── static/
│ └── style.css

├── tests/
│ ├── conftest.py
│ ├── data.sql
│ ├── test_factory.py
│ ├── test_db.py
│ ├── test_auth.py
│ └── test_blog.py

├── venv/

├── .gitignore
├── setup.py
└── MANIFEST.in

A partir de estos contenidos, se se puede ver que una aplicación Frasco, como la mayoría de aplicaciones Python, está construido alrededor de los paquetes de Python.

Nota: no verlo? Un consejo rápido para la detección de paquetes es mediante la búsqueda de un archivo __init__.py. Esta se encuentra en el directorio de más alto nivel para ese paquete en particular. En la disposición anterior, flaskr es un paquete que contiene los módulos db, autenticación, y blogs.

En este diseño, todo reside en el paquete flaskr a excepción de las pruebas, un directorio para sus entornos virtuales, y sus archivos habituales de nivel superior. Al igual que en otros diseños, las pruebas serán más o menos coincidir con los módulos individuales que residen dentro del paquete flaskr. Sus plantillas también residen en el paquete principal proyecto, lo que no sucedería con los diseños de Django.

Esté seguro también de visitar nuestra página Frasco plancha de caldera de Github para una vista de una aplicación más Frasco plasmen plenamente de salida y ver el texto modelo en acción aquí.

Para más información sobre el frasco, echa un vistazo a todos nuestros tutoriales Frasco aquí. Conclusiones

y Avisos de

Ahora se han visto ejemplos de diseños para un número de diferentes tipos de aplicaciones: Una sola vez Python scripts, paquetes instalables individuales, las aplicaciones más grandes con paquetes internos, aplicaciones web Django y aplicaciones web frasco.

Coming lejos de esta guía, usted tendrá las herramientas para prevenir con éxito el bloqueo del codificador a cabo mediante la construcción de la estructura de su aplicación, de modo que usted no está mirando a un lienzo en blanco tratando de averiguar por dónde empezar.

Debido a que Python es en gran parte no-dogmático cuando se trata de diseños de aplicaciones, puede personalizar estos diseños ejemplo al contenido de su corazón para un mejor ajuste a su caso de uso.

quiero que no sólo permite tener una referencia de diseño de la aplicación, sino también salir con el entendimiento de que estos ejemplos no son ni reglas duras y rápidas ni la única manera de estructurar su aplicación. Con el tiempo y con la práctica, que va a desarrollar la capacidad de crear y personalizar sus propios diseños de útiles aplicaciones Python.

me he perdido un caso de uso? ¿Tiene otra filosofía estructura de la aplicación? Hizo este artículo ayuda a prevenir el bloqueo del codificador? ¡Házmelo saber en los comentarios!

Deja un comentario

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *