CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-black

The uncompromising code formatter.

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

Black

Black is the uncompromising Python code formatter that formats Python code to be consistent and readable. It provides both command-line and programmatic APIs for formatting Python source code, Jupyter notebooks, and stub files according to configurable style rules.

Package Information

  • Package Name: black
  • Language: Python
  • Installation: pip install black

Core Imports

import black

Common imports for specific functionality:

from black import format_str, format_file_in_place, Mode, TargetVersion
from black import WriteBack, Changed, Report, NothingChanged

Basic Usage

import black

# Format a string of Python code
code = """def hello( name ):
    print(f'Hello {name}!')"""

# Format with default settings
formatted = black.format_str(code, mode=black.Mode())
print(formatted)
# Output: def hello(name):
#     print(f"Hello {name}!")

# Format with custom line length
mode = black.Mode(line_length=79)
formatted = black.format_str(code, mode=mode)

# Format targeting specific Python versions
mode = black.Mode(target_versions={black.TargetVersion.PY39, black.TargetVersion.PY310})
formatted = black.format_str(code, mode=mode)

# Format file in place
from pathlib import Path
changed = black.format_file_in_place(
    Path("script.py"),
    fast=False,
    mode=black.Mode(),
    write_back=black.WriteBack.YES
)

Architecture

Black's architecture centers around the Mode configuration system that controls all formatting behavior:

  • Mode: Central configuration class that controls formatting options, target Python versions, and feature flags
  • Formatting Pipeline: AST-based parsing and transformation with safety checks for equivalent output
  • Target Version System: Automatic detection and enforcement of Python version compatibility
  • Preview Features: Opt-in experimental formatting behaviors for future style evolution
  • Multi-format Support: Unified handling of .py files, .pyi stub files, and .ipynb Jupyter notebooks

Capabilities

Core Formatting Functions

Primary API functions for formatting Python code as strings, file contents, and files in place. Includes AST safety validation and stable formatting verification.

def format_str(src_contents: str, *, mode: Mode, lines: Collection[tuple[int, int]] = ()) -> str: ...
def format_file_contents(src_contents: str, *, fast: bool, mode: Mode, lines: Collection[tuple[int, int]] = ()) -> str: ...
def format_file_in_place(src: Path, fast: bool, mode: Mode, write_back: WriteBack = WriteBack.NO, lock: Any = None, *, lines: Collection[tuple[int, int]] = ()) -> bool: ...

Core Formatting

Configuration and Modes

Mode configuration system for controlling formatting behavior, target Python versions, preview features, and style options. Includes target version detection and feature compatibility checking.

class Mode:
    target_versions: set[TargetVersion] = field(default_factory=set)
    line_length: int = 88
    string_normalization: bool = True
    is_pyi: bool = False
    is_ipynb: bool = False
    skip_source_first_line: bool = False
    magic_trailing_comma: bool = True
    python_cell_magics: set[str] = field(default_factory=set)
    preview: bool = False
    unstable: bool = False
    enabled_features: set[Preview] = field(default_factory=set)

Configuration and Modes

Jupyter Notebook Support

Specialized formatting functions for Jupyter notebooks and individual notebook cells, with support for IPython magics and notebook-specific formatting rules.

def format_cell(src: str, *, fast: bool, mode: Mode) -> str: ...
def format_ipynb_string(src_contents: str, *, fast: bool, mode: Mode) -> str: ...

Jupyter Support

Command Line Interface

Complete CLI implementation with all formatting options, file discovery, configuration loading, and output modes including diffs and checks.

def main(ctx: click.Context, **options) -> None: ...
def get_sources(*, root: Path, src: tuple[str, ...], quiet: bool, verbose: bool, include: Pattern[str], exclude: Optional[Pattern[str]], extend_exclude: Optional[Pattern[str]], force_exclude: Optional[Pattern[str]], report: Report, stdin_filename: Optional[str]) -> set[Path]: ...

Command Line Interface

Server API (BlackD)

HTTP server API for formatting Python code via REST endpoints, with header-based configuration and protocol versioning.

def main(bind_host: str, bind_port: int) -> None: ...
def make_app() -> web.Application: ...
def handle(request: web.Request, executor: Executor) -> web.Response: ...

Server API

Types and Exceptions

Exception classes for error handling, constants for default configuration, type definitions, and utility functions for encoding and feature detection.

class NothingChanged(UserWarning): ...
class InvalidInput(ValueError): ...
class ASTSafetyError(Exception): ...

Types and Exceptions

Install with Tessl CLI

npx tessl i tessl/pypi-black
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/black@25.1.x
Publish Source
CLI
Badge
tessl/pypi-black badge