A formatter for Python files.zip

# YAPF <p align="center"> <a href="https://badge.fury.io/py/yapf"><img alt="PyPI Version" src="https://badge.fury.io/py/yapf.svg"></a> <a href="https://github.com/google/yapf/actions/workflows/ci.yml"><img alt="Build Status" src="https://github.com/google/yapf/actions/workflows/ci.yml/badge.svg"></a> <a href="https://github.com/google/yapf/actions/workflows/pre-commit.yml"><img alt="Actions Status" src="https://github.com/google/yapf/actions/workflows/pre-commit.yml/badge.svg"></a> <a href="https://coveralls.io/github/google/yapf?branch=main"><img alt="Coverage Status" src="https://coveralls.io/repos/github/google/yapf/badge.svg?branch=main"></a> </p> ## Introduction YAPF is a Python formatter based off of [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html) (developed by Daniel Jasper). In essence, the algorithm takes the code and calculates the best formatting that conforms to the configured style. It takes away a lot of the drudgery of maintaining your code. The ultimate goal is that the code YAPF produces is as good as the code that a programmer would write if they were following the style guide. > **Note** > YAPF is not an official Google product (experimental or otherwise), it is > just code that happens to be owned by Google. ## Installation To install YAPF from PyPI: ```bash $ pip install yapf ``` YAPF is still considered in "beta" stage, and the released version may change often; therefore, the best way to keep up-to-date with the latest development is to clone this repository or install directly from github: ```bash $ pip install git+https://github.com/google/yapf.git ``` Note that if you intend to use YAPF as a command-line tool rather than as a library, installation is not necessary. YAPF supports being run as a directory by the Python interpreter. If you cloned/unzipped YAPF into `DIR`, it's possible to run: ```bash $ PYTHONPATH=DIR python DIR/yapf [options] ... ``` ## Using YAPF within your favorite editor YAPF is supported by multiple editors via community extensions or plugins. See [Editor Support](EDITOR%20SUPPORT.md) for more info. ## Required Python versions YAPF supports Python 3.7+. ## Usage ```console usage: yapf [-h] [-v] [-d | -i | -q] [-r | -l START-END] [-e PATTERN] [--style STYLE] [--style-help] [--no-local-style] [-p] [-m] [-vv] [files ...] Formatter for Python code. positional arguments: files reads from stdin when no files are specified. optional arguments: -h, --help show this help message and exit -v, --version show program's version number and exit -d, --diff print the diff for the fixed source -i, --in-place make changes to files in place -q, --quiet output nothing and set return value -r, --recursive run recursively over directories -l START-END, --lines START-END range of lines to reformat, one-based -e PATTERN, --exclude PATTERN patterns for files to exclude from formatting --style STYLE specify formatting style: either a style name (for example "pep8" or "google"), or the name of a file with style settings. The default is pep8 unless a .style.yapf or setup.cfg or pyproject.toml file located in the same directory as the source or one of its parent directories (for stdin, the current directory is used). --style-help show style settings and exit; this output can be saved to .style.yapf to make your settings permanent --no-local-style don't search for local style definition -p, --parallel run YAPF in parallel when formatting multiple files. -m, --print-modified print out file names of modified files -vv, --verbose print out file names while processing ``` ### Return Codes Normally YAPF returns zero on successful program termination and non-zero otherwise. If `--diff` is supplied, YAPF returns zero when no changes were necessary, non-zero otherwise (including program error). You can use this in a CI workflow to test that code has been YAPF-formatted. ### Excluding files from formatting (.yapfignore or pyproject.toml) In addition to exclude patterns provided on commandline, YAPF looks for additional patterns specified in a file named `.yapfignore` or `pyproject.toml` located in the working directory from which YAPF is invoked. `.yapfignore`'s syntax is similar to UNIX's filename pattern matching: ``` * matches everything ? matches any single character [seq] matches any character in seq [!seq] matches any character not in seq ``` Note that no entry should begin with `./`. If you use `pyproject.toml`, exclude patterns are specified by `ignore_patterns` key in `[tool.yapfignore]` section. For example: ```ini [tool.yapfignore] ignore_patterns = [ "temp/**/*.py", "temp2/*.py" ] ``` Formatting style ================ The formatting style used by YAPF is configurable and there are many "knobs" that can be used to tune how YAPF does formatting. See the `style.py` module for the full list. To control the style, run YAPF with the `--style` argument. It accepts one of the predefined styles (e.g., `pep8` or `google`), a path to a configuration file that specifies the desired style, or a dictionary of key/value pairs. The config file is a simple listing of (case-insensitive) `key = value` pairs with a `[style]` heading. For example: ```ini [style] based_on_style = pep8 spaces_before_comment = 4 split_before_logical_operator = true ``` The `based_on_style` setting determines which of the predefined styles this custom style is based on (think of it like subclassing). Four styles are predefined: - `pep8` (default) - `google` (based off of the [Google Python Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md)) - `yapf` (for use with Google open source projects) - `facebook` See `_STYLE_NAME_TO_FACTORY` in [`style.py`](https://github.com/google/yapf/blob/main/yapf/yapflib/style.py) for details. It's also possible to do the same on the command line with a dictionary. For example: ```bash --style='{based_on_style: pep8, indent_width: 2}' ``` This will take the `pep8` base style and modify it to have two space indentations. YAPF will search for the formatting style in the following manner: 1. Specified on the command line 2. In the `[style]` section of a `.style.yapf` file in either the current directory or one of its parent directories. 3. In the `[yapf]` section of a `setup.cfg` file in either the current directory or one of its parent directories. 4. In the `[tool.yapf]` section of a `pyproject.toml` file in either the current directory or one of its parent directories. 5. In the `[style]` section of a `~/.config/yapf/style` file in your home directory. If none of those files are found, the default style PEP8 is used. Example ======= An example of the type of formatting that YAPF can do, it will take this ugly code: ```python x = { 'a':37,'b':42, 'c':927} y = 'hello ''world' z = 'hello '+'world' a = 'hello {}'.format('world') class foo ( object ): def f (self ): return 37*-+2 def g(self, x,y=42): return y def f ( a ) : return 37+-+a[42-x : y**3] ``` and reformat it into: ```python x = {'a': 37, 'b': 42, 'c': 927} y = 'hello ' 'world' z = 'hello ' + 'world' a = 'hello {}'.format('world') class foo(object): def f(self): return 37 * -+2 def g(self, x, y=42): return y def f(a): return 37 + -+a[42 - x:y**3] ``` ## Example as a module The two main APIs for calling YAPF are `FormatCode` and `FormatFile`, these share several arguments which are described below: ```python >>> from yapf.yapflib.yapf_api import FormatCode # reformat a string of code >>> formatted_code, changed