From a42aef780630bce97c01dbf33a1947ea108e6e29 Mon Sep 17 00:00:00 2001
From: Zsolt Dollenstein <zsol.zsol@gmail.com>
Date: Sat, 31 Mar 2018 22:42:48 +0100
Subject: [PATCH] Describe how string literals are handled (#96)

---
 README.md                              | 11 ++++++++++-
 black.py                               |  7 +++++++
 docs/reference/reference_functions.rst |  2 ++
 3 files changed, 19 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 3ab6887..205163f 100644
--- 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 3d5ea14..3bb83da 100644
--- 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 b521f78..4e7fb83 100644
--- 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
-- 
2.39.2