Pragmatism

Early versions of Black used to be absolutist in some respects. They took after its initial author. This was fine at the time as it made the implementation simpler and there were not many users anyway. Not many edge cases were reported. As a mature tool, Black does make some exceptions to rules it otherwise holds. This section documents what those exceptions are and why this is the case.

The magic trailing comma

Black in general does not take existing formatting into account.

However, there are cases where you put a short collection or function call in your code but you anticipate it will grow in the future.

For example:

TRANSLATIONS = {
    "en_us": "English (US)",
    "pl_pl": "polski",
}

Early versions of Black used to ruthlessly collapse those into one line (it fits!). Now, you can communicate that you don’t want that by putting a trailing comma in the collection yourself. When you do, Black will know to always explode your collection into one item per line.

How do you make it stop? Just delete that trailing comma and Black will collapse your collection into one line if it fits.

r”strings” and R”strings”

Black normalizes string quotes as well as string prefixes, making them lowercase. One exception to this rule is r-strings. It turns out that the very popular MagicPython syntax highlighter, used by default by (among others) GitHub and Visual Studio Code, differentiates between r-strings and R-strings. The former are syntax highlighted as regular expressions while the latter are treated as true raw strings with no special semantics.