1==== 2YAPF 3==== 4 5.. image:: https://badge.fury.io/py/yapf.svg 6 :target: https://badge.fury.io/py/yapf 7 :alt: PyPI version 8 9.. image:: https://github.com/google/yapf/actions/workflows/ci.yml/badge.svg 10 :target: https://github.com/google/yapf/actions 11 :alt: Build status 12 13.. image:: https://coveralls.io/repos/google/yapf/badge.svg?branch=main 14 :target: https://coveralls.io/r/google/yapf?branch=main 15 :alt: Coverage status 16 17 18Introduction 19============ 20 21Most of the current formatters for Python --- e.g., autopep8, and pep8ify --- 22are made to remove lint errors from code. This has some obvious limitations. 23For instance, code that conforms to the PEP 8 guidelines may not be 24reformatted. But it doesn't mean that the code looks good. 25 26YAPF takes a different approach. It's based off of `'clang-format' <https://cl 27ang.llvm.org/docs/ClangFormat.html>`_, developed by Daniel Jasper. In essence, 28the algorithm takes the code and reformats it to the best formatting that 29conforms to the style guide, even if the original code didn't violate the 30style guide. The idea is also similar to the `'gofmt' <https://golang.org/cmd/ 31gofmt/>`_ tool for the Go programming language: end all holy wars about 32formatting - if the whole codebase of a project is simply piped through YAPF 33whenever modifications are made, the style remains consistent throughout the 34project and there's no point arguing about style in every code review. 35 36The ultimate goal is that the code YAPF produces is as good as the code that a 37programmer would write if they were following the style guide. It takes away 38some of the drudgery of maintaining your code. 39 40.. footer:: 41 42 YAPF is not an official Google product (experimental or otherwise), it is 43 just code that happens to be owned by Google. 44 45.. contents:: 46 47 48Installation 49============ 50 51To install YAPF from PyPI: 52 53.. code-block:: shell 54 55 $ pip install yapf 56 57(optional) If you are using Python 2.7 and want to enable multiprocessing: 58 59.. code-block:: shell 60 61 $ pip install futures 62 63YAPF is still considered in "alpha" stage, and the released version may change 64often; therefore, the best way to keep up-to-date with the latest development 65is to clone this repository. 66 67Note that if you intend to use YAPF as a command-line tool rather than as a 68library, installation is not necessary. YAPF supports being run as a directory 69by the Python interpreter. If you cloned/unzipped YAPF into ``DIR``, it's 70possible to run: 71 72.. code-block:: shell 73 74 $ PYTHONPATH=DIR python DIR/yapf [options] ... 75 76 77Python versions 78=============== 79 80YAPF supports Python 2.7 and 3.6.4+. (Note that some Python 3 features may fail 81to parse with Python versions before 3.6.4.) 82 83YAPF requires the code it formats to be valid Python for the version YAPF itself 84runs under. Therefore, if you format Python 3 code with YAPF, run YAPF itself 85under Python 3 (and similarly for Python 2). 86 87 88Usage 89===== 90 91Options:: 92 93 usage: yapf [-h] [-v] [-d | -i] [-r | -l START-END] [-e PATTERN] 94 [--style STYLE] [--style-help] [--no-local-style] [-p] 95 [-vv] 96 [files [files ...]] 97 98 Formatter for Python code. 99 100 positional arguments: 101 files 102 103 optional arguments: 104 -h, --help show this help message and exit 105 -v, --version show version number and exit 106 -d, --diff print the diff for the fixed source 107 -i, --in-place make changes to files in place 108 -r, --recursive run recursively over directories 109 -l START-END, --lines START-END 110 range of lines to reformat, one-based 111 -e PATTERN, --exclude PATTERN 112 patterns for files to exclude from formatting 113 --style STYLE specify formatting style: either a style name (for 114 example "pep8" or "google"), or the name of a file 115 with style settings. The default is pep8 unless a 116 .style.yapf or setup.cfg or pyproject.toml file 117 located in the same directory as the source or one of 118 its parent directories (for stdin, the current 119 directory is used). 120 --style-help show style settings and exit; this output can be saved 121 to .style.yapf to make your settings permanent 122 --no-local-style don't search for local style definition 123 -p, --parallel Run yapf in parallel when formatting multiple files. 124 Requires concurrent.futures in Python 2.X 125 -vv, --verbose Print out file names while processing 126 127 128------------ 129Return Codes 130------------ 131 132Normally YAPF returns zero on successful program termination and non-zero otherwise. 133 134If ``--diff`` is supplied, YAPF returns zero when no changes were necessary, non-zero 135otherwise (including program error). You can use this in a CI workflow to test that code 136has been YAPF-formatted. 137 138--------------------------------------------- 139Excluding files from formatting (.yapfignore or pyproject.toml) 140--------------------------------------------- 141 142In addition to exclude patterns provided on commandline, YAPF looks for additional 143patterns specified in a file named ``.yapfignore`` or ``pyproject.toml`` located in the 144working directory from which YAPF is invoked. 145 146``.yapfignore``'s syntax is similar to UNIX's filename pattern matching:: 147 148 * matches everything 149 ? matches any single character 150 [seq] matches any character in seq 151 [!seq] matches any character not in seq 152 153Note that no entry should begin with `./`. 154 155If you use ``pyproject.toml``, exclude patterns are specified by ``ignore_pattens`` key 156in ``[tool.yapfignore]`` section. For example: 157 158.. code-block:: ini 159 160 [tool.yapfignore] 161 ignore_patterns = [ 162 "temp/**/*.py", 163 "temp2/*.py" 164 ] 165 166Formatting style 167================ 168 169The formatting style used by YAPF is configurable and there are many "knobs" 170that can be used to tune how YAPF does formatting. See the ``style.py`` module 171for the full list. 172 173To control the style, run YAPF with the ``--style`` argument. It accepts one of 174the predefined styles (e.g., ``pep8`` or ``google``), a path to a configuration 175file that specifies the desired style, or a dictionary of key/value pairs. 176 177The config file is a simple listing of (case-insensitive) ``key = value`` pairs 178with a ``[style]`` heading. For example: 179 180.. code-block:: ini 181 182 [style] 183 based_on_style = pep8 184 spaces_before_comment = 4 185 split_before_logical_operator = true 186 187The ``based_on_style`` setting determines which of the predefined styles this 188custom style is based on (think of it like subclassing). Four 189styles are predefined: 190 191- ``pep8`` (default) 192- ``google`` (based off of the `Google Python Style Guide`_) 193- ``yapf`` (for use with Google open source projects) 194- ``facebook`` 195 196.. _`Google Python Style Guide`: https://github.com/google/styleguide/blob/gh-pages/pyguide.md 197 198See ``_STYLE_NAME_TO_FACTORY`` in style.py_ for details. 199 200.. _style.py: https://github.com/google/yapf/blob/main/yapf/yapflib/style.py 201 202It's also possible to do the same on the command line with a dictionary. For 203example: 204 205.. code-block:: shell 206 207 --style='{based_on_style: pep8, indent_width: 2}' 208 209This will take the ``pep8`` base style and modify it to have two space 210indentations. 211 212YAPF will search for the formatting style in the following manner: 213 2141. Specified on the command line 2152. In the ``[style]`` section of a ``.style.yapf`` file in either the current 216 directory or one of its parent directories. 2173. In the ``[yapf]`` section of a ``setup.cfg`` file in either the current 218 directory or one of its parent directories. 2194. In the ``[tool.yapf]`` section of a ``pyproject.toml`` file in either the current 220 directory or one of its parent directories. 2215. In the ``[style]`` section of a ``~/.config/yapf/style`` file in your home 222 directory. 223 224If none of those files are found, the default style is used (PEP8). 225 226 227Example 228======= 229 230An example of the type of formatting that YAPF can do, it will take this ugly 231code: 232 233.. code-block:: python 234 235 x = { 'a':37,'b':42, 236 237 'c':927} 238 239 y = 'hello ''world' 240 z = 'hello '+'world' 241 a = 'hello {}'.format('world') 242 class foo ( object ): 243 def f (self ): 244 return 37*-+2 245 def g(self, x,y=42): 246 return y 247 def f ( a ) : 248 return 37+-+a[42-x : y**3] 249 250and reformat it into: 251 252.. code-block:: python 253 254 x = {'a': 37, 'b': 42, 'c': 927} 255 256 y = 'hello ' 'world' 257 z = 'hello ' + 'world' 258 a = 'hello {}'.format('world') 259 260 261 class foo(object): 262 def f(self): 263 return 37 * -+2 264 265 def g(self, x, y=42): 266 return y 267 268 269 def f(a): 270 return 37 + -+a[42 - x:y**3] 271 272 273Example as a module 274=================== 275 276The two main APIs for calling yapf are ``FormatCode`` and ``FormatFile``, these 277share several arguments which are described below: 278 279.. code-block:: python 280 281 >>> from yapf.yapflib.yapf_api import FormatCode # reformat a string of code 282 283 >>> formatted_code, changed = FormatCode("f ( a = 1, b = 2 )") 284 >>> formatted_code 285 'f(a=1, b=2)\n' 286 >>> changed 287 True 288 289A ``style_config`` argument: Either a style name or a path to a file that contains 290formatting style settings. If None is specified, use the default style 291as set in ``style.DEFAULT_STYLE_FACTORY``. 292 293.. code-block:: python 294 295 >>> FormatCode("def g():\n return True", style_config='pep8')[0] 296 'def g():\n return True\n' 297 298A ``lines`` argument: A list of tuples of lines (ints), [start, end], 299that we want to format. The lines are 1-based indexed. It can be used by 300third-party code (e.g., IDEs) when reformatting a snippet of code rather 301than a whole file. 302 303.. code-block:: python 304 305 >>> FormatCode("def g( ):\n a=1\n b = 2\n return a==b", lines=[(1, 1), (2, 3)])[0] 306 'def g():\n a = 1\n b = 2\n return a==b\n' 307 308A ``print_diff`` (bool): Instead of returning the reformatted source, return a 309diff that turns the formatted source into reformatted source. 310 311.. code-block:: python 312 313 >>> print(FormatCode("a==b", filename="foo.py", print_diff=True)[0]) 314 --- foo.py (original) 315 +++ foo.py (reformatted) 316 @@ -1 +1 @@ 317 -a==b 318 +a == b 319 320Note: the ``filename`` argument for ``FormatCode`` is what is inserted into 321the diff, the default is ``<unknown>``. 322 323``FormatFile`` returns reformatted code from the passed file along with its encoding: 324 325.. code-block:: python 326 327 >>> from yapf.yapflib.yapf_api import FormatFile # reformat a file 328 329 >>> print(open("foo.py").read()) # contents of file 330 a==b 331 332 >>> reformatted_code, encoding, changed = FormatFile("foo.py") 333 >>> formatted_code 334 'a == b\n' 335 >>> encoding 336 'utf-8' 337 >>> changed 338 True 339 340The ``in_place`` argument saves the reformatted code back to the file: 341 342.. code-block:: python 343 344 >>> FormatFile("foo.py", in_place=True)[:2] 345 (None, 'utf-8') 346 347 >>> print(open("foo.py").read()) # contents of file (now fixed) 348 a == b 349 350Formatting diffs 351================ 352 353Options:: 354 355 usage: yapf-diff [-h] [-i] [-p NUM] [--regex PATTERN] [--iregex PATTERN][-v] 356 [--style STYLE] [--binary BINARY] 357 358 This script reads input from a unified diff and reformats all the changed 359 lines. This is useful to reformat all the lines touched by a specific patch. 360 Example usage for git/svn users: 361 362 git diff -U0 --no-color --relative HEAD^ | yapf-diff -i 363 svn diff --diff-cmd=diff -x-U0 | yapf-diff -p0 -i 364 365 It should be noted that the filename contained in the diff is used 366 unmodified to determine the source file to update. Users calling this script 367 directly should be careful to ensure that the path in the diff is correct 368 relative to the current working directory. 369 370 optional arguments: 371 -h, --help show this help message and exit 372 -i, --in-place apply edits to files instead of displaying a diff 373 -p NUM, --prefix NUM strip the smallest prefix containing P slashes 374 --regex PATTERN custom pattern selecting file paths to reformat 375 (case sensitive, overrides -iregex) 376 --iregex PATTERN custom pattern selecting file paths to reformat 377 (case insensitive, overridden by -regex) 378 -v, --verbose be more verbose, ineffective without -i 379 --style STYLE specify formatting style: either a style name (for 380 example "pep8" or "google"), or the name of a file 381 with style settings. The default is pep8 unless a 382 .style.yapf or setup.cfg or pyproject.toml file 383 located in the same directory as the source or one of 384 its parent directories (for stdin, the current 385 directory is used). 386 --binary BINARY location of binary to use for yapf 387 388Knobs 389===== 390 391``ALIGN_CLOSING_BRACKET_WITH_VISUAL_INDENT`` 392 Align closing bracket with visual indentation. 393 394``ALLOW_MULTILINE_LAMBDAS`` 395 Allow lambdas to be formatted on more than one line. 396 397``ALLOW_MULTILINE_DICTIONARY_KEYS`` 398 Allow dictionary keys to exist on multiple lines. For example: 399 400 .. code-block:: python 401 402 x = { 403 ('this is the first element of a tuple', 404 'this is the second element of a tuple'): 405 value, 406 } 407 408``ALLOW_SPLIT_BEFORE_DEFAULT_OR_NAMED_ASSIGNS`` 409 Allow splitting before a default / named assignment in an argument list. 410 411``ALLOW_SPLIT_BEFORE_DICT_VALUE`` 412 Allow splits before the dictionary value. 413 414``ARITHMETIC_PRECEDENCE_INDICATION`` 415 Let spacing indicate operator precedence. For example: 416 417 .. code-block:: python 418 419 a = 1 * 2 + 3 / 4 420 b = 1 / 2 - 3 * 4 421 c = (1 + 2) * (3 - 4) 422 d = (1 - 2) / (3 + 4) 423 e = 1 * 2 - 3 424 f = 1 + 2 + 3 + 4 425 426 will be formatted as follows to indicate precedence: 427 428 .. code-block:: python 429 430 a = 1*2 + 3/4 431 b = 1/2 - 3*4 432 c = (1+2) * (3-4) 433 d = (1-2) / (3+4) 434 e = 1*2 - 3 435 f = 1 + 2 + 3 + 4 436 437``BLANK_LINE_BEFORE_NESTED_CLASS_OR_DEF`` 438 Insert a blank line before a ``def`` or ``class`` immediately nested within 439 another ``def`` or ``class``. For example: 440 441 .. code-block:: python 442 443 class Foo: 444 # <------ this blank line 445 def method(): 446 pass 447 448``BLANK_LINE_BEFORE_MODULE_DOCSTRING`` 449 Insert a blank line before a module docstring. 450 451``BLANK_LINE_BEFORE_CLASS_DOCSTRING`` 452 Insert a blank line before a class-level docstring. 453 454``BLANK_LINES_AROUND_TOP_LEVEL_DEFINITION`` 455 Sets the number of desired blank lines surrounding top-level function and 456 class definitions. For example: 457 458 .. code-block:: python 459 460 class Foo: 461 pass 462 # <------ having two blank lines here 463 # <------ is the default setting 464 class Bar: 465 pass 466 467``BLANK_LINES_BETWEEN_TOP_LEVEL_IMPORTS_AND_VARIABLES`` 468 Sets the number of desired blank lines between top-level imports and 469 variable definitions. Useful for compatibility with tools like isort. 470 471``COALESCE_BRACKETS`` 472 Do not split consecutive brackets. Only relevant when 473 ``DEDENT_CLOSING_BRACKETS`` or ``INDENT_CLOSING_BRACKETS`` 474 is set. For example: 475 476 .. code-block:: python 477 478 call_func_that_takes_a_dict( 479 { 480 'key1': 'value1', 481 'key2': 'value2', 482 } 483 ) 484 485 would reformat to: 486 487 .. code-block:: python 488 489 call_func_that_takes_a_dict({ 490 'key1': 'value1', 491 'key2': 'value2', 492 }) 493 494 495``COLUMN_LIMIT`` 496 The column limit (or max line-length) 497 498``CONTINUATION_ALIGN_STYLE`` 499 The style for continuation alignment. Possible values are: 500 501 - ``SPACE``: Use spaces for continuation alignment. This is default 502 behavior. 503 - ``FIXED``: Use fixed number (CONTINUATION_INDENT_WIDTH) of columns 504 (ie: CONTINUATION_INDENT_WIDTH/INDENT_WIDTH tabs or CONTINUATION_INDENT_WIDTH 505 spaces) for continuation alignment. 506 - ``VALIGN-RIGHT``: Vertically align continuation lines to multiple of 507 INDENT_WIDTH columns. Slightly right (one tab or a few spaces) if cannot 508 vertically align continuation lines with indent characters. 509 510``CONTINUATION_INDENT_WIDTH`` 511 Indent width used for line continuations. 512 513``DEDENT_CLOSING_BRACKETS`` 514 Put closing brackets on a separate line, dedented, if the bracketed 515 expression can't fit in a single line. Applies to all kinds of brackets, 516 including function definitions and calls. For example: 517 518 .. code-block:: python 519 520 config = { 521 'key1': 'value1', 522 'key2': 'value2', 523 } # <--- this bracket is dedented and on a separate line 524 525 time_series = self.remote_client.query_entity_counters( 526 entity='dev3246.region1', 527 key='dns.query_latency_tcp', 528 transform=Transformation.AVERAGE(window=timedelta(seconds=60)), 529 start_ts=now()-timedelta(days=3), 530 end_ts=now(), 531 ) # <--- this bracket is dedented and on a separate line 532 533``DISABLE_ENDING_COMMA_HEURISTIC`` 534 Disable the heuristic which places each list element on a separate line if 535 the list is comma-terminated. 536 537``EACH_DICT_ENTRY_ON_SEPARATE_LINE`` 538 Place each dictionary entry onto its own line. 539 540``FORCE_MULTILINE_DICT`` 541 Respect EACH_DICT_ENTRY_ON_SEPARATE_LINE even if the line is shorter than 542 COLUMN_LIMIT. 543 544``I18N_COMMENT`` 545 The regex for an internationalization comment. The presence of this comment 546 stops reformatting of that line, because the comments are required to be 547 next to the string they translate. 548 549``I18N_FUNCTION_CALL`` 550 The internationalization function call names. The presence of this function 551 stops reformatting on that line, because the string it has cannot be moved 552 away from the i18n comment. 553 554``INDENT_DICTIONARY_VALUE`` 555 Indent the dictionary value if it cannot fit on the same line as the 556 dictionary key. For example: 557 558 .. code-block:: python 559 560 config = { 561 'key1': 562 'value1', 563 'key2': value1 + 564 value2, 565 } 566 567``INDENT_WIDTH`` 568 The number of columns to use for indentation. 569 570``INDENT_BLANK_LINES`` 571 Set to ``True`` to prefer indented blank lines rather than empty 572 573``INDENT_CLOSING_BRACKETS`` 574 Put closing brackets on a separate line, indented, if the bracketed 575 expression can't fit in a single line. Applies to all kinds of brackets, 576 including function definitions and calls. For example: 577 578 .. code-block:: python 579 580 config = { 581 'key1': 'value1', 582 'key2': 'value2', 583 } # <--- this bracket is indented and on a separate line 584 585 time_series = self.remote_client.query_entity_counters( 586 entity='dev3246.region1', 587 key='dns.query_latency_tcp', 588 transform=Transformation.AVERAGE(window=timedelta(seconds=60)), 589 start_ts=now()-timedelta(days=3), 590 end_ts=now(), 591 ) # <--- this bracket is indented and on a separate line 592 593``JOIN_MULTIPLE_LINES`` 594 Join short lines into one line. E.g., single line ``if`` statements. 595 596``NO_SPACES_AROUND_SELECTED_BINARY_OPERATORS`` 597 Do not include spaces around selected binary operators. For example: 598 599 .. code-block:: python 600 601 1 + 2 * 3 - 4 / 5 602 603 will be formatted as follows when configured with ``*``, ``/``: 604 605 .. code-block:: python 606 607 1 + 2*3 - 4/5 608 609``SPACES_AROUND_POWER_OPERATOR`` 610 Set to ``True`` to prefer using spaces around ``**``. 611 612``SPACES_AROUND_DEFAULT_OR_NAMED_ASSIGN`` 613 Set to ``True`` to prefer spaces around the assignment operator for default 614 or keyword arguments. 615 616``SPACES_AROUND_DICT_DELIMITERS`` 617 Adds a space after the opening '{' and before the ending '}' dict delimiters. 618 619 .. code-block:: python 620 621 {1: 2} 622 623 will be formatted as: 624 625 .. code-block:: python 626 627 { 1: 2 } 628 629``SPACES_AROUND_LIST_DELIMITERS`` 630 Adds a space after the opening '[' and before the ending ']' list delimiters. 631 632 .. code-block:: python 633 634 [1, 2] 635 636 will be formatted as: 637 638 .. code-block:: python 639 640 [ 1, 2 ] 641 642``SPACES_AROUND_SUBSCRIPT_COLON`` 643 Use spaces around the subscript / slice operator. For example: 644 645 .. code-block:: python 646 647 my_list[1 : 10 : 2] 648 649``SPACES_AROUND_TUPLE_DELIMITERS`` 650 Adds a space after the opening '(' and before the ending ')' tuple delimiters. 651 652 .. code-block:: python 653 654 (1, 2, 3) 655 656 will be formatted as: 657 658 .. code-block:: python 659 660 ( 1, 2, 3 ) 661 662``SPACES_BEFORE_COMMENT`` 663 The number of spaces required before a trailing comment. 664 This can be a single value (representing the number of spaces 665 before each trailing comment) or list of of values (representing 666 alignment column values; trailing comments within a block will 667 be aligned to the first column value that is greater than the maximum 668 line length within the block). For example: 669 670 With ``spaces_before_comment=5``: 671 672 .. code-block:: python 673 674 1 + 1 # Adding values 675 676 will be formatted as: 677 678 .. code-block:: python 679 680 1 + 1 # Adding values <-- 5 spaces between the end of the statement and comment 681 682 With ``spaces_before_comment=15, 20``: 683 684 .. code-block:: python 685 686 1 + 1 # Adding values 687 two + two # More adding 688 689 longer_statement # This is a longer statement 690 short # This is a shorter statement 691 692 a_very_long_statement_that_extends_beyond_the_final_column # Comment 693 short # This is a shorter statement 694 695 will be formatted as: 696 697 .. code-block:: python 698 699 1 + 1 # Adding values <-- end of line comments in block aligned to col 15 700 two + two # More adding 701 702 longer_statement # This is a longer statement <-- end of line comments in block aligned to col 20 703 short # This is a shorter statement 704 705 a_very_long_statement_that_extends_beyond_the_final_column # Comment <-- the end of line comments are aligned based on the line length 706 short # This is a shorter statement 707 708``SPACE_BETWEEN_ENDING_COMMA_AND_CLOSING_BRACKET`` 709 Insert a space between the ending comma and closing bracket of a list, etc. 710 711``SPACE_INSIDE_BRACKETS`` 712 Use spaces inside brackets, braces, and parentheses. For example: 713 714 .. code-block:: python 715 716 method_call( 1 ) 717 my_dict[ 3 ][ 1 ][ get_index( *args, **kwargs ) ] 718 my_set = { 1, 2, 3 } 719 720``SPLIT_ARGUMENTS_WHEN_COMMA_TERMINATED`` 721 Split before arguments if the argument list is terminated by a comma. 722 723``SPLIT_ALL_COMMA_SEPARATED_VALUES`` 724 If a comma separated list (``dict``, ``list``, ``tuple``, or function 725 ``def``) is on a line that is too long, split such that each element 726 is on a separate line. 727 728``SPLIT_ALL_TOP_LEVEL_COMMA_SEPARATED_VALUES`` 729 Variation on ``SPLIT_ALL_COMMA_SEPARATED_VALUES`` in which, if a 730 subexpression with a comma fits in its starting line, then the 731 subexpression is not split. This avoids splits like the one for 732 ``b`` in this code: 733 734 .. code-block:: python 735 736 abcdef( 737 aReallyLongThing: int, 738 b: [Int, 739 Int]) 740 741 With the new knob this is split as: 742 743 .. code-block:: python 744 745 abcdef( 746 aReallyLongThing: int, 747 b: [Int, Int]) 748 749``SPLIT_BEFORE_BITWISE_OPERATOR`` 750 Set to ``True`` to prefer splitting before ``&``, ``|`` or ``^`` rather 751 than after. 752 753``SPLIT_BEFORE_ARITHMETIC_OPERATOR`` 754 Set to ``True`` to prefer splitting before ``+``, ``-``, ``*``, ``/``, ``//``, 755 or ``@`` rather than after. 756 757``SPLIT_BEFORE_CLOSING_BRACKET`` 758 Split before the closing bracket if a ``list`` or ``dict`` literal doesn't 759 fit on a single line. 760 761``SPLIT_BEFORE_DICT_SET_GENERATOR`` 762 Split before a dictionary or set generator (comp_for). For example, note 763 the split before the ``for``: 764 765 .. code-block:: python 766 767 foo = { 768 variable: 'Hello world, have a nice day!' 769 for variable in bar if variable != 42 770 } 771 772``SPLIT_BEFORE_DOT`` 773 Split before the ``.`` if we need to split a longer expression: 774 775 .. code-block:: python 776 777 foo = ('This is a really long string: {}, {}, {}, {}'.format(a, b, c, d)) 778 779 would reformat to something like: 780 781 .. code-block:: python 782 783 foo = ('This is a really long string: {}, {}, {}, {}' 784 .format(a, b, c, d)) 785 786``SPLIT_BEFORE_EXPRESSION_AFTER_OPENING_PAREN`` 787 Split after the opening paren which surrounds an expression if it doesn't 788 fit on a single line. 789 790``SPLIT_BEFORE_FIRST_ARGUMENT`` 791 If an argument / parameter list is going to be split, then split before the 792 first argument. 793 794``SPLIT_BEFORE_LOGICAL_OPERATOR`` 795 Set to ``True`` to prefer splitting before ``and`` or ``or`` rather than 796 after. 797 798``SPLIT_BEFORE_NAMED_ASSIGNS`` 799 Split named assignments onto individual lines. 800 801``SPLIT_COMPLEX_COMPREHENSION`` 802 For list comprehensions and generator expressions with multiple clauses 803 (e.g multiple ``for`` calls, ``if`` filter expressions) and which need to 804 be reflowed, split each clause onto its own line. For example: 805 806 .. code-block:: python 807 808 result = [ 809 a_var + b_var for a_var in xrange(1000) for b_var in xrange(1000) 810 if a_var % b_var] 811 812 would reformat to something like: 813 814 .. code-block:: python 815 816 result = [ 817 a_var + b_var 818 for a_var in xrange(1000) 819 for b_var in xrange(1000) 820 if a_var % b_var] 821 822``SPLIT_PENALTY_AFTER_OPENING_BRACKET`` 823 The penalty for splitting right after the opening bracket. 824 825``SPLIT_PENALTY_AFTER_UNARY_OPERATOR`` 826 The penalty for splitting the line after a unary operator. 827 828``SPLIT_PENALTY_ARITHMETIC_OPERATOR`` 829 The penalty of splitting the line around the ``+``, ``-``, ``*``, ``/``, 830 ``//``, ``%``, and ``@`` operators. 831 832``SPLIT_PENALTY_BEFORE_IF_EXPR`` 833 The penalty for splitting right before an ``if`` expression. 834 835``SPLIT_PENALTY_BITWISE_OPERATOR`` 836 The penalty of splitting the line around the ``&``, ``|``, and ``^`` 837 operators. 838 839``SPLIT_PENALTY_COMPREHENSION`` 840 The penalty for splitting a list comprehension or generator expression. 841 842``SPLIT_PENALTY_EXCESS_CHARACTER`` 843 The penalty for characters over the column limit. 844 845``SPLIT_PENALTY_FOR_ADDED_LINE_SPLIT`` 846 The penalty incurred by adding a line split to the logical line. The more 847 line splits added the higher the penalty. 848 849``SPLIT_PENALTY_IMPORT_NAMES`` 850 The penalty of splitting a list of ``import as`` names. For example: 851 852 .. code-block:: python 853 854 from a_very_long_or_indented_module_name_yada_yad import (long_argument_1, 855 long_argument_2, 856 long_argument_3) 857 858 would reformat to something like: 859 860 .. code-block:: python 861 862 from a_very_long_or_indented_module_name_yada_yad import ( 863 long_argument_1, long_argument_2, long_argument_3) 864 865``SPLIT_PENALTY_LOGICAL_OPERATOR`` 866 The penalty of splitting the line around the ``and`` and ``or`` operators. 867 868``USE_TABS`` 869 Use the Tab character for indentation. 870 871(Potentially) Frequently Asked Questions 872======================================== 873 874-------------------------------------------- 875Why does YAPF destroy my awesome formatting? 876-------------------------------------------- 877 878YAPF tries very hard to get the formatting correct. But for some code, it won't 879be as good as hand-formatting. In particular, large data literals may become 880horribly disfigured under YAPF. 881 882The reasons for this are manyfold. In short, YAPF is simply a tool to help 883with development. It will format things to coincide with the style guide, but 884that may not equate with readability. 885 886What can be done to alleviate this situation is to indicate regions YAPF should 887ignore when reformatting something: 888 889.. code-block:: python 890 891 # yapf: disable 892 FOO = { 893 # ... some very large, complex data literal. 894 } 895 896 BAR = [ 897 # ... another large data literal. 898 ] 899 # yapf: enable 900 901You can also disable formatting for a single literal like this: 902 903.. code-block:: python 904 905 BAZ = { 906 (1, 2, 3, 4), 907 (5, 6, 7, 8), 908 (9, 10, 11, 12), 909 } # yapf: disable 910 911To preserve the nice dedented closing brackets, use the 912``dedent_closing_brackets`` in your style. Note that in this case all 913brackets, including function definitions and calls, are going to use 914that style. This provides consistency across the formatted codebase. 915 916------------------------------- 917Why Not Improve Existing Tools? 918------------------------------- 919 920We wanted to use clang-format's reformatting algorithm. It's very powerful and 921designed to come up with the best formatting possible. Existing tools were 922created with different goals in mind, and would require extensive modifications 923to convert to using clang-format's algorithm. 924 925----------------------------- 926Can I Use YAPF In My Program? 927----------------------------- 928 929Please do! YAPF was designed to be used as a library as well as a command line 930tool. This means that a tool or IDE plugin is free to use YAPF. 931 932----------------------------------------- 933I still get non Pep8 compliant code! Why? 934----------------------------------------- 935 936YAPF tries very hard to be fully PEP 8 compliant. However, it is paramount 937to not risk altering the semantics of your code. Thus, YAPF tries to be as 938safe as possible and does not change the token stream 939(e.g., by adding parentheses). 940All these cases however, can be easily fixed manually. For instance, 941 942.. code-block:: python 943 944 from my_package import my_function_1, my_function_2, my_function_3, my_function_4, my_function_5 945 946 FOO = my_variable_1 + my_variable_2 + my_variable_3 + my_variable_4 + my_variable_5 + my_variable_6 + my_variable_7 + my_variable_8 947 948won't be split, but you can easily get it right by just adding parentheses: 949 950.. code-block:: python 951 952 from my_package import (my_function_1, my_function_2, my_function_3, 953 my_function_4, my_function_5) 954 955 FOO = (my_variable_1 + my_variable_2 + my_variable_3 + my_variable_4 + 956 my_variable_5 + my_variable_6 + my_variable_7 + my_variable_8) 957 958Gory Details 959============ 960 961---------------- 962Algorithm Design 963---------------- 964 965The main data structure in YAPF is the ``LogicalLine`` object. It holds a list 966of ``FormatToken``\s, that we would want to place on a single line if there 967were no column limit. An exception being a comment in the middle of an 968expression statement will force the line to be formatted on more than one line. 969The formatter works on one ``LogicalLine`` object at a time. 970 971An ``LogicalLine`` typically won't affect the formatting of lines before or 972after it. There is a part of the algorithm that may join two or more 973``LogicalLine``\s into one line. For instance, an if-then statement with a 974short body can be placed on a single line: 975 976.. code-block:: python 977 978 if a == 42: continue 979 980YAPF's formatting algorithm creates a weighted tree that acts as the solution 981space for the algorithm. Each node in the tree represents the result of a 982formatting decision --- i.e., whether to split or not to split before a token. 983Each formatting decision has a cost associated with it. Therefore, the cost is 984realized on the edge between two nodes. (In reality, the weighted tree doesn't 985have separate edge objects, so the cost resides on the nodes themselves.) 986 987For example, take the following Python code snippet. For the sake of this 988example, assume that line (1) violates the column limit restriction and needs to 989be reformatted. 990 991.. code-block:: python 992 993 def xxxxxxxxxxx(aaaaaaaaaaaa, bbbbbbbbb, cccccccc, dddddddd, eeeeee): # 1 994 pass # 2 995 996For line (1), the algorithm will build a tree where each node (a 997``FormattingDecisionState`` object) is the state of the line at that token given 998the decision to split before the token or not. Note: the ``FormatDecisionState`` 999objects are copied by value so each node in the graph is unique and a change in 1000one doesn't affect other nodes. 1001 1002Heuristics are used to determine the costs of splitting or not splitting. 1003Because a node holds the state of the tree up to a token's insertion, it can 1004easily determine if a splitting decision will violate one of the style 1005requirements. For instance, the heuristic is able to apply an extra penalty to 1006the edge when not splitting between the previous token and the one being added. 1007 1008There are some instances where we will never want to split the line, because 1009doing so will always be detrimental (i.e., it will require a backslash-newline, 1010which is very rarely desirable). For line (1), we will never want to split the 1011first three tokens: ``def``, ``xxxxxxxxxxx``, and ``(``. Nor will we want to 1012split between the ``)`` and the ``:`` at the end. These regions are said to be 1013"unbreakable." This is reflected in the tree by there not being a "split" 1014decision (left hand branch) within the unbreakable region. 1015 1016Now that we have the tree, we determine what the "best" formatting is by finding 1017the path through the tree with the lowest cost. 1018 1019And that's it! 1020
