yapf

Display a diff of the changes that would be made, without making them (dry-run)

$ yapf [[-d|--diff]] [path/to/file]

$ yapf [[-ri|--recursive --in-place]] --style [pep8] [[-p|--parallel]] [path/to/directory]

yapf [options] <file or directory ...>
yapf --style-help
yapf --list-style-types

-i, --in-place
    Edit files in place. The original files are modified directly.

-d, --diff
    Print a diff of the changes that would be made to the files, without modifying them.

-r, --recursive
    Recursively format files in the specified directories. It processes all Python files found within.

-p, --parallel
    Run yapf in parallel using multiple processes, speeding up formatting for many files.

-s, --style <style>
    Specify a built-in style (e.g., pep8, google, facebook, chromium) or a path to a style definition file. The default is 'pep8'.

--verbose
    Print verbose messages, showing more details about the formatting process.

--version
    Show the program's version number and exit.

--list-style-types
    List all the supported built-in style types that can be used with the --style option.

--disable-smart-backticks
    Do not attempt to reformat backticks. This is useful for older Python 2 codebases.

--no-local-style
    Do not look for .style.yapf or setup.cfg files for style configuration. Only applies command-line or default styles.

--style-help
    Show detailed documentation about the available style options and their effects, then exit.

yapf, which stands for Yet Another Python Formatter, is a powerful tool developed by Google for automatically reformatting Python code. Its primary purpose is to ensure code conforms to the PEP 8 style guide, thereby enhancing readability and maintaining consistency across a codebase.

Unlike some other formatters, yapf is designed to be "uncompromising." This means it applies a single, opinionated formatting to a given piece of code, aiming to eliminate subjective style debates during code reviews. It can process individual files, entire directories recursively, or accept input directly from standard input. yapf supports various configuration options, allowing users to select predefined styles (like Google or Chromium) or define custom ones through command-line flags or dedicated configuration files. Its overarching goal is to streamline collaboration and reduce cognitive load by ensuring a uniform and aesthetically pleasing code style.

While yapf is highly effective, its "uncompromising" nature means it imposes a strict style that might not always align perfectly with every niche team preference, even if it adheres to PEP 8.

First-time application to a large, unformatted codebase can result in very significant changes, leading to large Git diffs. It's often recommended to apply it as a single, dedicated commit to avoid mixing formatting changes with functional ones.

yapf can be configured using a .style.yapf file placed in the project's root directory, or within a [yapf] section in pyproject.toml or setup.cfg. These files allow project-specific style settings to be defined and shared among team members, ensuring consistent formatting without needing to specify command-line arguments every time.

To maintain continuous code quality, yapf is often integrated directly into development workflows. This includes integration with popular Integrated Development Environments (IDEs) like VS Code and PyCharm, where it can automatically format code on save. It's also a common practice to include yapf as part of Git pre-commit hooks or Continuous Integration/Continuous Delivery (CI/CD) pipelines to automatically enforce code style checks before code is merged or deployed.

yapf was developed by Google and first released around 2015-2016. Its creation stemmed from the desire to standardize Python code formatting within Google and to address the inefficiencies of manual style adherence or subjective code reviews. The core philosophy behind yapf was to be "uncompromising," meaning for any given piece of code, there should ideally be only one correct way to format it. This approach aimed to eliminate endless debates over stylistic preferences, allowing developers to focus on the logic and functionality of their code.

black(1), autopep8(1), flake8(1)