psf / black · 入門

metadata 也記錄了具體的事實：主要語言是 Python，追蹤到的語言位元組幾乎全是 Python（約 5.46 百萬中的 5,440,093 個），Vim Script、Jupyter Notebook 和 Dockerfile 只占一小部分。授權記錄為 MIT，來源標示為 GitHub API 和 repository 裡的一個檔案。最新 release 是 26.5.1，於 2026-05-18 發布，這個 repository 在 2026-09-14 有 41,844 個 star。分析器的成熟度訊號列出 482 個被分析的檔案、326 個類測試檔案、7 個清單檔、9,339 條靜態關係邊和 176 條有界執行路徑。

如果你的問題是要安裝什麼，這份分析資料回答不了。它沒有任何依賴記錄；依賴記錄只來自分析器 v0.10 解析的 requirements 形式清單檔，而這個 repository 一個也沒有被解析。pyproject.toml 的依賴表不會被解析，所以宣告的依賴和版本限制都沒有列出來，即使 pyproject.toml 確實存在，也被歸為專案層級的重要檔案。成熟度訊號在檔案清單中算到 7 個清單檔，但沒有任何解析過的清單記錄，所以它們的內容沒有反映在這裡。因為安裝、執行與建置的推論並不完整，安裝指令也沒有驗證，這份指南也無法指名要安裝哪些套件或版本。

列出了十八筆進入點記錄：其中十七筆的摘錄顯示 Python __main__ 執行守衛（這些記錄的摘錄欄位，就是看得到這種守衛長什麼樣子的地方），另有一個依檔名啟發式規則找到的候選 action/main.py（分析把它標為 filename-heuristic candidate，依據的是檔名，而不是守衛摘錄）。在 src 目錄樹裡，套件的 init 檔 src/black/__init__.py 和 src/blackd/__init__.py 各自用守衛包住一個 patched_main() 呼叫。在 src/blib2to3/pgen2 底下，driver.py 以 sys.exit(int(not main())) 結尾，literals.py 和 tokenize.py 則帶有較小、偏向測試用途的守衛。在 scripts/ 裡，diff_shades_gha_helper.py、generate_schema.py 和 make_width_table.py 都用守衛包住一個 main() 呼叫；release.py 以 sys.exit(main()) 結尾，release_tests.py 呼叫 unittest.main()。scripts/fuzz.py 的守衛會執行 test_idempotent_any_syntactically_valid_python()，並在有 Atheris fuzzing 函式庫時進行 coverage-guided fuzzing。帶有守衛的記錄還包括 tests/test_tokenize.py（它的守衛讀取 stdin、做 tokenize，然後印出一個 assert_tokenizes 斷言），以及 tests/data/cases/ 底下的路徑。重建結果統計出 18 個進入點和 176 條有界執行路徑；為 action/main.py 列出的五條有界路徑就是執行路徑記錄，它們的步驟顯示都馬上停在 Path 和 os.getenv 這類未解析的外部邊界。分析的限制清單記錄了最後這個詞背後的一般原則：好幾種動態行為，這次靜態分析都沒有解析。超出這些守衛與有界路徑記錄的執行時行為，包括這個套件安裝後怎麼以指令的形式被呼叫，這次分析都無法確定。

README.md、pyproject.toml 和 LICENSE 被歸為專案層級的重要檔案。分析器關於學習路徑的陳述建議：先從清單檔和重要符號開始，再追蹤有界執行路徑，並在改程式之前檢查未解析的邊界；但這份分析資料看不到這個建議所預設的清單檔內容，所以光靠這份資料無法照著做。它關於修改的陳述說，要從偵測到的進入點 action/main.py 開始分析修改，再手動確認下游的影響。依被分析的檔案數，頂層目錄樹是 tests（326）、docs（48）、src（48）、.github（22）、scripts（9）、profiling（7），根目錄有 19 個檔案，action、plugin 和 autoload 則各有一個檔案。src 裡有帶守衛的套件 init 檔 src/black/__init__.py 和 src/blackd/__init__.py，以及進入點記錄中提到的 src/blib2to3/pgen2 模組。326 個類測試檔案大約占全部 482 個被分析檔案的三分之二；光看數字無法知道這些檔案的內容。docs/ 有 48 個檔案，進入點摘錄顯示有兩支腳本會開啟 CHANGES.md，以及 docs/usage_and_configuration/the_basics.md 和 docs/integrations/source_version_control.md 這類文件檔。

這是靜態分析，分析資料本身也記錄了它的邊界。安裝、建置和執行指令都沒有驗證，安裝／執行／建置的推論也不完整，這就是為什麼這份指南沒有任何指令。只有 requirements 形式的清單檔會產生依賴記錄，pyproject.toml 的依賴表不會被解析，所以這裡的依賴樣貌是空的。來自 README 的陳述是逐行擷取的，可能抓到程式碼行而不是說明文字，所以任何 README 的陳述最多只算 author_claimed。反射、執行期依賴注入、動態 import、monkey-patching、產生的程式碼、框架在執行期的接線和動態分派都沒有解析。在 9,339 條靜態關係邊中，重建結果只算到 813 條已解析的呼叫關係，所以大多數的邊仍是未解析或外部的。分析資料也自相矛盾：有一條教學陳述說沒有可用的有界靜態執行路徑，但 action/main.py 列出了五條有界路徑，總數更有 176 條；而且摘要文字把 scripts/check_pre_commit_rev_in_example.py 稱為主要起點，教學陳述卻指向 action/main.py。這個專案平常應該怎麼被呼叫使用，無法確定。

repository metadata 把這個專案描述為「The uncompromising Python code formatter」；請把它當作作者的自我描述，不是分析的發現。首頁欄位指向 Read the Docs 上 Black 文件網站的 stable 頻道。附加的 topics 包括 formatter、codeformatter、python、pre-commit-hook、autopep8、yapf、gofmt、hacktoberfest 和 code。