black
24.10.0
"El color que quieras".
El negro es el formateador de código Python sin concesiones. Al usarlo, usted acepta ceder el control sobre los detalles del formateo manual. A cambio, Black le brinda velocidad, determinismo y libertad de las molestias pycodestyle sobre el formato. Ahorrarás tiempo y energía mental para asuntos más importantes.
El código ennegrecido tiene el mismo aspecto independientemente del proyecto que estés leyendo. El formato se vuelve transparente después de un tiempo y usted puede concentrarse en el contenido.
Black agiliza la revisión del código al producir las diferencias más pequeñas posibles.
Pruébelo ahora usando Black Playground. Mire la charla de PyCon 2019 para obtener más información.
¡Lea la documentación en ReadTheDocs!
Black se puede instalar ejecutando pip install black . Requiere Python 3.9+ para ejecutarse. Si desea formatear Jupyter Notebooks, instálelo con pip install "black[jupyter]" .
Si no puede esperar a las últimas novedades y desea instalar desde GitHub, utilice:
pip install git+https://github.com/psf/black
Para comenzar de inmediato con valores predeterminados sensatos:
black {source_file_or_directory}Puede ejecutar Black como paquete si ejecutarlo como script no funciona:
python -m black {source_file_or_directory}Puede encontrar más información en nuestros documentos:
El negro ya se utiliza con éxito en muchos proyectos, pequeños y grandes. Black tiene un conjunto de pruebas completo, con pruebas paralelas eficientes y nuestro propio formato automático y ejecutor de integración continua paralelo. Ahora que nos hemos estabilizado, no deberías esperar grandes cambios de formato en el futuro. Los cambios de estilo serán principalmente respuestas a informes de errores y soporte para la nueva sintaxis de Python. Para obtener más información, consulte The Black Code Style.
Además, como medida de seguridad que ralentiza el procesamiento, Black verificará que el código reformateado aún produzca un AST válido que sea efectivamente equivalente al original (consulte la sección Pragmatismo para obtener más detalles). Si se siente seguro, utilice --fast .
Black es un formateador testarudo compatible con PEP 8. Black reformatea archivos completos en su lugar. Las opciones de configuración de estilo son deliberadamente limitadas y rara vez se agregan. No tiene en cuenta el formato anterior (consulte Pragmatismo para conocer las excepciones).
Nuestra documentación cubre el estilo actual del código Black , pero también se documentan los cambios planificados. Vale la pena echarles un vistazo a ambos:
Los cambios en el estilo del código Black están sujetos a la Política de estabilidad:
Consulte este documento antes de enviar un problema. Lo que parece un error podría ser un comportamiento previsto.
Las primeras versiones de Black solían ser absolutistas en algunos aspectos. Se inspiraron en su autor inicial. Esto estuvo bien en ese momento, ya que simplificó la implementación y de todos modos no había muchos usuarios. No se informaron muchos casos extremos. Como herramienta madura, las negras hacen algunas excepciones a las reglas que por lo demás aplican.
Consulte este documento antes de enviar un problema, como ocurre con el documento anterior. Lo que parece un error podría ser un comportamiento previsto.
Black puede leer valores predeterminados específicos del proyecto para sus opciones de línea de comando desde un archivo pyproject.toml . Esto es especialmente útil para especificar patrones personalizados --include y --exclude / --force-exclude / --extend-exclude para su proyecto.
Puede encontrar más detalles en nuestra documentación:
Y si busca documentación de configuración más general:
Consejo profesional : si te preguntas "¿Necesito configurar algo?" la respuesta es "No". El negro tiene que ver con valores predeterminados sensatos. La aplicación de esos valores predeterminados hará que su código cumpla con muchos otros proyectos con formato Black .
Los siguientes proyectos notables de código abierto confían en Black para aplicar un estilo de código consistente: pytest, tox, Pyramid, Django, Django Channels, Hypothesis, attrs, SQLAlchemy, Poetry, aplicaciones PyPA (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow , Twisted, LocalStack, cada integración del agente Datadog, Home Assistant, Zulip, Kedro, OpenOA, FLORIS, ORBIT, WOMBAT, y muchos más.
Las siguientes organizaciones utilizan Black : Facebook, Dropbox, KeepTruckin, Lyft, Mozilla, Quora, Duolingo, QuantumBlack, Tesla, Archer Aviation.
¿Nos falta alguien? Háganoslo saber.
Mike Bayer , autor de SQLAlchemy :
No puedo pensar en ninguna herramienta en toda mi carrera de programación que me haya brindado un mayor aumento de productividad con su introducción. Ahora puedo hacer refactorizaciones en aproximadamente el 1% de las pulsaciones de teclas que me habrían requerido anteriormente cuando no teníamos forma de que el código se formateara.
Dusty Phillips , escritor:
El negro es obstinado, así que tú no tienes por qué serlo.
Hynek Schlawack , creador de attrs , desarrollador principal de Twisted y CPython:
¡Un formateador automático que no apesta es todo lo que quiero para Navidad!
Carl Meyer , desarrollador principal de Django:
Al menos el nombre es bueno.
Kenneth Reitz , creador de requests y pipenv :
Esto mejora enormemente el formato de nuestro código. ¡Muchas gracias!
Utilice la insignia en el archivo README.md de su proyecto:
[ ![ Code style: black ] ( https://img.shields.io/badge/code%20style-black-000000.svg )] ( https://github.com/psf/black )Usando la insignia en README.rst:
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
Se parece a esto:
MIT
¡Bienvenido! Me alegra verte dispuesto a mejorar el proyecto. Puedes empezar leyendo esto:
También puedes echar un vistazo al resto de los documentos contribuidos o hablar con los desarrolladores:
El registro se ha vuelto bastante largo. Se trasladó a su propio archivo.
Ver CAMBIOS.
La lista de autores es bastante larga hoy en día, por lo que vive en su propio archivo.
Ver AUTORES.md
Se espera que todos los que participan en el proyecto Black , y en particular en el rastreador de problemas, las solicitudes de extracción y la actividad en las redes sociales, traten a otras personas con respeto y, en general, sigan las pautas articuladas en el Código de conducta de la comunidad Python.
Al mismo tiempo, se fomenta el humor. De hecho, se espera una familiaridad básica con Flying Circus de Monty Python. No somos salvajes.
Y si realmente necesitas abofetear a alguien, hazlo con un pez mientras bailas.
