Black (formatter)

Black (formatter)
source
Name	Black
Developer	Łukasz Langa
Released	2018
Latest release	23.1.0
Programming language	Python (programming language)
License	MIT License
Repository	GitHub
Platform	Cross-platform

Black (formatter)

Black is an uncompromising code formatter for Python (programming language) that enforces a uniform style by reformating source files automatically. Designed to remove stylistic debates from projects, Black produces deterministic output so teams using tools like GitHub, GitLab, Bitbucket, or Phabricator can rely on consistent diffs during reviews. The project has influenced surrounding tooling in ecosystems such as Visual Studio Code, PyCharm, and continuous integration systems including Travis CI and CircleCI.

Overview

Black was created to provide a single, opinionated formatter for Python (programming language) codebases, emphasizing speed, determinism, and minimal configuration. The tool is distributed via PyPI as a package installable with pip and is hosted on GitHub where contributors coordinate using issues and pull requests. Black’s philosophy parallels other opinionated tools like Prettier in the JavaScript ecosystem and interoperates with linters such as Flake8 and Pylint by separating formatting concerns from static analysis.

Features

Black formats Python (programming language) code to a canonical style with stable line-length handling and AST-based rewrites. Key features include: - Deterministic formatting: identical inputs yield identical outputs, enabling reproducible results for Continuous integration workflows across GitHub Actions, Jenkins, and Azure DevOps. - Speed and scalability: suitable for large repositories such as projects developed by teams using NumPy, pandas, or Django. - Minimal configuration: a few flags and a small set of supported options reduce configuration drift among contributors using tools like pre-commit and editors such as Visual Studio Code or Sublime Text. - Safety modes: options to preview changes with diff output and to check formatting without modifying files, useful for automation with GitLab CI/CD or Travis CI. - Integration points: supports configuration files and command-line flags that cooperate with packaging tools like setuptools and poetry.

Usage

Black is invoked either from the command line, integrated into editor workflows, or run as part of automated pipelines. Typical usage patterns: - Command-line invocation via pip-installed entry point to reformat a project tree or single file. - Editor integration in Visual Studio Code, PyCharm, or Emacs to autoformat on save. - Pre-commit hooks using the pre-commit framework to enforce formatting prior to commits in repositories hosted on GitHub or GitLab. - CI enforcement by running a no-write check step in Jenkins, GitHub Actions, or CircleCI to fail builds when code is not formatted.

Configuration

Black intentionally limits configurability to preserve consistent output across teams and projects. Supported configuration mechanisms include: - pyproject.toml entries compatible with tools like Poetry and Flit to set values such as target line length and skip patterns. - Command-line flags for one-off formatting choices when used in scripts or ad-hoc runs within Bash or PowerShell environments. - Integration with pre-commit configuration to lock Black’s version and provide deterministic behavior across CI and local development. - Environment-specific invocation from build systems like tox and Nox to coordinate with testing frameworks such as pytest.

Integration and Tooling

Black’s ecosystem comprises editor plugins, CI examples, and compatibility layers: - Editor extensions exist for Visual Studio Code, PyCharm, Atom, and Vim enabling in-editor formatting and configuration synchronization. - Integration with the pre-commit project facilitates repository-level enforcement on hosts like GitHub and Bitbucket. - Tooling for large codebases includes parallelized runs and file-globbing strategies compatible with monorepos used by organizations such as Mozilla and Dropbox. - Combined usage with linters (Flake8, Pylint) and type checkers (mypy) is common to separate style normalization from static analysis and type validation.

Development and History

Black originated as a personal project and quickly attracted community contributions on GitHub under the stewardship of Łukasz Langa. Since its public debut in 2018, Black evolved with semantic releases, expanding support for successive Python (programming language) versions and language features such as f-string enhancements and pattern matching introduced in later versions of Python (programming language). The project governance has involved maintainers and external contributors coordinating via issue trackers and pull requests, mirroring workflows common to projects like CPython and NumFOCUS-hosted libraries.

Reception and Adoption

Black has been widely adopted across open-source and commercial projects, praised for reducing formatting debates and pull-request noise in communities centered around Django, Flask, FastAPI, and scientific stacks including SciPy and NumPy. Critics have voiced concerns about its opinionated decisions and limited configurability compared to traditional style guides such as PEP 8 or configurable formatters relying on style settings used by projects like YAPF. Nevertheless, major code hosts and editors include built-in or easily installable support for Black, and many large organizations recommend or mandate its use in contributor guides and internal tooling.

Category:Software