{"id":13398332,"url":"https://github.com/google/yapf","last_synced_at":"2025-05-12T18:26:55.394Z","repository":{"id":28950477,"uuid":"32476524","full_name":"google/yapf","owner":"google","description":"A formatter for Python files","archived":false,"fork":false,"pushed_at":"2025-04-28T05:03:22.000Z","size":2681,"stargazers_count":13883,"open_issues_count":413,"forks_count":898,"subscribers_count":204,"default_branch":"main","last_synced_at":"2025-05-05T15:54:07.890Z","etag":null,"topics":["formatter","google","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/google.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":"AUTHORS","dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2015-03-18T18:22:31.000Z","updated_at":"2025-05-04T23:42:11.000Z","dependencies_parsed_at":"2023-11-19T11:06:22.986Z","dependency_job_id":"b3d83a72-de26-41a3-8682-4b8e155ff462","html_url":"https://github.com/google/yapf","commit_stats":{"total_commits":1133,"total_committers":165,"mean_commits":6.866666666666666,"dds":0.4271844660194175,"last_synced_commit":"be725578eb6d93dd4a36f1aadbdfb73f86c9861e"},"previous_names":[],"tags_count":71,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fyapf","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fyapf/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fyapf/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/google%2Fyapf/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/google","download_url":"https://codeload.github.com/google/yapf/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253796970,"owners_count":21965813,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["formatter","google","python"],"created_at":"2024-07-30T19:00:23.020Z","updated_at":"2025-05-12T18:26:55.375Z","avatar_url":"https://github.com/google.png","language":"Python","readme":"# YAPF\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"https://badge.fury.io/py/yapf\"\u003e\u003cimg alt=\"PyPI Version\" src=\"https://badge.fury.io/py/yapf.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/google/yapf/actions/workflows/ci.yml\"\u003e\u003cimg alt=\"Build Status\" src=\"https://github.com/google/yapf/actions/workflows/ci.yml/badge.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://github.com/google/yapf/actions/workflows/pre-commit.yml\"\u003e\u003cimg alt=\"Actions Status\" src=\"https://github.com/google/yapf/actions/workflows/pre-commit.yml/badge.svg\"\u003e\u003c/a\u003e\n\u003ca href=\"https://coveralls.io/github/google/yapf?branch=main\"\u003e\u003cimg alt=\"Coverage Status\" src=\"https://coveralls.io/repos/github/google/yapf/badge.svg?branch=main\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\n## Introduction\n\nYAPF is a Python formatter based on [`clang-format`](https://clang.llvm.org/docs/ClangFormat.html)\n(developed by Daniel Jasper). In essence, the algorithm takes the code and\ncalculates the best formatting that conforms to the configured style. It takes\naway a lot of the drudgery of maintaining your code.\n\nThe ultimate goal is that the code YAPF produces is as good as the code that a\nprogrammer would write if they were following the style guide.\n\n\u003e **Note**\n\u003e YAPF is not an official Google product (experimental or otherwise), it is\n\u003e just code that happens to be owned by Google.\n\n\n## Installation\n\nTo install YAPF from PyPI:\n\n```bash\n$ pip install yapf\n```\n\nYAPF is still considered in \"beta\" stage, and the released version may change\noften; therefore, the best way to keep up-to-date with the latest development\nis to clone this repository or install directly from github:\n\n```bash\n$ pip install git+https://github.com/google/yapf.git\n```\n\nNote that if you intend to use YAPF as a command-line tool rather than as a\nlibrary, installation is not necessary. YAPF supports being run as a directory\nby the Python interpreter. If you cloned/unzipped YAPF into `DIR`, it's\npossible to run:\n\n```bash\n$ PYTHONPATH=DIR python DIR/yapf [options] ...\n```\n\n## Using YAPF within your favorite editor\nYAPF is supported by multiple editors via community extensions or plugins. See [Editor Support](EDITOR%20SUPPORT.md) for more info.\n\n## Required Python versions\n\nYAPF supports Python 3.7+.\n\n\n## Usage\n\n```console\nusage: yapf [-h] [-v] [-d | -i | -q] [-r | -l START-END] [-e PATTERN]\n            [--style STYLE] [--style-help] [--no-local-style] [-p] [-m] [-vv]\n            [files ...]\n\nFormatter for Python code.\n\npositional arguments:\n  files                 reads from stdin when no files are specified.\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -v, --version         show program's version number and exit\n  -d, --diff            print the diff for the fixed source\n  -i, --in-place        make changes to files in place\n  -q, --quiet           output nothing and set return value\n  -r, --recursive       run recursively over directories\n  -l START-END, --lines START-END\n                        range of lines to reformat, one-based\n  -e PATTERN, --exclude PATTERN\n                        patterns for files to exclude from formatting\n  --style STYLE         specify formatting style: either a style name (for\n                        example \"pep8\" or \"google\"), or the name of a file\n                        with style settings. The default is pep8 unless a\n                        .style.yapf or setup.cfg or pyproject.toml file\n                        located in the same directory as the source or one of\n                        its parent directories (for stdin, the current\n                        directory is used).\n  --style-help          show style settings and exit; this output can be saved\n                        to .style.yapf to make your settings permanent\n  --no-local-style      don't search for local style definition\n  -p, --parallel        run YAPF in parallel when formatting multiple files.\n  -m, --print-modified  print out file names of modified files\n  -vv, --verbose        print out file names while processing\n```\n\n\n### Return Codes\n\nNormally YAPF returns zero on successful program termination and non-zero\notherwise.\n\nIf `--diff` is supplied, YAPF returns zero when no changes were necessary,\nnon-zero otherwise (including program error). You can use this in a CI workflow\nto test that code has been YAPF-formatted.\n\n### Excluding files from formatting (.yapfignore or pyproject.toml)\n\nIn addition to exclude patterns provided on commandline, YAPF looks for\nadditional patterns specified in a file named `.yapfignore` or `pyproject.toml`\nlocated in the working directory from which YAPF is invoked.\n\n`.yapfignore`'s syntax is similar to UNIX's filename pattern matching:\n\n```\n*       matches everything\n?       matches any single character\n[seq]   matches any character in seq\n[!seq]  matches any character not in seq\n```\n\nNote that no entry should begin with `./`.\n\nIf you use `pyproject.toml`, exclude patterns are specified by `ignore_patterns` key\nin `[tool.yapfignore]` section. For example:\n\n```ini\n[tool.yapfignore]\nignore_patterns = [\n  \"temp/**/*.py\",\n  \"temp2/*.py\"\n]\n```\n\n\nFormatting style\n================\n\nThe formatting style used by YAPF is configurable and there are many \"knobs\"\nthat can be used to tune how YAPF does formatting. See the `style.py` module\nfor the full list.\n\nTo control the style, run YAPF with the `--style` argument. It accepts one of\nthe predefined styles (e.g., `pep8` or `google`), a path to a configuration\nfile that specifies the desired style, or a dictionary of key/value pairs.\n\nThe config file is a simple listing of (case-insensitive) `key = value` pairs\nwith a `[style]` heading. For example:\n\n```ini\n[style]\nbased_on_style = pep8\nspaces_before_comment = 4\nsplit_before_logical_operator = true\n```\n\nThe `based_on_style` setting determines which of the predefined styles this\ncustom style is based on (think of it like subclassing). Four\nstyles are predefined:\n\n- `pep8` (default)\n- `google` (based off of the [Google Python Style Guide](https://github.com/google/styleguide/blob/gh-pages/pyguide.md))\n- `yapf` (for use with Google open source projects)\n- `facebook`\n\nSee `_STYLE_NAME_TO_FACTORY` in [`style.py`](https://github.com/google/yapf/blob/main/yapf/yapflib/style.py) for details.\n\nIt's also possible to do the same on the command line with a dictionary. For\nexample:\n\n```bash\n--style='{based_on_style: pep8, indent_width: 2}'\n```\n\nThis will take the `pep8` base style and modify it to have two space\nindentations.\n\nYAPF will search for the formatting style in the following manner:\n\n1. Specified on the command line\n2. In the `[style]` section of a `.style.yapf` file in either the current\n   directory or one of its parent directories.\n3. In the `[yapf]` section of a `setup.cfg` file in either the current\n   directory or one of its parent directories.\n4. In the `[tool.yapf]` section of a `pyproject.toml` file in either the current\n   directory or one of its parent directories.\n5. In the `[style]` section of a `~/.config/yapf/style` file in your home\n   directory.\n\nIf none of those files are found, the default style PEP8 is used.\n\n\nExample\n=======\n\nAn example of the type of formatting that YAPF can do, it will take this ugly\ncode:\n\n```python\nx = {  'a':37,'b':42,\n\n'c':927}\n\ny = 'hello ''world'\nz = 'hello '+'world'\na = 'hello {}'.format('world')\nclass foo  (     object  ):\n  def f    (self   ):\n    return       37*-+2\n  def g(self, x,y=42):\n      return y\ndef f  (   a ) :\n  return      37+-+a[42-x :  y**3]\n```\n\nand reformat it into:\n\n```python\nx = {'a': 37, 'b': 42, 'c': 927}\n\ny = 'hello ' 'world'\nz = 'hello ' + 'world'\na = 'hello {}'.format('world')\n\n\nclass foo(object):\n    def f(self):\n        return 37 * -+2\n\n    def g(self, x, y=42):\n        return y\n\n\ndef f(a):\n    return 37 + -+a[42 - x:y**3]\n```\n\n\n## Example as a module\n\nThe two main APIs for calling YAPF are `FormatCode` and `FormatFile`, these\nshare several arguments which are described below:\n\n```python\n\u003e\u003e\u003e from yapf.yapflib.yapf_api import FormatCode  # reformat a string of code\n\n\u003e\u003e\u003e formatted_code, changed = FormatCode(\"f ( a = 1, b = 2 )\")\n\u003e\u003e\u003e formatted_code\n'f(a=1, b=2)\\n'\n\u003e\u003e\u003e changed\nTrue\n```\n\nA `style_config` argument: Either a style name or a path to a file that\ncontains formatting style settings. If None is specified, use the default style\nas set in `style.DEFAULT_STYLE_FACTORY`.\n\n```python\n\u003e\u003e\u003e FormatCode(\"def g():\\n  return True\", style_config='pep8')[0]\n'def g():\\n    return True\\n'\n```\n\nA `lines` argument: A list of tuples of lines (ints), [start, end], that we\nwant to format. The lines are 1-based indexed. It can be used by third-party\ncode (e.g., IDEs) when reformatting a snippet of code rather than a whole file.\n\n```python\n\u003e\u003e\u003e FormatCode(\"def g( ):\\n    a=1\\n    b = 2\\n    return a==b\", lines=[(1, 1), (2, 3)])[0]\n'def g():\\n    a = 1\\n    b = 2\\n    return a==b\\n'\n```\n\nA `print_diff` (bool): Instead of returning the reformatted source, return a\ndiff that turns the formatted source into reformatted source.\n\n```diff\n\u003e\u003e\u003e print(FormatCode(\"a==b\", filename=\"foo.py\", print_diff=True)[0])\n--- foo.py (original)\n+++ foo.py (reformatted)\n@@ -1 +1 @@\n-a==b\n+a == b\n```\n\nNote: the `filename` argument for `FormatCode` is what is inserted into the\ndiff, the default is `\u003cunknown\u003e`.\n\n`FormatFile` returns reformatted code from the passed file along with its encoding:\n\n```python\n\u003e\u003e\u003e from yapf.yapflib.yapf_api import FormatFile  # reformat a file\n\n\u003e\u003e\u003e print(open(\"foo.py\").read())  # contents of file\na==b\n\n\u003e\u003e\u003e reformatted_code, encoding, changed = FormatFile(\"foo.py\")\n\u003e\u003e\u003e formatted_code\n'a == b\\n'\n\u003e\u003e\u003e encoding\n'utf-8'\n\u003e\u003e\u003e changed\nTrue\n```\n\nThe `in_place` argument saves the reformatted code back to the file:\n\n```python\n\u003e\u003e\u003e FormatFile(\"foo.py\", in_place=True)[:2]\n(None, 'utf-8')\n\n\u003e\u003e\u003e print(open(\"foo.py\").read())  # contents of file (now fixed)\na == b\n```\n\n\n## Formatting diffs\n\nOptions:\n\n```console\nusage: yapf-diff [-h] [-i] [-p NUM] [--regex PATTERN] [--iregex PATTERN][-v]\n                 [--style STYLE] [--binary BINARY]\n\nThis script reads input from a unified diff and reformats all the changed\nlines. This is useful to reformat all the lines touched by a specific patch.\nExample usage for git/svn users:\n\n  git diff -U0 --no-color --relative HEAD^ | yapf-diff -i\n  svn diff --diff-cmd=diff -x-U0 | yapf-diff -p0 -i\n\nIt should be noted that the filename contained in the diff is used\nunmodified to determine the source file to update. Users calling this script\ndirectly should be careful to ensure that the path in the diff is correct\nrelative to the current working directory.\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -i, --in-place        apply edits to files instead of displaying a diff\n  -p NUM, --prefix NUM  strip the smallest prefix containing P slashes\n  --regex PATTERN       custom pattern selecting file paths to reformat\n                        (case sensitive, overrides -iregex)\n  --iregex PATTERN      custom pattern selecting file paths to reformat\n                        (case insensitive, overridden by -regex)\n  -v, --verbose         be more verbose, ineffective without -i\n  --style STYLE         specify formatting style: either a style name (for\n                        example \"pep8\" or \"google\"), or the name of a file\n                        with style settings. The default is pep8 unless a\n                        .style.yapf or setup.cfg or pyproject.toml file\n                        located in the same directory as the source or one of\n                        its parent directories (for stdin, the current\n                        directory is used).\n  --binary BINARY       location of binary to use for YAPF\n```\n\n## Python features not yet supported\n* Python 3.12 – [PEP 695 – Type Parameter Syntax](https://peps.python.org/pep-0695/) – [YAPF #1170](https://github.com/google/yapf/issues/1170)\n* Python 3.12 – [PEP 701 – Syntactic formalization of f-strings](https://peps.python.org/pep-0701/) – [YAPF #1136](https://github.com/google/yapf/issues/1136)\n\n## Knobs\n\n#### `ALIGN_CLOSING_BRACKET_WITH_VISUAL_INDENT`\n\n\u003e    Align closing bracket with visual indentation.\n\n#### `ALLOW_MULTILINE_LAMBDAS`\n\n\u003e    Allow lambdas to be formatted on more than one line.\n\n#### `ALLOW_MULTILINE_DICTIONARY_KEYS`\n\n\u003e    Allow dictionary keys to exist on multiple lines. For example:\n\n```python\n    x = {\n        ('this is the first element of a tuple',\n         'this is the second element of a tuple'):\n             value,\n    }\n```\n\n#### `ALLOW_SPLIT_BEFORE_DEFAULT_OR_NAMED_ASSIGNS`\n\n\u003e    Allow splitting before a default / named assignment in an argument list.\n\n#### `ALLOW_SPLIT_BEFORE_DICT_VALUE`\n\n\u003e    Allow splits before the dictionary value.\n\n#### `ARITHMETIC_PRECEDENCE_INDICATION`\n\n\u003e    Let spacing indicate operator precedence. For example:\n\n```python\n    a = 1 * 2 + 3 / 4\n    b = 1 / 2 - 3 * 4\n    c = (1 + 2) * (3 - 4)\n    d = (1 - 2) / (3 + 4)\n    e = 1 * 2 - 3\n    f = 1 + 2 + 3 + 4\n```\n\n\u003e    will be formatted as follows to indicate precedence:\n\n```python\n    a = 1*2 + 3/4\n    b = 1/2 - 3*4\n    c = (1+2) * (3-4)\n    d = (1-2) / (3+4)\n    e = 1*2 - 3\n    f = 1 + 2 + 3 + 4\n```\n\n#### `BLANK_LINES_AROUND_TOP_LEVEL_DEFINITION`\n\n\u003e    Sets the number of desired blank lines surrounding top-level function and\n\u003e    class definitions. For example:\n\n```python\n    class Foo:\n        pass\n                       # \u003c------ having two blank lines here\n                       # \u003c------ is the default setting\n    class Bar:\n        pass\n```\n\n#### `BLANK_LINE_BEFORE_CLASS_DOCSTRING`\n\n\u003e    Insert a blank line before a class-level docstring.\n\n#### `BLANK_LINE_BEFORE_MODULE_DOCSTRING`\n\n\u003e    Insert a blank line before a module docstring.\n\n#### `BLANK_LINE_BEFORE_NESTED_CLASS_OR_DEF`\n\n\u003e    Insert a blank line before a `def` or `class` immediately nested within\n\u003e    another `def` or `class`. For example:\n\n```python\n    class Foo:\n                       # \u003c------ this blank line\n        def method():\n            pass\n```\n\n#### `BLANK_LINES_BETWEEN_TOP_LEVEL_IMPORTS_AND_VARIABLES`\n\n\u003e    Sets the number of desired blank lines between top-level imports and\n\u003e    variable definitions. Useful for compatibility with tools like isort.\n\n#### `COALESCE_BRACKETS`\n\n\u003e    Do not split consecutive brackets. Only relevant when\n\u003e    `DEDENT_CLOSING_BRACKETS` or `INDENT_CLOSING_BRACKETS` is set. For example:\n\n```python\n    call_func_that_takes_a_dict(\n        {\n            'key1': 'value1',\n            'key2': 'value2',\n        }\n    )\n```\n\n\u003e    would reformat to:\n\n```python\n    call_func_that_takes_a_dict({\n        'key1': 'value1',\n        'key2': 'value2',\n    })\n```\n\n#### `COLUMN_LIMIT`\n\n\u003e    The column limit (or max line-length)\n\n#### `CONTINUATION_ALIGN_STYLE`\n\n\u003e    The style for continuation alignment. Possible values are:\n\n\u003e    - `SPACE`: Use spaces for continuation alignment. This is default\n\u003e      behavior.\n\u003e    - `FIXED`: Use fixed number (`CONTINUATION_INDENT_WIDTH`) of columns\n\u003e      (i.e. `CONTINUATION_INDENT_WIDTH`/`INDENT_WIDTH` tabs or\n\u003e      `CONTINUATION_INDENT_WIDTH` spaces) for continuation alignment.\n\u003e    - `VALIGN-RIGHT`: Vertically align continuation lines to multiple of\n\u003e      `INDENT_WIDTH` columns. Slightly right (one tab or a few spaces) if cannot\n\u003e      vertically align continuation lines with indent characters.\n\n#### `CONTINUATION_INDENT_WIDTH`\n\n\u003e    Indent width used for line continuations.\n\n#### `DEDENT_CLOSING_BRACKETS`\n\n\u003e    Put closing brackets on a separate line, dedented, if the bracketed\n\u003e    expression can't fit in a single line. Applies to all kinds of brackets,\n\u003e    including function definitions and calls. For example:\n\n```python\n    config = {\n        'key1': 'value1',\n        'key2': 'value2',\n    }  # \u003c--- this bracket is dedented and on a separate line\n\n    time_series = self.remote_client.query_entity_counters(\n        entity='dev3246.region1',\n        key='dns.query_latency_tcp',\n        transform=Transformation.AVERAGE(window=timedelta(seconds=60)),\n        start_ts=now()-timedelta(days=3),\n        end_ts=now(),\n    )  # \u003c--- this bracket is dedented and on a separate line\n```\n\n#### `DISABLE_ENDING_COMMA_HEURISTIC`\n\n\u003e    Disable the heuristic which places each list element on a separate line if\n\u003e    the list is comma-terminated.\n\u003e\n\u003e    Note: The behavior of this flag changed in v0.40.3.  Before, if this flag\n\u003e    was true, we would split lists that contained a trailing comma or a\n\u003e    comment.  Now, we have a separate flag, `DISABLE_SPLIT_LIST_WITH_COMMENT`,\n\u003e    that controls splitting when a list contains a comment.  To get the old\n\u003e    behavior, set both flags to true.  More information in\n\u003e    [CHANGELOG.md](CHANGELOG.md#new-disable_split_list_with_comment-flag).\n\n#### `DISABLE_SPLIT_LIST_WITH_COMMENT`\n\n\u003e    Don't put every element on a new line within a list that contains\n\u003e    interstitial comments.\n\u003e\n\u003e    Without this flag (default):\n\u003e\n\u003e    ```\n\u003e    [\n\u003e      a,\n\u003e      b,  #\n\u003e      c\n\u003e    ]\n\u003e    ```\n\u003e\n\u003e    With this flag:\n\u003e\n\u003e    ```\n\u003e    [\n\u003e      a, b,  #\n\u003e      c\n\u003e    ]\n\u003e    ```\n\u003e\n\u003e    This mirrors the behavior of clang-format and is useful for forming\n\u003e    \"logical groups\" of elements in a list.  It also works in function\n\u003e    declarations.\n\n#### `EACH_DICT_ENTRY_ON_SEPARATE_LINE`\n\n\u003e    Place each dictionary entry onto its own line.\n\n#### `FORCE_MULTILINE_DICT`\n\n\u003e    Respect `EACH_DICT_ENTRY_ON_SEPARATE_LINE` even if the line is shorter than\n\u003e    `COLUMN_LIMIT`.\n\n#### `I18N_COMMENT`\n\n\u003e    The regex for an internationalization comment. The presence of this comment\n\u003e    stops reformatting of that line, because the comments are required to be\n\u003e    next to the string they translate.\n\n#### `I18N_FUNCTION_CALL`\n\n\u003e    The internationalization function call names. The presence of this function\n\u003e    stops reformatting on that line, because the string it has cannot be moved\n\u003e    away from the i18n comment.\n\n#### `INDENT_BLANK_LINES`\n\n\u003e    Set to `True` to prefer indented blank lines rather than empty\n\n#### `INDENT_CLOSING_BRACKETS`\n\n\u003e    Put closing brackets on a separate line, indented, if the bracketed\n\u003e    expression can't fit in a single line. Applies to all kinds of brackets,\n\u003e    including function definitions and calls. For example:\n\n```python\n    config = {\n        'key1': 'value1',\n        'key2': 'value2',\n        }  # \u003c--- this bracket is indented and on a separate line\n\n    time_series = self.remote_client.query_entity_counters(\n        entity='dev3246.region1',\n        key='dns.query_latency_tcp',\n        transform=Transformation.AVERAGE(window=timedelta(seconds=60)),\n        start_ts=now()-timedelta(days=3),\n        end_ts=now(),\n        )  # \u003c--- this bracket is indented and on a separate line\n```\n\n#### `INDENT_DICTIONARY_VALUE`\n\n\u003e    Indent the dictionary value if it cannot fit on the same line as the\n\u003e    dictionary key. For example:\n\n```python\n    config = {\n        'key1':\n            'value1',\n        'key2': value1 +\n                value2,\n    }\n```\n\n#### `INDENT_WIDTH`\n\n\u003e    The number of columns to use for indentation.\n\n#### `JOIN_MULTIPLE_LINES`\n\n\u003e    Join short lines into one line. E.g., single line `if` statements.\n\n#### `NO_SPACES_AROUND_SELECTED_BINARY_OPERATORS`\n\n\u003e    Do not include spaces around selected binary operators. For example:\n\n```python\n    1 + 2 * 3 - 4 / 5\n```\n\n\u003e    will be formatted as follows when configured with `*`, `/`:\n\n```python\n    1 + 2*3 - 4/5\n```\n\n#### `SPACE_BETWEEN_ENDING_COMMA_AND_CLOSING_BRACKET`\n\n\u003e    Insert a space between the ending comma and closing bracket of a list, etc.\n\n#### `SPACE_INSIDE_BRACKETS`\n\n    Use spaces inside brackets, braces, and parentheses.  For example:\n\n```python\n        method_call( 1 )\n        my_dict[ 3 ][ 1 ][ get_index( *args, **kwargs ) ]\n        my_set = { 1, 2, 3 }\n```\n\n#### `SPACES_AROUND_DEFAULT_OR_NAMED_ASSIGN`\n\n\u003e    Set to `True` to prefer spaces around the assignment operator for default\n\u003e    or keyword arguments.\n\n#### `SPACES_AROUND_DICT_DELIMITERS`\n\n\u003e    Adds a space after the opening '{' and before the ending '}' dict delimiters.\n\n```python\n        {1: 2}\n```\n\n\u003e    will be formatted as:\n\n```python\n        { 1: 2 }\n```\n\n#### `SPACES_AROUND_LIST_DELIMITERS`\n\n\u003e    Adds a space after the opening '[' and before the ending ']' list delimiters.\n\n```python\n    [1, 2]\n```\n\n\u003e    will be formatted as:\n\n```python\n    [ 1, 2 ]\n```\n\n#### `SPACES_AROUND_POWER_OPERATOR`\n\n\u003e    Set to `True` to prefer using spaces around `**`.\n\n#### `SPACES_AROUND_SUBSCRIPT_COLON`\n\n\u003e    Use spaces around the subscript / slice operator.  For example:\n\n```python\n    my_list[1 : 10 : 2]\n```\n\n##### `SPACES_AROUND_TUPLE_DELIMITERS`\n\n\u003e    Adds a space after the opening '(' and before the ending ')' tuple delimiters.\n\n```python\n    (1, 2, 3)\n```\n\n\u003e    will be formatted as:\n\n```python\n    ( 1, 2, 3 )\n```\n\n#### `SPACES_BEFORE_COMMENT`\n\n\u003e    The number of spaces required before a trailing comment.\n\u003e    This can be a single value (representing the number of spaces\n\u003e    before each trailing comment) or list of values (representing\n\u003e    alignment column values; trailing comments within a block will\n\u003e    be aligned to the first column value that is greater than the maximum\n\u003e    line length within the block).\n\n\u003e **Note:** Lists of values may need to be quoted in some contexts\n\u003e (eg. shells or editor config files).\n\n\u003e    For example, with `spaces_before_comment=5`:\n\n```python\n    1 + 1 # Adding values\n```\n\n\u003e    will be formatted as:\n\n```python\n    1 + 1     # Adding values \u003c-- 5 spaces between the end of the statement and comment\n```\n\n\u003e    with `spaces_before_comment=\"15, 20\"`:\n\n```python\n    1 + 1 # Adding values\n    two + two # More adding\n\n    longer_statement # This is a longer statement\n    short # This is a shorter statement\n\n    a_very_long_statement_that_extends_beyond_the_final_column # Comment\n    short # This is a shorter statement\n```\n\n\u003e    will be formatted as:\n\n```python\n    1 + 1          # Adding values \u003c-- end of line comments in block aligned to col 15\n    two + two      # More adding\n\n    longer_statement    # This is a longer statement \u003c-- end of line comments in block aligned to col 20\n    short               # This is a shorter statement\n\n    a_very_long_statement_that_extends_beyond_the_final_column  # Comment \u003c-- the end of line comments are aligned based on the line length\n    short                                                       # This is a shorter statement\n```\n\n#### `SPLIT_ALL_COMMA_SEPARATED_VALUES`\n\n\u003e    If a comma separated list (`dict`, `list`, `tuple`, or function `def`) is\n\u003e    on a line that is too long, split such that each element is on a separate\n\u003e    line.\n\n#### `SPLIT_ALL_TOP_LEVEL_COMMA_SEPARATED_VALUES`\n\n\u003e    Variation on `SPLIT_ALL_COMMA_SEPARATED_VALUES` in which, if a\n\u003e    subexpression with a comma fits in its starting line, then the\n\u003e    subexpression is not split. This avoids splits like the one for\n\u003e    `b` in this code:\n\n```python\n    abcdef(\n        aReallyLongThing: int,\n        b: [Int,\n            Int])\n```\n\n\u003e    with the new knob this is split as:\n\n```python\n    abcdef(\n        aReallyLongThing: int,\n        b: [Int, Int])\n```\n\n#### `SPLIT_ARGUMENTS_WHEN_COMMA_TERMINATED`\n\n\u003e    Split before arguments if the argument list is terminated by a comma.\n\n#### `SPLIT_BEFORE_ARITHMETIC_OPERATOR`\n\n\u003e    Set to `True` to prefer splitting before `+`, `-`, `*`, `/`, `//`, or `@`\n\u003e    rather than after.\n\n#### `SPLIT_BEFORE_BITWISE_OPERATOR`\n\n\u003e    Set to `True` to prefer splitting before `\u0026`, `|` or `^` rather than after.\n\n#### `SPLIT_BEFORE_CLOSING_BRACKET`\n\n\u003e    Split before the closing bracket if a `list` or `dict` literal doesn't fit\n\u003e    on a single line.\n\n#### `SPLIT_BEFORE_DICT_SET_GENERATOR`\n\n\u003e    Split before a dictionary or set generator (`comp_for`). For example, note\n\u003e    the split before the `for`:\n\n```python\n    foo = {\n        variable: 'Hello world, have a nice day!'\n        for variable in bar if variable != 42\n    }\n```\n\n#### `SPLIT_BEFORE_DOT`\n\n\u003e    Split before the `.` if we need to split a longer expression:\n\n```python\n    foo = ('This is a really long string: {}, {}, {}, {}'.format(a, b, c, d))\n```\n\n\u003e    would reformat to something like:\n\n```python\n    foo = ('This is a really long string: {}, {}, {}, {}'\n           .format(a, b, c, d))\n```\n\n#### `SPLIT_BEFORE_EXPRESSION_AFTER_OPENING_PAREN`\n\n\u003e    Split after the opening paren which surrounds an expression if it doesn't\n\u003e    fit on a single line.\n\n#### `SPLIT_BEFORE_FIRST_ARGUMENT`\n\n\u003e    If an argument / parameter list is going to be split, then split before the\n\u003e    first argument.\n\n#### `SPLIT_BEFORE_LOGICAL_OPERATOR`\n\n\u003e    Set to `True` to prefer splitting before `and` or `or` rather than after.\n\n#### `SPLIT_BEFORE_NAMED_ASSIGNS`\n\n\u003e    Split named assignments onto individual lines.\n\n#### `SPLIT_COMPLEX_COMPREHENSION`\n\n\u003e    For list comprehensions and generator expressions with multiple clauses\n\u003e    (e.g multiple `for` calls, `if` filter expressions) and which need to be\n\u003e    reflowed, split each clause onto its own line. For example:\n\n```python\n    result = [\n        a_var + b_var for a_var in xrange(1000) for b_var in xrange(1000)\n        if a_var % b_var]\n```\n\n\u003e    would reformat to something like:\n\n```python\n    result = [\n        a_var + b_var\n        for a_var in xrange(1000)\n        for b_var in xrange(1000)\n        if a_var % b_var]\n```\n\n#### `SPLIT_PENALTY_AFTER_OPENING_BRACKET`\n\n\u003e    The penalty for splitting right after the opening bracket.\n\n#### `SPLIT_PENALTY_AFTER_UNARY_OPERATOR`\n\n\u003e    The penalty for splitting the line after a unary operator.\n\n#### `SPLIT_PENALTY_ARITHMETIC_OPERATOR`\n\n\u003e    The penalty of splitting the line around the `+`, `-`, `*`, `/`, `//`, `%`,\n\u003e    and `@` operators.\n\n#### `SPLIT_PENALTY_BEFORE_IF_EXPR`\n\n\u003e    The penalty for splitting right before an `if` expression.\n\n#### `SPLIT_PENALTY_BITWISE_OPERATOR`\n\n\u003e    The penalty of splitting the line around the `\u0026`, `|`, and `^` operators.\n\n#### `SPLIT_PENALTY_COMPREHENSION`\n\n\u003e    The penalty for splitting a list comprehension or generator expression.\n\n#### `SPLIT_PENALTY_EXCESS_CHARACTER`\n\n\u003e    The penalty for characters over the column limit.\n\n#### `SPLIT_PENALTY_FOR_ADDED_LINE_SPLIT`\n\n\u003e    The penalty incurred by adding a line split to the logical line. The more\n\u003e    line splits added the higher the penalty.\n\n#### `SPLIT_PENALTY_IMPORT_NAMES`\n\n\u003e    The penalty of splitting a list of `import as` names. For example:\n\n```python\n    from a_very_long_or_indented_module_name_yada_yad import (long_argument_1,\n                                                              long_argument_2,\n                                                              long_argument_3)\n```\n\n\u003e    would reformat to something like:\n\n```python\n    from a_very_long_or_indented_module_name_yada_yad import (\n        long_argument_1, long_argument_2, long_argument_3)\n```\n\n#### `SPLIT_PENALTY_LOGICAL_OPERATOR`\n\n\u003e    The penalty of splitting the line around the `and` and `or` operators.\n\n#### `USE_TABS`\n\n\u003e    Use the Tab character for indentation.\n\n\n## (Potentially) Frequently Asked Questions\n\n### Why does YAPF destroy my awesome formatting?\n\nYAPF tries very hard to get the formatting correct. But for some code, it won't\nbe as good as hand-formatting. In particular, large data literals may become\nhorribly disfigured under YAPF.\n\nThe reasons for this are manyfold. In short, YAPF is simply a tool to help\nwith development. It will format things to coincide with the style guide, but\nthat may not equate with readability.\n\nWhat can be done to alleviate this situation is to indicate regions YAPF should\nignore when reformatting something:\n\n```python\n# yapf: disable\nFOO = {\n    # ... some very large, complex data literal.\n}\n\nBAR = [\n    # ... another large data literal.\n]\n# yapf: enable\n```\n\nYou can also disable formatting for a single literal like this:\n\n```python\nBAZ = {\n    (1, 2, 3, 4),\n    (5, 6, 7, 8),\n    (9, 10, 11, 12),\n}  # yapf: disable\n```\n\nTo preserve the nice dedented closing brackets, use the\n`dedent_closing_brackets` in your style. Note that in this case all\nbrackets, including function definitions and calls, are going to use\nthat style.  This provides consistency across the formatted codebase.\n\n### Why Not Improve Existing Tools?\n\nWe wanted to use clang-format's reformatting algorithm. It's very powerful and\ndesigned to come up with the best formatting possible. Existing tools were\ncreated with different goals in mind, and would require extensive modifications\nto convert to using clang-format's algorithm.\n\n### Can I Use YAPF In My Program?\n\nPlease do! YAPF was designed to be used as a library as well as a command line\ntool. This means that a tool or IDE plugin is free to use YAPF.\n\n### I still get non-PEP8 compliant code! Why?\n\nYAPF tries very hard to be fully PEP 8 compliant. However, it is paramount\nto not risk altering the semantics of your code. Thus, YAPF tries to be as\nsafe as possible and does not change the token stream\n(e.g., by adding parentheses).\nAll these cases however, can be easily fixed manually. For instance,\n\n```python\nfrom my_package import my_function_1, my_function_2, my_function_3, my_function_4, my_function_5\n\nFOO = my_variable_1 + my_variable_2 + my_variable_3 + my_variable_4 + my_variable_5 + my_variable_6 + my_variable_7 + my_variable_8\n```\n\nwon't be split, but you can easily get it right by just adding parentheses:\n\n```python\nfrom my_package import (my_function_1, my_function_2, my_function_3,\n                        my_function_4, my_function_5)\n\nFOO = (my_variable_1 + my_variable_2 + my_variable_3 + my_variable_4 +\n       my_variable_5 + my_variable_6 + my_variable_7 + my_variable_8)\n```\n\n\n## Gory Details\n\n### Algorithm Design\n\nThe main data structure in YAPF is the `LogicalLine` object. It holds a list\nof `FormatToken`\\s, that we would want to place on a single line if there\nwere no column limit. An exception being a comment in the middle of an\nexpression statement will force the line to be formatted on more than one line.\nThe formatter works on one `LogicalLine` object at a time.\n\nAn `LogicalLine` typically won't affect the formatting of lines before or\nafter it. There is a part of the algorithm that may join two or more\n`LogicalLine`\\s into one line. For instance, an if-then statement with a\nshort body can be placed on a single line:\n\n```python\nif a == 42: continue\n```\n\nYAPF's formatting algorithm creates a weighted tree that acts as the solution\nspace for the algorithm. Each node in the tree represents the result of a\nformatting decision --- i.e., whether to split or not to split before a token.\nEach formatting decision has a cost associated with it. Therefore, the cost is\nrealized on the edge between two nodes. (In reality, the weighted tree doesn't\nhave separate edge objects, so the cost resides on the nodes themselves.)\n\nFor example, take the following Python code snippet. For the sake of this\nexample, assume that line (1) violates the column limit restriction and needs to\nbe reformatted.\n\n```python\ndef xxxxxxxxxxx(aaaaaaaaaaaa, bbbbbbbbb, cccccccc, dddddddd, eeeeee):  # 1\n    pass                                                               # 2\n```\n\nFor line (1), the algorithm will build a tree where each node (a\n`FormattingDecisionState` object) is the state of the line at that token given\nthe decision to split before the token or not. Note: the `FormatDecisionState`\nobjects are copied by value so each node in the graph is unique and a change in\none doesn't affect other nodes.\n\nHeuristics are used to determine the costs of splitting or not splitting.\nBecause a node holds the state of the tree up to a token's insertion, it can\neasily determine if a splitting decision will violate one of the style\nrequirements. For instance, the heuristic is able to apply an extra penalty to\nthe edge when not splitting between the previous token and the one being added.\n\nThere are some instances where we will never want to split the line, because\ndoing so will always be detrimental (i.e., it will require a backslash-newline,\nwhich is very rarely desirable). For line (1), we will never want to split the\nfirst three tokens: `def`, `xxxxxxxxxxx`, and `(`. Nor will we want to\nsplit between the `)` and the `:` at the end. These regions are said to be\n\"unbreakable.\" This is reflected in the tree by there not being a \"split\"\ndecision (left hand branch) within the unbreakable region.\n\nNow that we have the tree, we determine what the \"best\" formatting is by finding\nthe path through the tree with the lowest cost.\n\nAnd that's it!\n","funding_links":[],"categories":["Python","HarmonyOS","资源列表","Code Analysis","Ecosystems","Python (144)","Containers \u0026 Language Extentions \u0026 Linting","代码分析","All-in formatters","Python 程序","代码分析和 Lint 工具","Language Specific","Code Analysis [🔝](#readme)","Programming Languages","Code Formatting","Formatters","Uncategorized","Code Formatters","Python Hacks","Other Useful Stuff"],"sub_categories":["Windows Manager","代码分析和 Lint 工具","Formatter","[Python](https://www.python.org/)","For Python","网络服务_其他","Uncategorized"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle%2Fyapf","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgoogle%2Fyapf","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgoogle%2Fyapf/lists"}