Describe how string literals are handled (#96)

diff --git a/README.md b/README.md
index 3ab68878c4421598c1330d5b0e1cb61802622f1a..205163f3e158d92cdd6be653fda388980a18c0d2 100644 (file)
--- a/README.md
+++ b/README.md
@@ -159,7 +159,7 @@ def very_important_function(
     debug: bool = False,
 ):
     """Applies `variables` to the `template` and writes to `file`."""
-    with open(file, 'w') as f:
+    with open(file, "w") as f:
         ...
 ```
 
@@ -260,6 +260,15 @@ if you'd like a trailing comma in this situation and *Black* didn't
 recognize it was safe to do so, put it there manually and *Black* will
 keep it.
 
+### Strings
+
+*Black* prefers double quotes (`"` and `"""`), but only if this does not
+result in more escaping. It will remove escape sequences as necessary as
+part of moving to the other type of quote. This applies to all kinds of
+prefixed strings, including *raw-strings* (`r""`), *byte literals* (`b""`),
+and *formatted strings* (`f""`). The approach above strikes a good balance
+between consistency and legibility.
+
 
 ## Editor integration
 

diff --git a/black.py b/black.py
index 3d5ea14736e0c6aca41a75c9cc517130802b5076..3bb83daef28c396cd7670503d7ad21c7d20336c2 100644 (file)
--- a/black.py
+++ b/black.py
@@ -1815,6 +1815,13 @@ def normalize_prefix(leaf: Leaf, *, inside_brackets: bool) -> None:
 
 
 def normalize_string_quotes(leaf: Leaf) -> None:
+    """Prefer double quotes but only if it doesn't cause more escaping.
+
+    Adds or removes backslashes as appropriate. Doesn't parse and fix
+    strings nested in f-strings (yet).
+
+    Note: Mutates its argument.
+    """
     value = leaf.value.lstrip("furbFURB")
     if value[:3] == '"""':
         return

diff --git a/docs/reference/reference_functions.rst b/docs/reference/reference_functions.rst
index b521f789e4a86ffbf791720b145637ef865266fc..4e7fb837222d1d0f477f85c2a2823a9ba0d6d461 100644 (file)
--- a/docs/reference/reference_functions.rst
+++ b/docs/reference/reference_functions.rst
@@ -77,6 +77,8 @@ Utilities
 
 .. autofunction:: black.normalize_prefix
 
+.. autofunction:: black.normalize_string_quotes
+
 .. autofunction:: black.preceding_leaf
 
 .. autofunction:: black.whitespace