$ show psf/black
Black is the uncompromising Python code formatter. It is a CLI tool that automatically reformats Python source code to a consistent style, with a focus on determinism and minimal configuration. The repository contains the core formatting engine, a HTTP server (blackd) for on-demand formatting, a GitHub Action for CI integration, and a Vim plugin. The architecture is modular: parsing uses a forked lib2to3 parser (blib2to3) for lenient syntax handling, then a visitor-based line generator produces formatted lines, with specialized transformers for strings, brackets, and comments. It supports Jupyter notebooks, line-range formatting, caching, and parallel execution. The codebase is exceptionally well-tested with hundreds of edge-case test files and a comprehensive test suite. It demonstrates high craftsmanship in areas like tree manipulation, concurrency patterns, and string normalization.
The LLM identified 5 files worth highlighting for reuse:
Implements a Rust-inspired `Ok`/`Err` generic result type. Provides a clean, type-safe way to handle success/failure without exceptions. The `Result` base class and its `Ok` and `Err` subclasses support pattern matching via `isinstance` checks and a `ok()` method. This is a reusable pattern for any Python project that wants to avoid exception-heavy control flow.
Implements a feature-aware cache for formatted files. Uses SHA-256 hashing of file contents combined with a `CacheKey` that includes the formatting mode (line length, target version, preview flags). The cache is stored as a pickle file and supports filtering by changed files. The `filtered_cached` method efficiently returns only files that need reformatting. This pattern is reusable for any tool that needs to avoid redundant processing based on configuration changes.
Provides `reformat_many` for parallel formatting of multiple files. Uses `ProcessPoolExecutor` for CPU-bound work with a fallback to `ThreadPoolExecutor` on platforms where processes are unavailable (Windows with limited workers, frozen builds, AWS Lambda). Integrates with asyncio for signal handling and cancellation. The `maybe_install_uvloop` function optionally uses uvloop for better performance. This is a robust pattern for parallelizing I/O or CPU tasks with graceful degradation.
Handles normalization of string prefixes, quotes, and Unicode escape sequences. Functions like `normalize_string_prefix`, `normalize_string_quotes`, and `normalize_unicode_escape_sequences` are self-contained and can be reused in any Python tool that needs to canonicalize string literals. The module also includes logic for detecting East Asian width characters and handling f-string expressions. The code is well-documented and handles many edge cases (raw strings, byte strings, triple-quoted strings).
Implements a configurable CORS middleware for aiohttp servers. Allows specifying allowed origins, headers, and methods. Handles preflight requests and sets appropriate CORS headers. The middleware is generic and can be extracted for any aiohttp application that needs CORS support. It is concise (under 50 lines) and follows best practices for CORS implementation.