Don't omit escaping the second consecutive quote

[etc/vim.git] / README.md

diff --git a/README.md b/README.md
index 205163f3e158d92cdd6be653fda388980a18c0d2..06b732466eb3b305307992f35a23df99cc476956 100644 (file)
--- a/README.md
+++ b/README.md
@@ -53,13 +53,18 @@ black [OPTIONS] [SRC]...
 
 Options:
   -l, --line-length INTEGER   Where to wrap around.  [default: 88]
 
 Options:
   -l, --line-length INTEGER   Where to wrap around.  [default: 88]

-  --check                     Don't write back the files, just return the
+  --check                     Don't write the files back, just return the

                               status.  Return code 0 means nothing would
                               change.  Return code 1 means some files would be
                               reformatted.  Return code 123 means there was an
                               internal error.
                               status.  Return code 0 means nothing would
                               change.  Return code 1 means some files would be
                               reformatted.  Return code 123 means there was an
                               internal error.

+  --diff                      Don't write the files back, just output a diff
+                              for each file on stdout.

   --fast / --safe             If --fast given, skip temporary sanity checks.
                               [default: --safe]
   --fast / --safe             If --fast given, skip temporary sanity checks.
                               [default: --safe]

+  -q, --quiet                 Don't emit non-error messages to stderr. Errors
+                              are still emitted, silence those with
+                              2>/dev/null.

   --version                   Show the version and exit.
   --help                      Show this message and exit.
 ```
   --version                   Show the version and exit.
   --help                      Show this message and exit.
 ```


@@ -262,12 +267,54 @@ keep it.
 
 ### Strings
 
 
 ### 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.
+*Black* prefers double quotes (`"` and `"""`) over single quotes (`'`
+and `'''`).  It will replace the latter with the former as long as it
+does not result in more backslash escapes than before.
+
+The main reason to standardize on a single form of quotes is aesthetics.
+Having one kind of quotes everywhere reduces reader distraction.
+It will also enable a future version of *Black* to merge consecutive
+string literals that ended up on the same line (see
+[#26](https://github.com/ambv/black/issues/26) for details).
+
+Why settle on double quotes?  They anticipate apostrophes in English
+text.  They match the docstring standard described in PEP 257.  An
+empty string in double quotes (`""`) is impossible to confuse with
+a one double-quote regardless of fonts and syntax highlighting used.
+On top of this, double quotes for strings are consistent with C which
+Python interacts a lot with.
+
+On certain keyboard layouts like US English, typing single quotes is
+a bit easier than double quotes.  The latter requires use of the Shift
+key.  My recommendation here is to keep using whatever is faster to type
+and let *Black* handle the transformation.
+
+### Line Breaks & Binary Operators
+
+*Black* will break a line before a binary operator when splitting a block
+of code over multiple lines. This is so that *Black* is compliant with the
+recent changes in the [PEP 8](https://www.python.org/dev/peps/pep-0008/#should-a-line-break-before-or-after-a-binary-operator)
+style guide, which emphasizes that this approach improves readability.
+
+This behaviour may raise ``W503 line break before binary operator`` warnings in
+style guide enforcement tools like Flake8. Since ``W503`` is not PEP 8 compliant,
+you should tell Flake8 to ignore these warnings.
+
+### Parentheses
+
+Some parentheses are optional in the Python grammar.  Any expression can
+be wrapped in a pair of parentheses to form an atom.  There are a few
+interesting cases:
+
+- `if (...):`
+- `while (...):`
+- `for (...) in (...):`
+- `assert (...), (...)`
+- `from X import (...)`
+
+In those cases, parentheses are removed when the entire statement fits
+in one line, or if the inner expression doesn't have any delimiters to
+further split on.  Otherwise, the parentheses are always added.

 
 
 ## Editor integration
 
 
 ## Editor integration


@@ -277,6 +324,36 @@ between consistency and legibility.
 Use [proofit404/blacken](https://github.com/proofit404/blacken).
 
 
 Use [proofit404/blacken](https://github.com/proofit404/blacken).
 
 

+### PyCharm
+
+1. Install `black`.
+
+        $ pip install black
+
+2. Locate your `black` installation folder.
+
+  On MacOS / Linux / BSD:
+
+        $ which black
+        /usr/local/bin/black  # possible location
+
+  On Windows:
+
+        $ where black
+        %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
+
+3. Open External tools in PyCharm with `File -> Settings -> Tools -> External Tools`.
+
+4. Click the + icon to add a new external tool with the following values:
+    - Name: Black
+    - Description: Black is the uncompromising Python code formatter.
+    - Program: <install_location_from_step_2>
+    - Arguments: $FilePath$
+
+5. Format the currently opened file by selecting `Tools -> External Tools -> black`.
+    - Alternatively, you can set a keyboard shortcut by navigating to `Preferences -> Keymap`.
+
+

 ### Vim
 
 Commands and shortcuts:
 ### Vim
 
 Commands and shortcuts:


@@ -337,6 +414,28 @@ affect your use case.
 This can be used for example with PyCharm's [File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).
 
 
 This can be used for example with PyCharm's [File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).
 
 

+## Version control integration
+
+Use [pre-commit](https://pre-commit.com/). Once you [have it
+installed](https://pre-commit.com/#install), add this to the
+`.pre-commit-config.yaml` in your repository:
+```yaml
+repos:
+-   repo: https://github.com/ambv/black
+    rev: stable
+    hooks:
+    - id: black
+      args: [--line-length=88, --safe]
+      python_version: python3.6
+```
+Then run `pre-commit install` and you're ready to go.
+
+`args` in the above config is optional but shows you how you can change
+the line length if you really need to.  If you're already using Python
+3.7, switch the `python_version` accordingly. Finally, `stable` is a tag
+that is pinned to the latest release on PyPI.  If you'd rather run on
+master, this is also an option.
+

 ## Testimonials
 
 **Dusty Phillips**, [writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips):
 ## Testimonials
 
 **Dusty Phillips**, [writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips):


@@ -392,10 +491,27 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Change Log
 
 
 ## Change Log
 

-### 18.3a5 (unreleased)
+### 18.4a1
+
+* added `--quiet` (#78)

 
 

-* add line breaks before all delimiters, except in cases like commas, to better
-  comply with PEP8 (#73)
+* added automatic parentheses management (#4)
+
+* added [pre-commit](https://pre-commit.com) integration (#103, #104)
+
+* fixed reporting on `--check` with multiple files (#101, #102)
+
+* fixed removing backslash escapes from raw strings (#100, #105)
+
+### 18.4a0
+
+* added `--diff` (#87)
+
+* add line breaks before all delimiters, except in cases like commas, to
+  better comply with PEP 8 (#73)
+
+* standardize string literals to use double quotes (almost) everywhere
+  (#75)

 
 * fixed handling of standalone comments within nested bracketed
   expressions; Black will no longer produce super long lines or put all
 
 * fixed handling of standalone comments within nested bracketed
   expressions; Black will no longer produce super long lines or put all


@@ -404,6 +520,9 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 * fixed 18.3a4 regression: don't crash and burn on empty lines with
   trailing whitespace (#80)
 
 * fixed 18.3a4 regression: don't crash and burn on empty lines with
   trailing whitespace (#80)
 

+* fixed 18.3a4 regression: `# yapf: disable` usage as trailing comment
+  would cause Black to not emit the rest of the file (#95)
+

 * when CTRL+C is pressed while formatting many files, Black no longer
   freaks out with a flurry of asyncio-related exceptions
 
 * when CTRL+C is pressed while formatting many files, Black no longer
   freaks out with a flurry of asyncio-related exceptions
 


@@ -508,13 +627,16 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
 Glued together by [Łukasz Langa](mailto:lukasz@langa.pl).
 
 
 Glued together by [Łukasz Langa](mailto:lukasz@langa.pl).
 

-Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com)
-and [Carl Meyer](mailto:carl@oddbird.net).
+Maintained with [Carol Willing](mailto:carolcode@willingconsulting.com),
+[Carl Meyer](mailto:carl@oddbird.net),
+[Mika Naylor](mailto:mail@autophagy.io), and
+[Zsolt Dollenstein](mailto:zsol.zsol@gmail.com).

 
 Multiple contributions by:
 
 Multiple contributions by:

+* [Anthony Sottile](mailto:asottile@umich.edu)

 * [Artem Malyshev](mailto:proofit404@gmail.com)
 * [Daniel M. Capella](mailto:polycitizen@gmail.com)
 * [Eli Treuherz](mailto:eli.treuherz@cgi.com)
 * Hugo van Kemenade
 * [Artem Malyshev](mailto:proofit404@gmail.com)
 * [Daniel M. Capella](mailto:polycitizen@gmail.com)
 * [Eli Treuherz](mailto:eli.treuherz@cgi.com)
 * Hugo van Kemenade

-* [Mika Naylor](mailto:mail@autophagy.io)
+* [Ivan Katanić](mailto:ivan.katanic@gmail.com)

 * [Osaetin Daniel](mailto:osaetindaniel@gmail.com)
 * [Osaetin Daniel](mailto:osaetindaniel@gmail.com)