For other languages, please see the Chromium style guides.
We currently require Python 3.8 (as in, that‘s what the bots use, so don’t assume or require anything older or newer), but most newer versions of Python3 will work fine for most things. There is an appropriate version of Python3 in
$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 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‘t as useful as you might think in Chromium, because most of our python invocations come from other tools like Ninja or the swarming infrastructure, and they also don’t work on Windows. So, don't expect them to help you. That said, a python 3 shebang is one way to indicate to the presubmit system that test scripts should be run under Python 3 rather than Python 2.
However, if your script is executable, you should still use one, and for Python you should use
#!/usr/bin/env python3 or
#!/usr/bin/env vpython3 in order to pick up the right version of Python from your $PATH rather than assuming you want the version in
/usr/bin; this allows you to pick up the versions we endorse from
Chromium follows PEP-8.
It is also encouraged to follow advice from Google's Python Style Guide, which is a superset of PEP-8.
Chromium used to differ from PEP-8 in the following ways:
CamelCase()method and function names instead of
New scripts should not follow these deviations, but they should be followed when making changes to files that follow them.
You can propose changes to this style guide by sending an email to
firstname.lastname@example.org. Ideally, the list will arrive at some consensus and you can request review for a change to this file. If there's no consensus,
//styleguide/python/OWNERS get to decide.
There are a couple of differences in how text files are handled on Windows that can lead to portability problems. These differences are:
The default encoding when reading/writing text files is cp1252 on Windows and utf-8 on Linux, which can lead to Windows-only test failures. These can be avoided by always specifying
encoding='utf-8' when opening text files.
The default behavior when writing text files on Windows is to emit \r\n (carriage return line feed) line endings. This can lead to cryptic Windows-only test failures and is generally undesirable. This can be avoided by always specifying
newline='' when opening text files for writing.
That is, use these forms when opening text files in Python:
Depot tools contains a local copy of pylint, appropriately configured.
YAPF is the Python formatter used by:
git cl format --python
Directories can opt into enforcing auto-formatting by adding a
.style.yapf file with the following contents:
[style] based_on_style = pep8
Entire files can be formatted (rather than just touched lines) via:
git cl format --python --full
YAPF has gotchas. You should review its changes before submitting. Notably: