| # Chromium Python Style Guide |
| |
| _For other languages, please see the[Chromium style |
| guides](https://chromium.googlesource.com/chromium/src/+/main/styleguide/styleguide.md)._ |
| |
| The minimum supportedPython versionis3.9, we recommendusingPython3.11 |
| (asin, that's what the bots use, so don't assumeorrequire anything older |
| *or* newer), but most newer versions ofPython3 will work finefor most |
| things.Thereis an appropriate version ofPython3in |
| `$depot_tools/python-bin`,if you don't have one already. |
| |
| We (often) use a tool called [vpython] to manage Python packages; vpython |
| is a wrapper around virtualenv. However, it is not safe to use vpython |
| regardless of context, as it can have performance issues. All tests are |
| run under vpython, so it is safe there, and vpython is the default for |
| running scripts during PRESUBMIT checks (input_api.python3_executable points to |
| vpython3 and is used in GetPythonUnitTests), but you should not use vpython |
| during gclient runhooks, or during the build unless a |
| [//build/OWNER](../../build/OWNERS) has told you that it is okay to do so. |
| |
| Also, there is some performance overhead to using vpython, so prefer not |
| to use vpython unless you need it (to pick up packages not available in the |
| source tree). |
| |
| "shebang lines" (the first line of many unix scripts, like `#!/bin/sh`) |
| aren'tas usefulas you might thinkinChromium, because |
| most ofour python invocations comefrom other tools likeNinjaor |
| the swarming infrastructure,and they also don't work on Windows. |
| So, don't expect them to help you.That said, a python3 shebangis one way to |
| indicate to the presubmit system that test scripts should be run underPython3 |
| rather thanPython2. |
| |
| However,if your scriptis executable, you should stilluse one,andfor |
| Python you shoulduse`#!/usr/bin/env python3`or`#!/usr/bin/env vpython3` |
| in order to pick up the right version ofPythonfrom your $PATH rather than |
| assuming you want the versionin`/usr/bin`;this allows you to pick up the |
| versions we endorsefrom |
| `depot_tools`. |
| |
| Chromium follows[PEP-8](https://www.python.org/dev/peps/pep-0008/). |
| |
| Itis also encouraged to follow advicefrom |
| [Google's Python Style Guide](https://google.github.io/styleguide/pyguide.html), |
| which is a superset of PEP-8. |
| |
| See also: |
| * [ChromiumOS Python Style Guide](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/styleguide/python.md) |
| * [Blink Python Style Guide](blink-python.md) |
| |
| [TOC] |
| |
| ## Our Previous Python Style |
| |
| Chromium used to differ from PEP-8 in the following ways: |
| * Use two-space indentation instead of four-space indentation. |
| * Use `CamelCase()` method and function names instead of `unix_hacker_style()` |
| names. |
| * 80 character line limits rather than 79. |
| |
| New scripts should not follow these deviations, but they should be followed when |
| making changes to files that follow them. |
| |
| ## Making Style Guide Changes |
| |
| You can propose changes to this style guide by sending an email to |
| [`python@chromium.org`]. Ideally, the list will arrive at some consensus and you |
| can request review for a change to this file. If there'sno consensus, |
| [`//styleguide/python/OWNERS`](https://chromium.googlesource.com/chromium/src/+/main/styleguide/python/OWNERS) |
| get to decide. |
| |
| ## Portability |
| |
| There are a couple of differencesin how text files are handled onWindows that |
| can lead to portability problems.These differences are: |
| |
| *Thedefault encodingwhen reading/writing text filesis cp1252 onWindowsand |
| utf-8 onLinux, which can lead toWindows-only test failures.These can be |
| avoidedby always specifying`encoding='utf-8'`when opening text files. |
| |
| *Thedefault behaviorwhen writing text files onWindowsis to emit \r\n |
| (carriagereturn line feed) line endings.This can lead to crypticWindows-only |
| test failuresandis generally undesirable.This can be avoidedby always |
| specifying`newline=''`when opening text filesfor writing. |
| |
| Thatis,use these formswhen opening text filesinPython: |
| |
| * reading:with open(filename,'r', encoding='utf-8')as f: |
| * writing:with open(filename,'w', encoding='utf-8', newline='')as f: |
| |
| ## Tools |
| |
| ### pylint |
| [Depot tools](http://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools.html) |
| contains alocal copy of pylint, appropriately configured. |
| *Directories need to optinto pylint presubmit checks via: |
| `input_api.canned_checks.RunPylint()`. |
| |
| ### YAPF |
| [YAPF](https://github.com/google/yapf) is the Python formatter used by: |
| |
| ```sh |
| git cl format --python |
| ``` |
| |
| Directories can optinto enforcingauto-formattingby adding a`.style.yapf` |
| filewith the following contents: |
| ``` |
| [style] |
| based_on_style = pep8 |
| ``` |
| |
| Entire files can be formatted(rather than just touched lines) via: |
| ```sh |
| git cl format --python --full |
| ``` |
| |
| YAPF has gotchas.You should review its changes before submitting.Notably: |
| *It doesnot re-wrap comments. |
| *It won't insert characters in order wrap lines. You might need to add ()s |
| yourself in order to have to wrap long lines for you. |
| * It formats lists differently depending on whether or not they end with a |
| trailing comma. |
| |
| |
| #### Bugs |
| * Are tracked here: https://github.com/google/yapf/issues. |
| * For Chromium-specific bugs, please discuss on [`python@chromium.org`]. |
| |
| #### Editor Integration |
| See: https://github.com/google/yapf/tree/main/plugins |
| |
| [vpython]: https://chromium.googlesource.com/infra/infra/+/refs/heads/main/doc/users/vpython.md |
| [`python@chromium.org`]: https://groups.google.com/a/chromium.org/g/python |
