| Andrew Grieve | 32bc5e0d | 2020-01-03 19:39:52 | [diff] [blame] | 1 | # Chromium Python Style Guide |
| Peter Wen | dcdb2ec | 2018-11-26 23:00:36 | [diff] [blame] | 2 | |
| 3 | _For other languages, please see the[Chromium style |
| John Palmer | be05130 | 2021-05-19 11:48:35 | [diff] [blame] | 4 | guides](https://chromium.googlesource.com/chromium/src/+/main/styleguide/styleguide.md)._ |
| Peter Wen | dcdb2ec | 2018-11-26 23:00:36 | [diff] [blame] | 5 | |
| zhoupeng | 6ebd49d | 2025-04-03 20:45:00 | [diff] [blame] | 6 | The minimum supportedPython versionis3.9, we recommendusingPython3.11 |
| 7 | (asin, that's what the bots use, so don't assumeorrequire anything older |
| 8 | *or* newer), but most newer versions ofPython3 will work finefor most |
| 9 | things.Thereis an appropriate version ofPython3in |
| 10 | `$depot_tools/python-bin`,if you don't have one already. |
| Dirk Pranke | cc23234 | 2021-05-13 22:20:12 | [diff] [blame] | 11 | |
| 12 | We (often) use a tool called [vpython] to manage Python packages; vpython |
| 13 | is a wrapper around virtualenv. However, it is not safe to use vpython |
| 14 | regardless of context, as it can have performance issues. All tests are |
| Bruce Dawson | 942f9bcd | 2022-08-10 18:40:22 | [diff] [blame] | 15 | run under vpython, so it is safe there, and vpython is the default for |
| 16 | running scripts during PRESUBMIT checks (input_api.python3_executable points to |
| 17 | vpython3 and is used in GetPythonUnitTests), but you should not use vpython |
| 18 | during gclient runhooks, or during the build unless a |
| 19 | [//build/OWNER](../../build/OWNERS) has told you that it is okay to do so. |
| Dirk Pranke | cc23234 | 2021-05-13 22:20:12 | [diff] [blame] | 20 | |
| 21 | Also, there is some performance overhead to using vpython, so prefer not |
| 22 | to use vpython unless you need it (to pick up packages not available in the |
| 23 | source tree). |
| 24 | |
| 25 | "shebang lines" (the first line of many unix scripts, like `#!/bin/sh`) |
| 26 | aren'tas usefulas you might thinkinChromium, because |
| 27 | most ofour python invocations comefrom other tools likeNinjaor |
| 28 | the swarming infrastructure,and they also don't work on Windows. |
| Bruce Dawson | 942f9bcd | 2022-08-10 18:40:22 | [diff] [blame] | 29 | So, don't expect them to help you.That said, a python3 shebangis one way to |
| 30 | indicate to the presubmit system that test scripts should be run underPython3 |
| 31 | rather thanPython2. |
| Dirk Pranke | cc23234 | 2021-05-13 22:20:12 | [diff] [blame] | 32 | |
| 33 | However,if your scriptis executable, you should stilluse one,andfor |
| David Munro | 9980b2c | 2022-02-02 15:30:41 | [diff] [blame] | 34 | Python you shoulduse`#!/usr/bin/env python3`or`#!/usr/bin/env vpython3` |
| Dirk Pranke | cc23234 | 2021-05-13 22:20:12 | [diff] [blame] | 35 | in order to pick up the right version ofPythonfrom your $PATH rather than |
| 36 | assuming you want the versionin`/usr/bin`;this allows you to pick up the |
| 37 | versions we endorsefrom |
| 38 | `depot_tools`. |
| 39 | |
| Andrew Grieve | 32bc5e0d | 2020-01-03 19:39:52 | [diff] [blame] | 40 | Chromium follows[PEP-8](https://www.python.org/dev/peps/pep-0008/). |
| Peter Wen | dcdb2ec | 2018-11-26 23:00:36 | [diff] [blame] | 41 | |
| Andrew Grieve | 32bc5e0d | 2020-01-03 19:39:52 | [diff] [blame] | 42 | Itis also encouraged to follow advicefrom |
| 43 | [Google's Python Style Guide](https://google.github.io/styleguide/pyguide.html), |
| 44 | which is a superset of PEP-8. |
| 45 | |
| 46 | See also: |
| Brian Norris | 13e1fe42 | 2023-08-25 20:26:11 | [diff] [blame] | 47 | * [ChromiumOS Python Style Guide](https://chromium.googlesource.com/chromiumos/docs/+/HEAD/styleguide/python.md) |
| Andrew Grieve | 32bc5e0d | 2020-01-03 19:39:52 | [diff] [blame] | 48 | * [Blink Python Style Guide](blink-python.md) |
| 49 | |
| 50 | [TOC] |
| 51 | |
| 52 | ## Our Previous Python Style |
| 53 | |
| 54 | Chromium used to differ from PEP-8 in the following ways: |
| 55 | * Use two-space indentation instead of four-space indentation. |
| 56 | * Use `CamelCase()` method and function names instead of `unix_hacker_style()` |
| 57 | names. |
| 58 | * 80 character line limits rather than 79. |
| 59 | |
| 60 | New scripts should not follow these deviations, but they should be followed when |
| 61 | making changes to files that follow them. |
| 62 | |
| 63 | ## Making Style Guide Changes |
| Peter Wen | dcdb2ec | 2018-11-26 23:00:36 | [diff] [blame] | 64 | |
| 65 | You can propose changes to this style guide by sending an email to |
| Takuto Ikuta | 8ba9115 | 2023-09-25 13:42:44 | [diff] [blame] | 66 | [`python@chromium.org`]. Ideally, the list will arrive at some consensus and you |
| Peter Wen | dcdb2ec | 2018-11-26 23:00:36 | [diff] [blame] | 67 | can request review for a change to this file. If there'sno consensus, |
| John Palmer | be05130 | 2021-05-19 11:48:35 | [diff] [blame] | 68 | [`//styleguide/python/OWNERS`](https://chromium.googlesource.com/chromium/src/+/main/styleguide/python/OWNERS) |
| Peter Wen | dcdb2ec | 2018-11-26 23:00:36 | [diff] [blame] | 69 | get to decide. |
| 70 | |
| Bruce Dawson | 942f9bcd | 2022-08-10 18:40:22 | [diff] [blame] | 71 | ## Portability |
| 72 | |
| 73 | There are a couple of differencesin how text files are handled onWindows that |
| 74 | can lead to portability problems.These differences are: |
| 75 | |
| 76 | *Thedefault encodingwhen reading/writing text filesis cp1252 onWindowsand |
| 77 | utf-8 onLinux, which can lead toWindows-only test failures.These can be |
| 78 | avoidedby always specifying`encoding='utf-8'`when opening text files. |
| 79 | |
| 80 | *Thedefault behaviorwhen writing text files onWindowsis to emit \r\n |
| 81 | (carriagereturn line feed) line endings.This can lead to crypticWindows-only |
| 82 | test failuresandis generally undesirable.This can be avoidedby always |
| 83 | specifying`newline=''`when opening text filesfor writing. |
| 84 | |
| 85 | Thatis,use these formswhen opening text filesinPython: |
| 86 | |
| 87 | * reading:with open(filename,'r', encoding='utf-8')as f: |
| 88 | * writing:with open(filename,'w', encoding='utf-8', newline='')as f: |
| 89 | |
| Peter Wen | dcdb2ec | 2018-11-26 23:00:36 | [diff] [blame] | 90 | ## Tools |
| 91 | |
| Andrew Grieve | a6dad4a | 2018-11-29 13:57:32 | [diff] [blame] | 92 | ### pylint |
| Peter Wen | dcdb2ec | 2018-11-26 23:00:36 | [diff] [blame] | 93 | [Depot tools](http://commondatastorage.googleapis.com/chrome-infra-docs/flat/depot_tools/docs/html/depot_tools.html) |
| 94 | contains alocal copy of pylint, appropriately configured. |
| Dirk Pranke | cc23234 | 2021-05-13 22:20:12 | [diff] [blame] | 95 | *Directories need to optinto pylint presubmit checks via: |
| Andrew Grieve | a6dad4a | 2018-11-29 13:57:32 | [diff] [blame] | 96 | `input_api.canned_checks.RunPylint()`. |
| 97 | |
| 98 | ### YAPF |
| agrieve | 1a1b9066b | 2018-11-30 15:47:22 | [diff] [blame] | 99 | [YAPF](https://github.com/google/yapf) is the Python formatter used by: |
| Andrew Grieve | a6dad4a | 2018-11-29 13:57:32 | [diff] [blame] | 100 | |
| 101 | ```sh |
| 102 | git cl format --python |
| 103 | ``` |
| 104 | |
| agrieve | 1a1b9066b | 2018-11-30 15:47:22 | [diff] [blame] | 105 | Directories can optinto enforcingauto-formattingby adding a`.style.yapf` |
| 106 | filewith the following contents: |
| Andrew Grieve | a6dad4a | 2018-11-29 13:57:32 | [diff] [blame] | 107 | ``` |
| 108 | [style] |
| Andrew Grieve | 83d4c6a9 | 2020-01-07 16:50:23 | [diff] [blame] | 109 | based_on_style = pep8 |
| Andrew Grieve | a6dad4a | 2018-11-29 13:57:32 | [diff] [blame] | 110 | ``` |
| 111 | |
| 112 | Entire files can be formatted(rather than just touched lines) via: |
| 113 | ```sh |
| 114 | git cl format --python --full |
| agrieve | 1a1b9066b | 2018-11-30 15:47:22 | [diff] [blame] | 115 | ``` |
| 116 | |
| Andrew Grieve | 32bc5e0d | 2020-01-03 19:39:52 | [diff] [blame] | 117 | YAPF has gotchas.You should review its changes before submitting.Notably: |
| 118 | *It doesnot re-wrap comments. |
| 119 | *It won't insert characters in order wrap lines. You might need to add ()s |
| 120 | yourself in order to have to wrap long lines for you. |
| 121 | * It formats lists differently depending on whether or not they end with a |
| 122 | trailing comma. |
| 123 | |
| 124 | |
| agrieve | 1a1b9066b | 2018-11-30 15:47:22 | [diff] [blame] | 125 | #### Bugs |
| 126 | * Are tracked here: https://github.com/google/yapf/issues. |
| Takuto Ikuta | 8ba9115 | 2023-09-25 13:42:44 | [diff] [blame] | 127 | * For Chromium-specific bugs, please discuss on [`python@chromium.org`]. |
| agrieve | 1a1b9066b | 2018-11-30 15:47:22 | [diff] [blame] | 128 | |
| 129 | #### Editor Integration |
| Dirk Pranke | cc23234 | 2021-05-13 22:20:12 | [diff] [blame] | 130 | See: https://github.com/google/yapf/tree/main/plugins |
| 131 | |
| 132 | [vpython]: https://chromium.googlesource.com/infra/infra/+/refs/heads/main/doc/users/vpython.md |
| Takuto Ikuta | 8ba9115 | 2023-09-25 13:42:44 | [diff] [blame] | 133 | [`python@chromium.org`]: https://groups.google.com/a/chromium.org/g/python |
