Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 1 | ==== |
| 2 | YAPF |
| 3 | ==== |
| 4 | |
Bill Wendling | 19c44d0 | 2015-04-07 23:48:05 -0700 | [diff] [blame] | 5 | .. image:: https://badge.fury.io/py/yapf.svg |
Ronald Eddy Jr | 808d7d2 | 2017-12-25 22:38:41 -0800 | [diff] [blame] | 6 | :target: https://badge.fury.io/py/yapf |
Bill Wendling | 19c44d0 | 2015-04-07 23:48:05 -0700 | [diff] [blame] | 7 | :alt: PyPI version |
| 8 | |
Bill Wendling | fb8ab38 | 2015-03-18 20:24:14 -0700 | [diff] [blame] | 9 | .. image:: https://travis-ci.org/google/yapf.svg?branch=master |
| 10 | :target: https://travis-ci.org/google/yapf |
| 11 | :alt: Build status |
| 12 | |
Bill Wendling | 14ac881 | 2015-04-05 02:47:32 -0700 | [diff] [blame] | 13 | .. image:: https://coveralls.io/repos/google/yapf/badge.svg?branch=master |
| 14 | :target: https://coveralls.io/r/google/yapf?branch=master |
| 15 | :alt: Coverage status |
| 16 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 17 | |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 18 | Introduction |
| 19 | ============ |
| 20 | |
Bill Wendling | 5632e67 | 2015-03-29 17:06:07 -0700 | [diff] [blame] | 21 | Most of the current formatters for Python --- e.g., autopep8, and pep8ify --- |
| 22 | are made to remove lint errors from code. This has some obvious limitations. |
| 23 | For instance, code that conforms to the PEP 8 guidelines may not be |
| 24 | reformatted. But it doesn't mean that the code looks good. |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 25 | |
| 26 | YAPF takes a different approach. It's based off of 'clang-format', developed by |
| 27 | Daniel Jasper. In essence, the algorithm takes the code and reformats it to the |
| 28 | best formatting that conforms to the style guide, even if the original code |
Peter Bengtsson | 1c60ad7 | 2015-03-24 20:05:39 -0700 | [diff] [blame] | 29 | didn't violate the style guide. The idea is also similar to the 'gofmt' tool for |
Eli Bendersky | 07072f8 | 2015-03-23 06:41:14 -0700 | [diff] [blame] | 30 | the Go programming language: end all holy wars about formatting - if the whole |
Samuel Dion-Girardeau | 5ae6349 | 2016-09-08 21:01:20 -0400 | [diff] [blame] | 31 | codebase of a project is simply piped through YAPF whenever modifications are |
Eli Bendersky | 07072f8 | 2015-03-23 06:41:14 -0700 | [diff] [blame] | 32 | made, the style remains consistent throughout the project and there's no point |
| 33 | arguing about style in every code review. |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 34 | |
| 35 | The ultimate goal is that the code YAPF produces is as good as the code that a |
Bill Wendling | 8fb9c48 | 2015-03-29 17:32:07 -0700 | [diff] [blame] | 36 | programmer would write if they were following the style guide. It takes away |
| 37 | some of the drudgery of maintaining your code. |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 38 | |
José Padilla | 45aea8e | 2018-01-16 12:26:33 -0500 | [diff] [blame] | 39 | Try out YAPF with this `online demo <https://yapf.now.sh>`_. |
José Padilla | 2774c1b | 2017-12-19 16:59:52 -0500 | [diff] [blame] | 40 | |
Bill Wendling | f5e50b6 | 2015-03-28 23:38:12 -0700 | [diff] [blame] | 41 | .. footer:: |
Bill Wendling | 52e0411 | 2015-03-18 20:42:26 -0700 | [diff] [blame] | 42 | |
| 43 | YAPF is not an official Google product (experimental or otherwise), it is |
| 44 | just code that happens to be owned by Google. |
| 45 | |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 46 | .. contents:: |
| 47 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 48 | |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 49 | Installation |
| 50 | ============ |
| 51 | |
Bill Wendling | 6e8ca7b | 2015-10-25 01:16:43 -0700 | [diff] [blame] | 52 | To install YAPF from PyPI: |
| 53 | |
Bill Wendling | a907b4f | 2018-05-21 23:50:24 -0700 | [diff] [blame] | 54 | .. code-block:: shell |
Eli Bendersky | 8a36536 | 2015-03-25 18:42:22 -0700 | [diff] [blame] | 55 | |
Eli Bendersky | e0e83c1 | 2015-04-06 20:23:30 -0700 | [diff] [blame] | 56 | $ pip install yapf |
| 57 | |
Diogo de Campos | 2f246c0 | 2016-10-06 14:04:38 +0200 | [diff] [blame] | 58 | (optional) If you are using Python 2.7 and want to enable multiprocessing: |
| 59 | |
Bill Wendling | a907b4f | 2018-05-21 23:50:24 -0700 | [diff] [blame] | 60 | .. code-block:: shell |
Diogo de Campos | 2f246c0 | 2016-10-06 14:04:38 +0200 | [diff] [blame] | 61 | |
| 62 | $ pip install futures |
| 63 | |
Eli Bendersky | e0e83c1 | 2015-04-06 20:23:30 -0700 | [diff] [blame] | 64 | YAPF is still considered in "alpha" stage, and the released version may change |
| 65 | often; therefore, the best way to keep up-to-date with the latest development |
| 66 | is to clone this repository. |
| 67 | |
| 68 | Note that if you intend to use YAPF as a command-line tool rather than as a |
| 69 | library, installation is not necessary. YAPF supports being run as a directory |
| 70 | by the Python interpreter. If you cloned/unzipped YAPF into ``DIR``, it's |
Bill Wendling | 6e8ca7b | 2015-10-25 01:16:43 -0700 | [diff] [blame] | 71 | possible to run: |
| 72 | |
Bill Wendling | a907b4f | 2018-05-21 23:50:24 -0700 | [diff] [blame] | 73 | .. code-block:: shell |
Eli Bendersky | 07072f8 | 2015-03-23 06:41:14 -0700 | [diff] [blame] | 74 | |
Eli Bendersky | b3678b3 | 2015-03-25 14:16:11 -0700 | [diff] [blame] | 75 | $ PYTHONPATH=DIR python DIR/yapf [options] ... |
Eli Bendersky | 07072f8 | 2015-03-23 06:41:14 -0700 | [diff] [blame] | 76 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 77 | |
Eli Bendersky | 5eb8823 | 2015-03-27 06:27:11 -0700 | [diff] [blame] | 78 | Python versions |
| 79 | =============== |
| 80 | |
Bill Wendling | fe6460f | 2018-01-26 15:08:07 -0800 | [diff] [blame] | 81 | YAPF supports Python 2.7 and 3.6.4+. (Note that some Python 3 features may fail |
| 82 | to parse with Python versions before 3.6.4.) |
Eli Bendersky | 5eb8823 | 2015-03-27 06:27:11 -0700 | [diff] [blame] | 83 | |
| 84 | YAPF requires the code it formats to be valid Python for the version YAPF itself |
| 85 | runs under. Therefore, if you format Python 3 code with YAPF, run YAPF itself |
| 86 | under Python 3 (and similarly for Python 2). |
| 87 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 88 | |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 89 | Usage |
| 90 | ===== |
| 91 | |
Bill Wendling | fa22c89 | 2015-03-18 13:42:25 -0700 | [diff] [blame] | 92 | Options:: |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 93 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 94 | usage: yapf [-h] [-v] [-d | -i] [-r | -l START-END] [-e PATTERN] |
Diogo de Campos | 2f246c0 | 2016-10-06 14:04:38 +0200 | [diff] [blame] | 95 | [--style STYLE] [--style-help] [--no-local-style] [-p] |
Bill Wendling | 7bfc0a9 | 2017-10-16 03:22:19 -0700 | [diff] [blame] | 96 | [-vv] |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 97 | [files [files ...]] |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 98 | |
Bill Wendling | fa22c89 | 2015-03-18 13:42:25 -0700 | [diff] [blame] | 99 | Formatter for Python code. |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 100 | |
Bill Wendling | fa22c89 | 2015-03-18 13:42:25 -0700 | [diff] [blame] | 101 | positional arguments: |
| 102 | files |
| 103 | |
| 104 | optional arguments: |
| 105 | -h, --help show this help message and exit |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 106 | -v, --version show version number and exit |
| 107 | -d, --diff print the diff for the fixed source |
| 108 | -i, --in-place make changes to files in place |
| 109 | -r, --recursive run recursively over directories |
| 110 | -l START-END, --lines START-END |
| 111 | range of lines to reformat, one-based |
| 112 | -e PATTERN, --exclude PATTERN |
| 113 | patterns for files to exclude from formatting |
Eli Bendersky | 83d2bd0 | 2015-03-23 06:33:48 -0700 | [diff] [blame] | 114 | --style STYLE specify formatting style: either a style name (for |
| 115 | example "pep8" or "google"), or the name of a file |
Sam Clegg | 5170c3a | 2015-04-16 12:18:58 -0700 | [diff] [blame] | 116 | with style settings. The default is pep8 unless a |
Peter Ludemann | 827260c | 2017-12-20 19:54:27 -0800 | [diff] [blame] | 117 | .style.yapf or setup.cfg file located in the same |
| 118 | directory as the source or one of its parent |
| 119 | directories (for stdin, the current directory is |
| 120 | used). |
Bill Wendling | 7bfc0a9 | 2017-10-16 03:22:19 -0700 | [diff] [blame] | 121 | --style-help show style settings and exit; this output can be saved |
| 122 | to .style.yapf to make your settings permanent |
| 123 | --no-local-style don't search for local style definition |
Diogo de Campos | 2f246c0 | 2016-10-06 14:04:38 +0200 | [diff] [blame] | 124 | -p, --parallel Run yapf in parallel when formatting multiple files. |
| 125 | Requires concurrent.futures in Python 2.X |
Bill Wendling | 7bfc0a9 | 2017-10-16 03:22:19 -0700 | [diff] [blame] | 126 | -vv, --verbose Print out file names while processing |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 127 | |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 128 | |
Mike Stipicevic | e176628 | 2018-04-16 17:09:38 +0200 | [diff] [blame] | 129 | ------------ |
| 130 | Return Codes |
| 131 | ------------ |
| 132 | |
| 133 | Normally YAPF returns zero on successful program termination and non-zero otherwise. |
| 134 | |
| 135 | If ``--diff`` is supplied, YAPF returns zero when no changes were necessary, non-zero |
| 136 | otherwise (including program error). You can use this in a CI workflow to test that code |
| 137 | has been YAPF-formatted. |
| 138 | |
| 139 | |
Eli Bendersky | 83d2bd0 | 2015-03-23 06:33:48 -0700 | [diff] [blame] | 140 | Formatting style |
Bill Wendling | f5e50b6 | 2015-03-28 23:38:12 -0700 | [diff] [blame] | 141 | ================ |
Eli Bendersky | 83d2bd0 | 2015-03-23 06:33:48 -0700 | [diff] [blame] | 142 | |
| 143 | The formatting style used by YAPF is configurable and there are many "knobs" |
| 144 | that can be used to tune how YAPF does formatting. See the ``style.py`` module |
| 145 | for the full list. |
| 146 | |
Bill Wendling | c016779 | 2015-04-02 01:58:39 -0700 | [diff] [blame] | 147 | To control the style, run YAPF with the ``--style`` argument. It accepts one of |
| 148 | the predefined styles (e.g., ``pep8`` or ``google``), a path to a configuration |
| 149 | file that specifies the desired style, or a dictionary of key/value pairs. |
| 150 | |
| 151 | The config file is a simple listing of (case-insensitive) ``key = value`` pairs |
Bill Wendling | 6e8ca7b | 2015-10-25 01:16:43 -0700 | [diff] [blame] | 152 | with a ``[style]`` heading. For example: |
| 153 | |
Bill Wendling | a907b4f | 2018-05-21 23:50:24 -0700 | [diff] [blame] | 154 | .. code-block:: ini |
Eli Bendersky | 83d2bd0 | 2015-03-23 06:33:48 -0700 | [diff] [blame] | 155 | |
| 156 | [style] |
| 157 | based_on_style = pep8 |
| 158 | spaces_before_comment = 4 |
| 159 | split_before_logical_operator = true |
| 160 | |
| 161 | The ``based_on_style`` setting determines which of the predefined styles this |
| 162 | custom style is based on (think of it like subclassing). |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 163 | |
Bill Wendling | c016779 | 2015-04-02 01:58:39 -0700 | [diff] [blame] | 164 | It's also possible to do the same on the command line with a dictionary. For |
Bill Wendling | 6e8ca7b | 2015-10-25 01:16:43 -0700 | [diff] [blame] | 165 | example: |
| 166 | |
Bill Wendling | a907b4f | 2018-05-21 23:50:24 -0700 | [diff] [blame] | 167 | .. code-block:: shell |
Bill Wendling | c016779 | 2015-04-02 01:58:39 -0700 | [diff] [blame] | 168 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 169 | --style='{based_on_style: chromium, indent_width: 4}' |
Bill Wendling | c016779 | 2015-04-02 01:58:39 -0700 | [diff] [blame] | 170 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 171 | This will take the ``chromium`` base style and modify it to have four space |
Bill Wendling | c016779 | 2015-04-02 01:58:39 -0700 | [diff] [blame] | 172 | indentations. |
| 173 | |
Bill Wendling | 169790e | 2015-10-25 03:13:13 -0700 | [diff] [blame] | 174 | YAPF will search for the formatting style in the following manner: |
| 175 | |
| 176 | 1. Specified on the command line |
Joshua Moravec | d8d15af | 2015-11-05 13:16:46 -0600 | [diff] [blame] | 177 | 2. In the `[style]` section of a `.style.yapf` file in either the current |
Bill Wendling | 169790e | 2015-10-25 03:13:13 -0700 | [diff] [blame] | 178 | directory or one of its parent directories. |
Bill Wendling | 821a36f | 2016-07-13 23:02:16 -0700 | [diff] [blame] | 179 | 3. In the `[yapf]` section of a `setup.cfg` file in either the current |
Bill Wendling | 169790e | 2015-10-25 03:13:13 -0700 | [diff] [blame] | 180 | directory or one of its parent directories. |
| 181 | 4. In the `~/.config/yapf/style` file in your home directory. |
| 182 | |
| 183 | If none of those files are found, the default style is used (PEP8). |
| 184 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 185 | |
Bill Wendling | f5e50b6 | 2015-03-28 23:38:12 -0700 | [diff] [blame] | 186 | Example |
| 187 | ======= |
| 188 | |
Sam Clegg | 4357fa3 | 2015-04-08 12:21:46 -0700 | [diff] [blame] | 189 | An example of the type of formatting that YAPF can do, it will take this ugly |
| 190 | code: |
Bill Wendling | f5e50b6 | 2015-03-28 23:38:12 -0700 | [diff] [blame] | 191 | |
| 192 | .. code-block:: python |
| 193 | |
| 194 | x = { 'a':37,'b':42, |
| 195 | |
| 196 | 'c':927} |
| 197 | |
| 198 | y = 'hello ''world' |
| 199 | z = 'hello '+'world' |
| 200 | a = 'hello {}'.format('world') |
| 201 | class foo ( object ): |
| 202 | def f (self ): |
| 203 | return 37*-+2 |
| 204 | def g(self, x,y=42): |
| 205 | return y |
| 206 | def f ( a ) : |
| 207 | return 37+-+a[42-x : y**3] |
| 208 | |
Bill Wendling | 8fb9c48 | 2015-03-29 17:32:07 -0700 | [diff] [blame] | 209 | and reformat it into: |
Bill Wendling | f5e50b6 | 2015-03-28 23:38:12 -0700 | [diff] [blame] | 210 | |
| 211 | .. code-block:: python |
| 212 | |
| 213 | x = {'a': 37, 'b': 42, 'c': 927} |
| 214 | |
| 215 | y = 'hello ' 'world' |
| 216 | z = 'hello ' + 'world' |
| 217 | a = 'hello {}'.format('world') |
| 218 | |
| 219 | |
| 220 | class foo(object): |
Bill Wendling | 5632e67 | 2015-03-29 17:06:07 -0700 | [diff] [blame] | 221 | def f(self): |
| 222 | return 37 * -+2 |
Bill Wendling | f5e50b6 | 2015-03-28 23:38:12 -0700 | [diff] [blame] | 223 | |
Bill Wendling | 5632e67 | 2015-03-29 17:06:07 -0700 | [diff] [blame] | 224 | def g(self, x, y=42): |
| 225 | return y |
Bill Wendling | f5e50b6 | 2015-03-28 23:38:12 -0700 | [diff] [blame] | 226 | |
| 227 | |
| 228 | def f(a): |
Bill Wendling | 8d8f512 | 2015-10-16 11:46:23 -0700 | [diff] [blame] | 229 | return 37 + -+a[42 - x:y**3] |
Bill Wendling | f5e50b6 | 2015-03-28 23:38:12 -0700 | [diff] [blame] | 230 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 231 | |
Andy Hayden | a00a6bf | 2015-06-15 18:47:41 -0700 | [diff] [blame] | 232 | Example as a module |
| 233 | =================== |
| 234 | |
Andy Hayden | 4af7168 | 2015-06-17 15:42:43 -0700 | [diff] [blame] | 235 | The two main APIs for calling yapf are ``FormatCode`` and ``FormatFile``, these |
| 236 | share several arguments which are described below: |
Andy Hayden | a00a6bf | 2015-06-15 18:47:41 -0700 | [diff] [blame] | 237 | |
| 238 | .. code-block:: python |
| 239 | |
srinivasanramaraju | cfa7ead | 2017-02-14 00:06:58 -0800 | [diff] [blame] | 240 | >>> from yapf.yapflib.yapf_api import FormatCode # reformat a string of code |
Łukasz Langa | 9408987 | 2015-09-22 16:02:26 -0700 | [diff] [blame] | 241 | |
Andy Hayden | a00a6bf | 2015-06-15 18:47:41 -0700 | [diff] [blame] | 242 | >>> FormatCode("f ( a = 1, b = 2 )") |
| 243 | 'f(a=1, b=2)\n' |
| 244 | |
Andy Hayden | 4af7168 | 2015-06-17 15:42:43 -0700 | [diff] [blame] | 245 | A ``style_config`` argument: Either a style name or a path to a file that contains |
Andy Hayden | a00a6bf | 2015-06-15 18:47:41 -0700 | [diff] [blame] | 246 | formatting style settings. If None is specified, use the default style |
| 247 | as set in ``style.DEFAULT_STYLE_FACTORY``. |
| 248 | |
| 249 | .. code-block:: python |
| 250 | |
| 251 | >>> FormatCode("def g():\n return True", style_config='pep8') |
| 252 | 'def g():\n return True\n' |
| 253 | |
Andy Hayden | a00a6bf | 2015-06-15 18:47:41 -0700 | [diff] [blame] | 254 | A ``lines`` argument: A list of tuples of lines (ints), [start, end], |
| 255 | that we want to format. The lines are 1-based indexed. It can be used by |
| 256 | third-party code (e.g., IDEs) when reformatting a snippet of code rather |
| 257 | than a whole file. |
| 258 | |
| 259 | .. code-block:: python |
| 260 | |
| 261 | >>> FormatCode("def g( ):\n a=1\n b = 2\n return a==b", lines=[(1, 1), (2, 3)]) |
| 262 | 'def g():\n a = 1\n b = 2\n return a==b\n' |
| 263 | |
| 264 | A ``print_diff`` (bool): Instead of returning the reformatted source, return a |
| 265 | diff that turns the formatted source into reformatter source. |
| 266 | |
| 267 | .. code-block:: python |
| 268 | |
| 269 | >>> print(FormatCode("a==b", filename="foo.py", print_diff=True)) |
Bill Wendling | b8645ea | 2015-06-30 22:27:56 -0700 | [diff] [blame] | 270 | --- foo.py (original) |
| 271 | +++ foo.py (reformatted) |
Andy Hayden | a00a6bf | 2015-06-15 18:47:41 -0700 | [diff] [blame] | 272 | @@ -1 +1 @@ |
| 273 | -a==b |
| 274 | +a == b |
| 275 | |
Andy Hayden | 4af7168 | 2015-06-17 15:42:43 -0700 | [diff] [blame] | 276 | Note: the ``filename`` argument for ``FormatCode`` is what is inserted into |
| 277 | the diff, the default is ``<unknown>``. |
Andy Hayden | a00a6bf | 2015-06-15 18:47:41 -0700 | [diff] [blame] | 278 | |
| 279 | ``FormatFile`` returns reformatted code from the passed file along with its encoding: |
| 280 | |
| 281 | .. code-block:: python |
| 282 | |
srinivasanramaraju | cfa7ead | 2017-02-14 00:06:58 -0800 | [diff] [blame] | 283 | >>> from yapf.yapflib.yapf_api import FormatFile # reformat a file |
Andy Hayden | 4af7168 | 2015-06-17 15:42:43 -0700 | [diff] [blame] | 284 | |
Andy Hayden | a00a6bf | 2015-06-15 18:47:41 -0700 | [diff] [blame] | 285 | >>> print(open("foo.py").read()) # contents of file |
| 286 | a==b |
| 287 | |
| 288 | >>> FormatFile("foo.py") |
Andy Hayden | 4af7168 | 2015-06-17 15:42:43 -0700 | [diff] [blame] | 289 | ('a == b\n', 'utf-8') |
| 290 | |
Bill Wendling | cfbb124 | 2015-09-20 12:08:18 -0700 | [diff] [blame] | 291 | The ``in-place`` argument saves the reformatted code back to the file: |
Andy Hayden | 4af7168 | 2015-06-17 15:42:43 -0700 | [diff] [blame] | 292 | |
| 293 | .. code-block:: python |
| 294 | |
| 295 | >>> FormatFile("foo.py", in_place=True) |
| 296 | (None, 'utf-8') |
| 297 | |
| 298 | >>> print(open("foo.py").read()) # contents of file (now fixed) |
| 299 | a == b |
| 300 | |
Andy Hayden | a00a6bf | 2015-06-15 18:47:41 -0700 | [diff] [blame] | 301 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 302 | Knobs |
| 303 | ===== |
| 304 | |
| 305 | ``ALIGN_CLOSING_BRACKET_WITH_VISUAL_INDENT`` |
| 306 | Align closing bracket with visual indentation. |
| 307 | |
Bill Wendling | 996c3ee | 2016-05-25 23:52:24 -0700 | [diff] [blame] | 308 | ``ALLOW_MULTILINE_LAMBDAS`` |
| 309 | Allow lambdas to be formatted on more than one line. |
| 310 | |
Bill Wendling | 8d32136 | 2017-02-05 18:29:26 -0800 | [diff] [blame] | 311 | ``ALLOW_MULTILINE_DICTIONARY_KEYS`` |
| 312 | Allow dictionary keys to exist on multiple lines. For example: |
| 313 | |
| 314 | .. code-block:: python |
| 315 | |
| 316 | x = { |
| 317 | ('this is the first element of a tuple', |
| 318 | 'this is the second element of a tuple'): |
| 319 | value, |
| 320 | } |
| 321 | |
Bill Wendling | 8a3b71f | 2017-08-26 02:34:03 -0700 | [diff] [blame] | 322 | ``ALLOW_SPLIT_BEFORE_DICT_VALUE`` |
| 323 | Allow splits before the dictionary value. |
| 324 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 325 | ``BLANK_LINE_BEFORE_NESTED_CLASS_OR_DEF`` |
Bill Wendling | c2a9e0d | 2016-05-24 20:51:04 -0700 | [diff] [blame] | 326 | Insert a blank line before a ``def`` or ``class`` immediately nested within |
Bill Wendling | 996c3ee | 2016-05-25 23:52:24 -0700 | [diff] [blame] | 327 | another ``def`` or ``class``. For example: |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 328 | |
Bill Wendling | c2a9e0d | 2016-05-24 20:51:04 -0700 | [diff] [blame] | 329 | .. code-block:: python |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 330 | |
| 331 | class Foo: |
| 332 | # <------ this blank line |
| 333 | def method(): |
| 334 | pass |
| 335 | |
Dan Porter | 61d8809 | 2018-03-22 12:52:16 +0000 | [diff] [blame] | 336 | ``BLANK_LINE_BEFORE_MODULE_DOCSTRING`` |
| 337 | Insert a blank line before a module docstring. |
| 338 | |
Bill Wendling | 9f49752 | 2017-02-04 04:39:47 -0800 | [diff] [blame] | 339 | ``BLANK_LINE_BEFORE_CLASS_DOCSTRING`` |
| 340 | Insert a blank line before a class-level docstring. |
| 341 | |
Markus Gerstel | c0d3268 | 2018-02-14 17:07:35 +0000 | [diff] [blame] | 342 | ``BLANK_LINES_AROUND_TOP_LEVEL_DEFINITION`` |
| 343 | Sets the number of desired blank lines surrounding top-level function and |
| 344 | class definitions. For example: |
| 345 | |
| 346 | .. code-block:: python |
| 347 | |
| 348 | class Foo: |
| 349 | pass |
| 350 | # <------ having two blank lines here |
| 351 | # <------ is the default setting |
| 352 | class Bar: |
| 353 | pass |
| 354 | |
Ben Plotnick | 7e08829 | 2016-06-09 18:29:56 -0700 | [diff] [blame] | 355 | ``COALESCE_BRACKETS`` |
| 356 | Do not split consecutive brackets. Only relevant when |
| 357 | ``DEDENT_CLOSING_BRACKETS`` is set. For example: |
| 358 | |
| 359 | .. code-block:: python |
| 360 | |
| 361 | call_func_that_takes_a_dict( |
| 362 | { |
| 363 | 'key1': 'value1', |
| 364 | 'key2': 'value2', |
| 365 | } |
| 366 | ) |
| 367 | |
| 368 | would reformat to: |
| 369 | |
| 370 | .. code-block:: python |
| 371 | |
| 372 | call_func_that_takes_a_dict({ |
| 373 | 'key1': 'value1', |
| 374 | 'key2': 'value2', |
| 375 | }) |
| 376 | |
| 377 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 378 | ``COLUMN_LIMIT`` |
James Broadhead | f4dd804 | 2016-01-07 14:40:19 +0000 | [diff] [blame] | 379 | The column limit (or max line-length) |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 380 | |
Yinyin L | a56072f | 2018-03-05 02:04:34 +0800 | [diff] [blame] | 381 | ``CONTINUATION_ALIGN_STYLE`` |
| 382 | The style for continuation alignment. Possible values are: |
| 383 | |
| 384 | - SPACE: Use spaces for continuation alignment. This is default behavior. |
| 385 | - FIXED: Use fixed number (CONTINUATION_INDENT_WIDTH) of columns |
| 386 | (ie: CONTINUATION_INDENT_WIDTH/INDENT_WIDTH tabs) for continuation |
| 387 | alignment. |
| 388 | - VALIGN-RIGHT: Vertically align continuation lines with indent characters. |
| 389 | Slightly right (one more indent character) if cannot vertically align |
| 390 | continuation lines with indent characters. |
| 391 | |
| 392 | For options ``FIXED``, and ``VALIGN-RIGHT`` are only available when |
| 393 | ``USE_TABS`` is enabled. |
| 394 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 395 | ``CONTINUATION_INDENT_WIDTH`` |
| 396 | Indent width used for line continuations. |
| 397 | |
| 398 | ``DEDENT_CLOSING_BRACKETS`` |
| 399 | Put closing brackets on a separate line, dedented, if the bracketed |
| 400 | expression can't fit in a single line. Applies to all kinds of brackets, |
Bill Wendling | c2a9e0d | 2016-05-24 20:51:04 -0700 | [diff] [blame] | 401 | including function definitions and calls. For example: |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 402 | |
Bill Wendling | c2a9e0d | 2016-05-24 20:51:04 -0700 | [diff] [blame] | 403 | .. code-block:: python |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 404 | |
| 405 | config = { |
| 406 | 'key1': 'value1', |
| 407 | 'key2': 'value2', |
Bill Wendling | c2a9e0d | 2016-05-24 20:51:04 -0700 | [diff] [blame] | 408 | } # <--- this bracket is dedented and on a separate line |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 409 | |
| 410 | time_series = self.remote_client.query_entity_counters( |
Bill Wendling | c2a9e0d | 2016-05-24 20:51:04 -0700 | [diff] [blame] | 411 | entity='dev3246.region1', |
| 412 | key='dns.query_latency_tcp', |
| 413 | transform=Transformation.AVERAGE(window=timedelta(seconds=60)), |
| 414 | start_ts=now()-timedelta(days=3), |
| 415 | end_ts=now(), |
| 416 | ) # <--- this bracket is dedented and on a separate line |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 417 | |
Bill Wendling | 4922549 | 2018-07-01 23:02:35 -0700 | [diff] [blame] | 418 | ``DISABLE_ENDING_COMMA_HEURISTIC`` |
| 419 | Disable the heuristic which places each list element on a separate line if |
| 420 | the list is comma-terminated. |
| 421 | |
Bill Wendling | 0e9b321 | 2017-01-31 14:41:00 -0800 | [diff] [blame] | 422 | ``EACH_DICT_ENTRY_ON_SEPARATE_LINE`` |
| 423 | Place each dictionary entry onto its own line. |
| 424 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 425 | ``I18N_COMMENT`` |
| 426 | The regex for an internationalization comment. The presence of this comment |
| 427 | stops reformatting of that line, because the comments are required to be |
| 428 | next to the string they translate. |
| 429 | |
| 430 | ``I18N_FUNCTION_CALL`` |
Bill Wendling | c2a9e0d | 2016-05-24 20:51:04 -0700 | [diff] [blame] | 431 | The internationalization function call names. The presence of this function |
Samuel Dion-Girardeau | 5ae6349 | 2016-09-08 21:01:20 -0400 | [diff] [blame] | 432 | stops reformatting on that line, because the string it has cannot be moved |
Bill Wendling | c2a9e0d | 2016-05-24 20:51:04 -0700 | [diff] [blame] | 433 | away from the i18n comment. |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 434 | |
| 435 | ``INDENT_DICTIONARY_VALUE`` |
| 436 | Indent the dictionary value if it cannot fit on the same line as the |
Bill Wendling | c2a9e0d | 2016-05-24 20:51:04 -0700 | [diff] [blame] | 437 | dictionary key. For example: |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 438 | |
Bill Wendling | c2a9e0d | 2016-05-24 20:51:04 -0700 | [diff] [blame] | 439 | .. code-block:: python |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 440 | |
| 441 | config = { |
| 442 | 'key1': |
| 443 | 'value1', |
| 444 | 'key2': value1 + |
| 445 | value2, |
| 446 | } |
| 447 | |
| 448 | ``INDENT_WIDTH`` |
| 449 | The number of columns to use for indentation. |
| 450 | |
| 451 | ``JOIN_MULTIPLE_LINES`` |
| 452 | Join short lines into one line. E.g., single line ``if`` statements. |
| 453 | |
Bill Wendling | 9dc7908 | 2016-05-10 00:23:53 -0700 | [diff] [blame] | 454 | ``SPACES_AROUND_POWER_OPERATOR`` |
| 455 | Set to ``True`` to prefer using spaces around ``**``. |
| 456 | |
Jiri Kuncar | f14bd17 | 2017-07-21 09:45:31 +0200 | [diff] [blame] | 457 | ``NO_SPACES_AROUND_SELECTED_BINARY_OPERATORS`` |
| 458 | Do not include spaces around selected binary operators. For example: |
| 459 | |
| 460 | .. code-block:: python |
| 461 | |
| 462 | 1 + 2 * 3 - 4 / 5 |
| 463 | |
Bill Wendling | 9518bab | 2018-07-01 22:17:25 -0700 | [diff] [blame] | 464 | will be formatted as follows when configured with ``*,/``: |
Jiri Kuncar | f14bd17 | 2017-07-21 09:45:31 +0200 | [diff] [blame] | 465 | |
| 466 | .. code-block:: python |
| 467 | |
| 468 | 1 + 2*3 - 4/5 |
| 469 | |
Alexander Lenz | 5fda36a | 2016-08-26 17:27:57 +0200 | [diff] [blame] | 470 | ``SPACES_AROUND_DEFAULT_OR_NAMED_ASSIGN`` |
| 471 | Set to ``True`` to prefer spaces around the assignment operator for default |
| 472 | or keyword arguments. |
| 473 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 474 | ``SPACES_BEFORE_COMMENT`` |
| 475 | The number of spaces required before a trailing comment. |
| 476 | |
Bill Wendling | 996c3ee | 2016-05-25 23:52:24 -0700 | [diff] [blame] | 477 | ``SPACE_BETWEEN_ENDING_COMMA_AND_CLOSING_BRACKET`` |
| 478 | Insert a space between the ending comma and closing bracket of a list, etc. |
| 479 | |
Bill Wendling | 982c5b3 | 2016-05-24 00:47:44 -0700 | [diff] [blame] | 480 | ``SPLIT_ARGUMENTS_WHEN_COMMA_TERMINATED`` |
| 481 | Split before arguments if the argument list is terminated by a comma. |
| 482 | |
cardenb | 99c9bb1 | 2018-05-15 11:40:28 -0700 | [diff] [blame] | 483 | ``SPLIT_ALL_COMMA_SEPARATED_VALUES`` |
| 484 | If a comma separated list (dict, list, tuple, or function def) is on a |
| 485 | line that is too long, split such that all elements are on a single line. |
| 486 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 487 | ``SPLIT_BEFORE_BITWISE_OPERATOR`` |
| 488 | Set to ``True`` to prefer splitting before ``&``, ``|`` or ``^`` rather |
| 489 | than after. |
| 490 | |
Patryk Zawadzki | 6d79f13 | 2018-02-13 16:31:25 +0100 | [diff] [blame] | 491 | ``SPLIT_BEFORE_CLOSING_BRACKET`` |
| 492 | Split before the closing bracket if a list or dict literal doesn't fit on |
| 493 | a single line. |
| 494 | |
Bill Wendling | 0e9b321 | 2017-01-31 14:41:00 -0800 | [diff] [blame] | 495 | ``SPLIT_BEFORE_DICT_SET_GENERATOR`` |
| 496 | Split before a dictionary or set generator (comp_for). For example, note |
| 497 | the split before the ``for``: |
| 498 | |
| 499 | .. code-block:: python |
| 500 | |
| 501 | foo = { |
| 502 | variable: 'Hello world, have a nice day!' |
| 503 | for variable in bar if variable != 42 |
| 504 | } |
| 505 | |
Bill Wendling | 6113e7e | 2017-10-09 01:11:38 -0700 | [diff] [blame] | 506 | ``SPLIT_BEFORE_EXPRESSION_AFTER_OPENING_PAREN`` |
| 507 | Split after the opening paren which surrounds an expression if it doesn't |
| 508 | fit on a single line. |
| 509 | |
Bill Wendling | 996c3ee | 2016-05-25 23:52:24 -0700 | [diff] [blame] | 510 | ``SPLIT_BEFORE_FIRST_ARGUMENT`` |
| 511 | If an argument / parameter list is going to be split, then split before the |
| 512 | first argument. |
| 513 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 514 | ``SPLIT_BEFORE_LOGICAL_OPERATOR`` |
| 515 | Set to ``True`` to prefer splitting before ``and`` or ``or`` rather than |
| 516 | after. |
| 517 | |
| 518 | ``SPLIT_BEFORE_NAMED_ASSIGNS`` |
| 519 | Split named assignments onto individual lines. |
| 520 | |
Matthew Suozzo | 4a3b633 | 2017-11-01 17:38:37 -0400 | [diff] [blame] | 521 | ``SPLIT_COMPLEX_COMPREHENSION`` |
| 522 | For list comprehensions and generator expressions with multiple clauses |
delirious-lettuce | b795f6d | 2018-01-16 20:38:46 -0700 | [diff] [blame] | 523 | (e.g multiple "for" calls, "if" filter expressions) and which need to be |
Matthew Suozzo | 4a3b633 | 2017-11-01 17:38:37 -0400 | [diff] [blame] | 524 | reflowed, split each clause onto its own line. For example: |
| 525 | |
| 526 | .. code-block:: python |
| 527 | |
| 528 | result = [ |
| 529 | a_var + b_var for a_var in xrange(1000) for b_var in xrange(1000) |
| 530 | if a_var % b_var] |
| 531 | |
| 532 | would reformat to something like: |
| 533 | |
| 534 | .. code-block:: python |
| 535 | |
| 536 | result = [ |
| 537 | a_var + b_var |
| 538 | for a_var in xrange(1000) |
| 539 | for b_var in xrange(1000) |
| 540 | if a_var % b_var] |
| 541 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 542 | ``SPLIT_PENALTY_AFTER_OPENING_BRACKET`` |
| 543 | The penalty for splitting right after the opening bracket. |
| 544 | |
| 545 | ``SPLIT_PENALTY_AFTER_UNARY_OPERATOR`` |
| 546 | The penalty for splitting the line after a unary operator. |
| 547 | |
Bill Wendling | 996c3ee | 2016-05-25 23:52:24 -0700 | [diff] [blame] | 548 | ``SPLIT_PENALTY_BEFORE_IF_EXPR`` |
| 549 | The penalty for splitting right before an ``if`` expression. |
| 550 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 551 | ``SPLIT_PENALTY_BITWISE_OPERATOR`` |
| 552 | The penalty of splitting the line around the ``&``, ``|``, and ``^`` |
| 553 | operators. |
| 554 | |
Matthew Suozzo | 3a0f6e7 | 2017-11-01 17:40:57 -0400 | [diff] [blame] | 555 | ``SPLIT_PENALTY_COMPREHENSION`` |
| 556 | The penalty for splitting a list comprehension or generator expression. |
| 557 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 558 | ``SPLIT_PENALTY_EXCESS_CHARACTER`` |
| 559 | The penalty for characters over the column limit. |
| 560 | |
| 561 | ``SPLIT_PENALTY_FOR_ADDED_LINE_SPLIT`` |
Bill Wendling | c2a9e0d | 2016-05-24 20:51:04 -0700 | [diff] [blame] | 562 | The penalty incurred by adding a line split to the unwrapped line. The more |
| 563 | line splits added the higher the penalty. |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 564 | |
| 565 | ``SPLIT_PENALTY_IMPORT_NAMES`` |
Bill Wendling | c2a9e0d | 2016-05-24 20:51:04 -0700 | [diff] [blame] | 566 | The penalty of splitting a list of ``import as`` names. For example: |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 567 | |
Bill Wendling | c2a9e0d | 2016-05-24 20:51:04 -0700 | [diff] [blame] | 568 | .. code-block:: python |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 569 | |
| 570 | from a_very_long_or_indented_module_name_yada_yad import (long_argument_1, |
| 571 | long_argument_2, |
| 572 | long_argument_3) |
| 573 | |
| 574 | would reformat to something like: |
| 575 | |
Bill Wendling | c2a9e0d | 2016-05-24 20:51:04 -0700 | [diff] [blame] | 576 | .. code-block:: python |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 577 | |
| 578 | from a_very_long_or_indented_module_name_yada_yad import ( |
| 579 | long_argument_1, long_argument_2, long_argument_3) |
| 580 | |
| 581 | ``SPLIT_PENALTY_LOGICAL_OPERATOR`` |
| 582 | The penalty of splitting the line around the ``and`` and ``or`` operators. |
| 583 | |
Dracony | e582d63 | 2016-06-05 11:48:26 +0200 | [diff] [blame] | 584 | ``USE_TABS`` |
| 585 | Use the Tab character for indentation. |
| 586 | |
Bill Wendling | 8fb9c48 | 2015-03-29 17:32:07 -0700 | [diff] [blame] | 587 | (Potentially) Frequently Asked Questions |
| 588 | ======================================== |
| 589 | |
Bill Wendling | a907b4f | 2018-05-21 23:50:24 -0700 | [diff] [blame] | 590 | -------------------------------------------- |
Bill Wendling | 8fb9c48 | 2015-03-29 17:32:07 -0700 | [diff] [blame] | 591 | Why does YAPF destroy my awesome formatting? |
| 592 | -------------------------------------------- |
| 593 | |
| 594 | YAPF tries very hard to get the formatting correct. But for some code, it won't |
| 595 | be as good as hand-formatting. In particular, large data literals may become |
| 596 | horribly disfigured under YAPF. |
| 597 | |
mlimber | 8af5baf | 2017-11-09 13:53:22 -0500 | [diff] [blame] | 598 | The reasons for this are manyfold. In short, YAPF is simply a tool to help |
Bill Wendling | 8fb9c48 | 2015-03-29 17:32:07 -0700 | [diff] [blame] | 599 | with development. It will format things to coincide with the style guide, but |
| 600 | that may not equate with readability. |
| 601 | |
| 602 | What can be done to alleviate this situation is to indicate regions YAPF should |
| 603 | ignore when reformatting something: |
| 604 | |
| 605 | .. code-block:: python |
| 606 | |
| 607 | # yapf: disable |
| 608 | FOO = { |
| 609 | # ... some very large, complex data literal. |
| 610 | } |
| 611 | |
| 612 | BAR = [ |
| 613 | # ... another large data literal. |
| 614 | ] |
| 615 | # yapf: enable |
| 616 | |
| 617 | You can also disable formatting for a single literal like this: |
| 618 | |
| 619 | .. code-block:: python |
| 620 | |
| 621 | BAZ = { |
Scott Sanderson | eda4e26 | 2015-07-05 21:10:06 -0400 | [diff] [blame] | 622 | (1, 2, 3, 4), |
| 623 | (5, 6, 7, 8), |
| 624 | (9, 10, 11, 12), |
Bill Wendling | 8fb9c48 | 2015-03-29 17:32:07 -0700 | [diff] [blame] | 625 | } # yapf: disable |
| 626 | |
Łukasz Langa | 9408987 | 2015-09-22 16:02:26 -0700 | [diff] [blame] | 627 | To preserve the nice dedented closing brackets, use the |
| 628 | ``dedent_closing_brackets`` in your style. Note that in this case all |
| 629 | brackets, including function definitions and calls, are going to use |
| 630 | that style. This provides consistency across the formatted codebase. |
| 631 | |
Bill Wendling | a907b4f | 2018-05-21 23:50:24 -0700 | [diff] [blame] | 632 | ------------------------------- |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 633 | Why Not Improve Existing Tools? |
Bill Wendling | 8fb9c48 | 2015-03-29 17:32:07 -0700 | [diff] [blame] | 634 | ------------------------------- |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 635 | |
| 636 | We wanted to use clang-format's reformatting algorithm. It's very powerful and |
| 637 | designed to come up with the best formatting possible. Existing tools were |
| 638 | created with different goals in mind, and would require extensive modifications |
| 639 | to convert to using clang-format's algorithm. |
| 640 | |
Bill Wendling | a907b4f | 2018-05-21 23:50:24 -0700 | [diff] [blame] | 641 | ----------------------------- |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 642 | Can I Use YAPF In My Program? |
Bill Wendling | 8fb9c48 | 2015-03-29 17:32:07 -0700 | [diff] [blame] | 643 | ----------------------------- |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 644 | |
| 645 | Please do! YAPF was designed to be used as a library as well as a command line |
| 646 | tool. This means that a tool or IDE plugin is free to use YAPF. |
| 647 | |
Bill Wendling | f09121c | 2015-10-20 22:59:33 -0700 | [diff] [blame] | 648 | |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 649 | Gory Details |
| 650 | ============ |
| 651 | |
Bill Wendling | a907b4f | 2018-05-21 23:50:24 -0700 | [diff] [blame] | 652 | ---------------- |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 653 | Algorithm Design |
| 654 | ---------------- |
| 655 | |
Eli Bendersky | d08130d | 2015-03-19 05:20:46 -0700 | [diff] [blame] | 656 | The main data structure in YAPF is the ``UnwrappedLine`` object. It holds a list |
| 657 | of ``FormatToken``\s, that we would want to place on a single line if there were |
| 658 | no column limit. An exception being a comment in the middle of an expression |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 659 | statement will force the line to be formatted on more than one line. The |
Eli Bendersky | d08130d | 2015-03-19 05:20:46 -0700 | [diff] [blame] | 660 | formatter works on one ``UnwrappedLine`` object at a time. |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 661 | |
Eli Bendersky | d08130d | 2015-03-19 05:20:46 -0700 | [diff] [blame] | 662 | An ``UnwrappedLine`` typically won't affect the formatting of lines before or |
| 663 | after it. There is a part of the algorithm that may join two or more |
| 664 | ``UnwrappedLine``\s into one line. For instance, an if-then statement with a |
Bill Wendling | f5e50b6 | 2015-03-28 23:38:12 -0700 | [diff] [blame] | 665 | short body can be placed on a single line: |
| 666 | |
| 667 | .. code-block:: python |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 668 | |
| 669 | if a == 42: continue |
| 670 | |
| 671 | YAPF's formatting algorithm creates a weighted tree that acts as the solution |
| 672 | space for the algorithm. Each node in the tree represents the result of a |
| 673 | formatting decision --- i.e., whether to split or not to split before a token. |
| 674 | Each formatting decision has a cost associated with it. Therefore, the cost is |
| 675 | realized on the edge between two nodes. (In reality, the weighted tree doesn't |
| 676 | have separate edge objects, so the cost resides on the nodes themselves.) |
| 677 | |
| 678 | For example, take the following Python code snippet. For the sake of this |
| 679 | example, assume that line (1) violates the column limit restriction and needs to |
| 680 | be reformatted. |
| 681 | |
Bill Wendling | fa22c89 | 2015-03-18 13:42:25 -0700 | [diff] [blame] | 682 | .. code-block:: python |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 683 | |
Bill Wendling | fa22c89 | 2015-03-18 13:42:25 -0700 | [diff] [blame] | 684 | def xxxxxxxxxxx(aaaaaaaaaaaa, bbbbbbbbb, cccccccc, dddddddd, eeeeee): # 1 |
| 685 | pass # 2 |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 686 | |
| 687 | For line (1), the algorithm will build a tree where each node (a |
Eli Bendersky | d08130d | 2015-03-19 05:20:46 -0700 | [diff] [blame] | 688 | ``FormattingDecisionState`` object) is the state of the line at that token given |
| 689 | the decision to split before the token or not. Note: the ``FormatDecisionState`` |
| 690 | objects are copied by value so each node in the graph is unique and a change in |
| 691 | one doesn't affect other nodes. |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 692 | |
Bill Wendling | fa22c89 | 2015-03-18 13:42:25 -0700 | [diff] [blame] | 693 | Heuristics are used to determine the costs of splitting or not splitting. |
| 694 | Because a node holds the state of the tree up to a token's insertion, it can |
| 695 | easily determine if a splitting decision will violate one of the style |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 696 | requirements. For instance, the heuristic is able to apply an extra penalty to |
| 697 | the edge when not splitting between the previous token and the one being added. |
| 698 | |
| 699 | There are some instances where we will never want to split the line, because |
| 700 | doing so will always be detrimental (i.e., it will require a backslash-newline, |
| 701 | which is very rarely desirable). For line (1), we will never want to split the |
Eli Bendersky | d08130d | 2015-03-19 05:20:46 -0700 | [diff] [blame] | 702 | first three tokens: ``def``, ``xxxxxxxxxxx``, and ``(``. Nor will we want to |
| 703 | split between the ``)`` and the ``:`` at the end. These regions are said to be |
| 704 | "unbreakable." This is reflected in the tree by there not being a "split" |
Bill Wendling | 7d62345 | 2015-03-18 13:36:07 -0700 | [diff] [blame] | 705 | decision (left hand branch) within the unbreakable region. |
| 706 | |
| 707 | Now that we have the tree, we determine what the "best" formatting is by finding |
| 708 | the path through the tree with the lowest cost. |
| 709 | |
| 710 | And that's it! |