Differences between revisions 6 and 9 (spanning 3 versions)
Revision 6 as of 2021-05-07 15:37:08
Size: 1992
Editor: SimonMarchi
Comment:
Revision 9 as of 2022-03-18 15:53:24
Size: 1970
Editor: SimonMarchi
Comment:
Deletions are marked like this. Additions are marked like this.
Line 9: Line 9:
All Python source files under the `gdb/` directory must be formatted using the tool black, version 21.4b0. This is the latest version at the time of writing, if you notice that a more recent version is available, feel free to submit a patch to format the code with the newest version available (if that causes any differences). We can then update this page to mention the new version. All Python source files under the `gdb/` directory must be formatted using the tool black. Use the latest available black version.
Line 11: Line 11:
A specific version can be installed using the following steps. This example uses a virtual environment to avoid polluting the home or system directories, but obviously if you Know What You Are Doing, you don't need to. If you notice formatting changes unrelated to your changes, then first submit or push an obvious patch that reformats the code using the latest black version. According to their [[https://black.readthedocs.io/en/stable/the_black_code_style/index.html#stability-policy|stability policy]], all versions of a given calendar year will produce the same output. So we can expect some small changes when they release a version after the new year. The spurious changes can also be because someone forgot to run black in a previous patch.

You can install black in a virtual environment to avoid polluting the home or system directories, but obviously if you Know What You Are Doing, you don't need to.
Line 14: Line 16:
$ python3 -m virtualenv env/ $ python3 -m virtualenv env/ # You can skip this to re-use an existing virtual environment
Line 16: Line 18:
(env) $ pip install 'black == 21.4b0'
(env) $ black --version
black, version 21.4b0
(env) $ pip install --upgrade black
Line 21: Line 21:
All you need to do to re-format files is run `black <file/directory>`. Black will re-format any Python file it finds in there. It runs quite fast, so the simplest is to do: All you need to do then to re-format files is run `black <file/directory>`. Black will re-format any Python file it finds in there. It runs quite fast, so the simplest is to do:
Line 24: Line 24:
$ black gdb/ (env) $ black gdb/
Line 31: Line 31:
If you notice that black produces changes unrelated to your patch, it's probably because someone forgot to run it before you. In this case, don't include unrelated hunks in your patch. Push an obvious patch fixing the formatting and rebase your work on top of that.

GDB Python Coding Standards

For everything that is not related to formatting (for that, see the Formatting section below), GDB follows the published Python coding standards in PEP008.

In addition, the guidelines in the Google Python Style Guide are also followed where they do not conflict with PEP008.

Formatting

All Python source files under the gdb/ directory must be formatted using the tool black. Use the latest available black version.

If you notice formatting changes unrelated to your changes, then first submit or push an obvious patch that reformats the code using the latest black version. According to their stability policy, all versions of a given calendar year will produce the same output. So we can expect some small changes when they release a version after the new year. The spurious changes can also be because someone forgot to run black in a previous patch.

You can install black in a virtual environment to avoid polluting the home or system directories, but obviously if you Know What You Are Doing, you don't need to.

$ python3 -m virtualenv env/  # You can skip this to re-use an existing virtual environment
$ source env/bin/activate
(env) $ pip install --upgrade black

All you need to do then to re-format files is run black <file/directory>. Black will re-format any Python file it finds in there. It runs quite fast, so the simplest is to do:

(env) $ black gdb/
All done! ✨ 🍰 ✨
87 files left unchanged.

from the top-level.

GDB-specific exceptions

There are a few exceptions to the published standards. They exist mainly for consistency with the C standards.

  • Use FIXME instead of TODO.

None: Internals GDB-Python-Coding-Standards (last edited 2022-03-18 15:53:24 by SimonMarchi)

All content (C) 2008 Free Software Foundation. For terms of use, redistribution, and modification, please see the WikiLicense page.