black
24.10.0
“สีอะไรก็ได้ที่คุณชอบ”
Black เป็นตัวจัดรูปแบบโค้ด Python ที่แน่วแน่ การใช้งานนี้แสดงว่าคุณตกลงที่จะยกการควบคุมเรื่องเล็กๆ น้อยๆ ในการจัดรูปแบบด้วยมือ ในทางกลับกัน Black จะให้ความเร็ว ระดับที่กำหนด และอิสระแก่คุณจาก pycodestyle ที่จู้จี้จุกจิกเกี่ยวกับการจัดรูปแบบ คุณจะประหยัดเวลาและพลังงานทางจิตสำหรับเรื่องที่สำคัญกว่า
โค้ดที่ดำคล้ำจะดูเหมือนเดิมไม่ว่าคุณกำลังอ่านโปรเจ็กต์ใดก็ตาม การจัดรูปแบบจะโปร่งใสหลังจากผ่านไประยะหนึ่ง และคุณสามารถมุ่งเน้นไปที่เนื้อหาแทนได้
สีดำ ทำให้การตรวจสอบโค้ดเร็วขึ้นโดยสร้างส่วนต่างที่เล็กที่สุดเท่าที่จะเป็นไปได้
ลองใช้ตอนนี้โดยใช้ Black Playground ดูการพูดคุยของ PyCon 2019 เพื่อเรียนรู้เพิ่มเติม
อ่านเอกสารประกอบใน ReadTheDocs!
สามารถติดตั้ง Black ได้โดยการรัน pip install black ต้องใช้ Python 3.9+ จึงจะทำงานได้ หากคุณต้องการฟอร์แมต Jupyter Notebooks ให้ติดตั้งด้วย pip install "black[jupyter]"
หากคุณแทบรอไม่ไหวที่จะพบกับ ความฮอต ล่าสุดและต้องการติดตั้งจาก GitHub ให้ใช้:
pip install git+https://github.com/psf/black
ในการเริ่มต้นทันทีด้วยค่าเริ่มต้นที่สมเหตุสมผล:
black {source_file_or_directory}คุณสามารถเรียกใช้ Black เป็นแพ็คเกจได้หากการเรียกใช้เป็นสคริปต์ไม่ทำงาน:
python -m black {source_file_or_directory}ข้อมูลเพิ่มเติมสามารถพบได้ในเอกสารของเรา:
สีดำ ถูกนำมาใช้อย่างประสบความสำเร็จในหลายโครงการทั้งขนาดเล็กและขนาดใหญ่ Black มีชุดการทดสอบที่ครอบคลุม พร้อมด้วยการทดสอบแบบขนานที่มีประสิทธิภาพ และการจัดรูปแบบอัตโนมัติและตัวรันการรวมต่อเนื่องแบบขนานของเราเอง ขณะนี้เรามีเสถียรภาพแล้ว คุณไม่ควรคาดหวังการเปลี่ยนแปลงการจัดรูปแบบขนาดใหญ่ในอนาคต การเปลี่ยนแปลงรูปแบบส่วนใหญ่จะเป็นการตอบสนองต่อรายงานข้อผิดพลาดและการรองรับไวยากรณ์ Python ใหม่ สำหรับข้อมูลเพิ่มเติม โปรดดูที่สไตล์รหัสสีดำ
นอกจากนี้ เพื่อเป็นมาตรการด้านความปลอดภัยซึ่งทำให้การประมวลผลช้าลง Black จะตรวจสอบว่าโค้ดที่ฟอร์แมตแล้วยังคงสร้าง AST ที่ถูกต้องซึ่งเทียบเท่ากับโค้ดต้นฉบับอย่างมีประสิทธิผล (ดูรายละเอียดในส่วนลัทธิปฏิบัตินิยม) หากคุณรู้สึกมั่นใจ ให้ใช้ --fast
สีดำ คือฟอร์แมตเตอร์ที่สอดคล้องกับมาตรฐาน PEP 8 สีดำ ฟอร์แมตไฟล์ทั้งหมดให้เข้าที่ ตัวเลือกการกำหนดค่าสไตล์มีเจตนาจำกัดและไม่ค่อยเพิ่ม ไม่คำนึงถึงการจัดรูปแบบก่อนหน้านี้ (ดูข้อยกเว้นในลัทธิปฏิบัตินิยม)
เอกสารประกอบของเราครอบคลุมถึงรูปแบบรหัส สีดำ ในปัจจุบัน แต่การเปลี่ยนแปลงที่วางแผนไว้ก็ได้รับการบันทึกไว้เช่นกัน พวกเขาทั้งคู่ควรค่าแก่การดู:
การเปลี่ยนแปลงรูปแบบโค้ด สีดำ จะมีผลผูกพันกับนโยบายความเสถียร:
โปรดดูเอกสารนี้ก่อนที่จะส่งปัญหา สิ่งที่ดูเหมือนเป็นจุดบกพร่องอาจเป็นพฤติกรรมที่ตั้งใจไว้
คนผิว ดำ เวอร์ชันแรก ๆ เคยเป็นสมบูรณาญาสิทธิราชย์ในบางประเด็น พวกเขายึดถือตามผู้เขียนคนแรก ซึ่งถือว่าใช้ได้ในขณะนั้นเนื่องจากทำให้การใช้งานง่ายขึ้นและมีผู้ใช้ไม่มากนัก มีการรายงานกรณี Edge ไม่มากนัก ในฐานะเครื่องมือสำหรับผู้ใหญ่ Black ได้สร้างข้อยกเว้นบางประการสำหรับกฎที่ถืออยู่
โปรดดูเอกสารนี้ก่อนที่จะส่งปัญหาเช่นเดียวกับเอกสารด้านบน สิ่งที่ดูเหมือนเป็นจุดบกพร่องอาจเป็นพฤติกรรมที่ตั้งใจไว้
Black สามารถอ่านค่าเริ่มต้นเฉพาะโครงการสำหรับตัวเลือกบรรทัดคำสั่งจากไฟล์ pyproject.toml สิ่งนี้มีประโยชน์อย่างยิ่งสำหรับการระบุรูปแบบ --include และ --exclude / --force-exclude / --extend-exclude แบบกำหนดเองสำหรับโครงการของคุณ
คุณสามารถค้นหารายละเอียดเพิ่มเติมได้ในเอกสารของเรา:
และหากคุณกำลังมองหาเอกสารการกำหนดค่าทั่วไปเพิ่มเติม:
เคล็ดลับจากมือโปร : หากคุณถามตัวเองว่า "ฉันต้องกำหนดค่าอะไรไหม" คำตอบคือ "ไม่" สีดำ เป็นเรื่องเกี่ยวกับค่าเริ่มต้นที่สมเหตุสมผล การใช้ค่าเริ่มต้นเหล่านั้นจะทำให้โค้ดของคุณสอดคล้องกับโปรเจ็กต์ที่มีรูปแบบ สีดำ อื่นๆ มากมาย
โปรเจ็กต์โอเพ่นซอร์สที่โดดเด่นต่อไปนี้ไว้วางใจ Black ในการบังคับใช้รูปแบบโค้ดที่สอดคล้องกัน: pytest, tox, Pyramid, Django, Django Channels, Hypothesis, attrs, SQLAlchemy, Poetry, แอปพลิเคชัน PyPA (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow , Twisted, LocalStack, การรวม Datadog Agent ทุกตัว, ผู้ช่วยที่บ้าน, Zulip, Kedro, OpenOA, FLORIS, วงโคจร วอมแบต และอื่นๆ อีกมากมาย
องค์กรต่อไปนี้ใช้ Black : Facebook, Dropbox, KeepTruckin, Lyft, Mozilla, Quora, Duolingo, QuantumBlack, Tesla, Archer Aviation
เราขาดใครไปหรือเปล่า? แจ้งให้เราทราบ
Mike Bayer ผู้เขียน SQLAlchemy :
ฉันไม่สามารถนึกถึงเครื่องมือใดเลยในอาชีพการเขียนโปรแกรมทั้งหมดของฉันที่ช่วยให้ฉันเพิ่มประสิทธิภาพการทำงานได้มากขึ้นจากการแนะนำ ตอนนี้ฉันสามารถทำการรีแฟคเตอร์ได้ประมาณ 1% ของการกดแป้นพิมพ์ที่เคยใช้ก่อนหน้านี้เมื่อเราไม่มีทางที่จะจัดรูปแบบโค้ดเอง
ดัสตี ฟิลลิปส์ , ผู้แต่ง:
คนดำ เป็นคนดื้อรั้น ดังนั้นคุณไม่จำเป็นต้องเป็นแบบนั้น
Hynek Schlawack ผู้สร้าง attrs ผู้พัฒนาหลักของ Twisted และ CPython:
ฟอร์แมตเตอร์อัตโนมัติที่ไม่ห่วยคือสิ่งเดียวที่ฉันต้องการสำหรับคริสต์มาส!
Carl Meyer ผู้พัฒนาหลักของ Django:
อย่างน้อยก็ชื่อก็ดี
Kenneth Reitz ผู้สร้าง requests และ pipenv :
สิ่งนี้ช่วยปรับปรุงการจัดรูปแบบของโค้ดของเราอย่างมาก ขอบคุณมาก!
ใช้ตราสัญลักษณ์ใน README.md ของโครงการของคุณ:
[ ![ Code style: black ] ( https://img.shields.io/badge/code%20style-black-000000.svg )] ( https://github.com/psf/black )การใช้ตราสัญลักษณ์ใน README.rst:
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
ดูเหมือนว่านี้:
เอ็มไอที
ยินดีต้อนรับ! ดีใจที่เห็นคุณเต็มใจทำให้โครงการดีขึ้น คุณสามารถเริ่มต้นด้วยการอ่านสิ่งนี้:
คุณยังสามารถดูเอกสารส่วนที่เหลือหรือพูดคุยกับนักพัฒนาได้:
บันทึกค่อนข้างยาว มันย้ายไปที่ไฟล์ของตัวเอง
ดูการเปลี่ยนแปลง
รายชื่อผู้แต่งในปัจจุบันค่อนข้างยาว ดังนั้นจึงอยู่ในไฟล์ของตัวเอง
ดู AUTHORS.md
ทุกคนที่เข้าร่วมในโครงการ Black และโดยเฉพาะอย่างยิ่งในตัวติดตามปัญหา คำขอดึง และกิจกรรมโซเชียลมีเดีย ได้รับการคาดหวังให้ปฏิบัติต่อผู้อื่นด้วยความเคารพ และโดยทั่วไปแล้วจะปฏิบัติตามแนวทางที่ระบุไว้ในหลักปฏิบัติของชุมชน Python
ในขณะเดียวกันก็ส่งเสริมให้มีอารมณ์ขัน อันที่จริงแล้ว คาดว่าจะมีความคุ้นเคยขั้นพื้นฐานกับ Flying Circus ของ Monty Python เราไม่ใช่คนป่าเถื่อน
และถ้าคุณต้องการตบใครสักคน จริงๆ ให้ตบปลาขณะเต้นรำ
