# 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

```python
import black
```

Common imports for specific functionality:

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

## Basic Usage

```python
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.

```python { .api }
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](./formatting.md)

### 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.

```python { .api }
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](./configuration.md)

### Jupyter Notebook Support

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

```python { .api }
def format_cell(src: str, *, fast: bool, mode: Mode) -> str: ...
def format_ipynb_string(src_contents: str, *, fast: bool, mode: Mode) -> str: ...
```

[Jupyter Support](./jupyter.md)

### Command Line Interface

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

```python { .api }
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](./cli.md)

### Server API (BlackD)

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

```python { .api }
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](./server.md)

### Types and Exceptions

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

```python { .api }
class NothingChanged(UserWarning): ...
class InvalidInput(ValueError): ...
class ASTSafetyError(Exception): ...
```

[Types and Exceptions](./types.md)