black
24.10.0
"N'importe quelle couleur que vous aimez."
Black est le formateur de code Python sans compromis. En l'utilisant, vous acceptez de céder le contrôle sur les détails du formatage manuel. En retour, Black vous offre rapidité, déterminisme et liberté face au pycodestyle qui vous harcèle concernant le formatage. Vous économiserez du temps et de l’énergie mentale pour des questions plus importantes.
Le code noirci est identique quel que soit le projet que vous lisez. Le formatage devient transparent après un certain temps et vous pouvez vous concentrer sur le contenu.
Le noir accélère la révision du code en produisant les plus petites différences possibles.
Essayez-le maintenant en utilisant le Black Playground. Regardez la conférence PyCon 2019 pour en savoir plus.
Lisez la documentation sur ReadTheDocs !
Black peut être installé en exécutant pip install black . Il nécessite Python 3.9+ pour s'exécuter. Si vous souhaitez formater les notebooks Jupyter, installez-les avec pip install "black[jupyter]" .
Si vous ne pouvez pas attendre les dernières nouveautés et que vous souhaitez installer depuis GitHub, utilisez :
pip install git+https://github.com/psf/black
Pour commencer immédiatement avec des valeurs par défaut raisonnables :
black {source_file_or_directory}Vous pouvez exécuter Black en tant que package si l'exécuter en tant que script ne fonctionne pas :
python -m black {source_file_or_directory}De plus amples informations peuvent être trouvées dans nos documents :
Le noir est déjà utilisé avec succès dans de nombreux projets, petits et grands. Black dispose d'une suite de tests complète, avec des tests parallèles efficaces, ainsi que de notre propre programme de formatage automatique et d'intégration continue parallèle. Maintenant que nous sommes devenus stables, il ne faut pas s'attendre à de grands changements de formatage à l'avenir. Les changements stylistiques seront principalement des réponses aux rapports de bogues et à la prise en charge de la nouvelle syntaxe Python. Pour plus d’informations, veuillez vous référer à The Black Code Style.
De plus, par mesure de sécurité qui ralentit le traitement, Black vérifiera que le code reformaté produit toujours un AST valide qui est effectivement équivalent à l'original (voir la section Pragmatisme pour plus de détails). Si vous vous sentez en confiance, utilisez --fast .
Black est un formateur avisé conforme à la norme PEP 8. Black reformate des fichiers entiers sur place. Les options de configuration de style sont délibérément limitées et rarement ajoutées. Il ne prend pas en compte le formatage précédent (voir Pragmatisme pour les exceptions).
Notre documentation couvre le style de code Black actuel, mais les modifications prévues y sont également documentées. Ils valent tous les deux le détour :
Les modifications apportées au style du code noir sont liées par la politique de stabilité :
Veuillez vous référer à ce document avant de soumettre un problème. Ce qui ressemble à un bug pourrait être un comportement intentionnel.
Les premières versions de Black étaient absolutistes à certains égards. Ils s'inspirent de son auteur initial. C'était bien à l'époque car cela simplifiait la mise en œuvre et de toute façon, il n'y avait pas beaucoup d'utilisateurs. Peu de cas extrêmes ont été signalés. En tant qu'outil mature, les Noirs font quelques exceptions aux règles qu'ils appliquent autrement.
Veuillez vous référer à ce document avant de soumettre un problème, tout comme pour le document ci-dessus. Ce qui ressemble à un bug pourrait être un comportement intentionnel.
Black est capable de lire les valeurs par défaut spécifiques au projet pour ses options de ligne de commande à partir d'un fichier pyproject.toml . Ceci est particulièrement utile pour spécifier des modèles --include et --exclude / --force-exclude / --extend-exclude personnalisés pour votre projet.
Vous pouvez trouver plus de détails dans notre documentation :
Et si vous recherchez une documentation de configuration plus générale :
Conseil de pro : si vous vous demandez « Dois-je configurer quelque chose ? » la réponse est "Non". Le noir est synonyme de valeurs par défaut raisonnables. L'application de ces valeurs par défaut rendra votre code conforme à de nombreux autres projets au format Black .
Les projets open source notables suivants font confiance à Black pour appliquer un style de code cohérent : pytest, tox, Pyramid, Django, Django Channels, Hypothesis, attrs, SQLAlchemy, Poetry, applications PyPA (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow. , Twisted, LocalStack, chaque intégration d'agent Datadog, Home Assistant, Zulip, Kedro, OpenOA, FLORIS, ORBIT, WOMBAT et bien d'autres plus.
Les organisations suivantes utilisent Black : Facebook, Dropbox, KeepTruckin, Lyft, Mozilla, Quora, Duolingo, QuantumBlack, Tesla, Archer Aviation.
Est-ce qu'il nous manque quelqu'un ? Faites-le-nous savoir.
Mike Bayer , auteur de SQLAlchemy :
Je ne peux penser à aucun outil dans toute ma carrière de programmeur qui m'a permis d'augmenter davantage ma productivité grâce à son introduction. Je peux maintenant effectuer des refactorisations dans environ 1 % des frappes au clavier, ce qui m'aurait été nécessaire auparavant lorsque nous n'avions aucun moyen pour le code de se formater.
Dusty Phillips , écrivain :
Le noir est opiniâtre, vous n'êtes donc pas obligé de l'être.
Hynek Schlawack , créateur de attrs , développeur principal de Twisted et CPython :
Un formateur automatique qui ne craint pas, c'est tout ce que je veux pour Noël !
Carl Meyer , développeur principal de Django :
Au moins, le nom est bon.
Kenneth Reitz , créateur de requests et pipenv :
Cela améliore considérablement le formatage de notre code. Merci beaucoup !
Utilisez le badge dans le README.md de votre projet :
[ ![ Code style: black ] ( https://img.shields.io/badge/code%20style-black-000000.svg )] ( https://github.com/psf/black )Utilisation du badge dans README.rst :
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
Cela ressemble à ceci :
MIT
Accueillir! Heureux de vous voir prêt à améliorer le projet. Vous pouvez commencer en lisant ceci :
Vous pouvez également consulter le reste des documents contributeurs ou discuter avec les développeurs :
Le journal est devenu assez long. Il a été déplacé vers son propre fichier.
Voir MODIFICATIONS.
La liste des auteurs est assez longue de nos jours, elle réside donc dans son propre fichier.
Voir AUTEURS.md
Toute personne participant au projet Black , et en particulier au suivi des problèmes, aux demandes d'extraction et à l'activité sur les réseaux sociaux, est censée traiter les autres avec respect et, plus généralement, suivre les directives énoncées dans le code de conduite de la communauté Python.
En parallèle, l’humour est encouragé. En fait, une connaissance de base du Flying Circus de Monty Python est attendue. Nous ne sommes pas des sauvages.
Et si vous avez vraiment besoin de gifler quelqu'un, faites-le avec un poisson en dansant.
