Store grammar pickle caches in CACHE_DIR

[etc/vim.git] / README.md

diff --git a/README.md b/README.md
index 3eb8ee4f131bb3bd234b457071895318932bf44c..57f3ac2e8669dfae035ba21cb36968ae6152ea11 100644 (file)
--- a/README.md
+++ b/README.md
@@ -78,14 +78,16 @@ Options:
   used).
 
 
-### NOTE: This is an early pre-release
+### NOTE: This is a beta product
 
-*Black* can already successfully format itself and the standard library.
+*Black* is already successfully used by several projects, small and big.
 It also sports a decent test suite.  However, it is still very new.
 Things will probably be wonky for a while. This is made explicit by the
-"Alpha" trove classifier, as well as by the "a" in the version number.
+"Beta" trove classifier, as well as by the "b" in the version number.
 What this means for you is that **until the formatter becomes stable,
-you should expect some formatting to change in the future**.
+you should expect some formatting to change in the future**.  That being
+said, no drastic stylistic changes are planned, mostly responses to bug
+reports.
 
 Also, as a temporary safety measure, *Black* will check that the
 reformatted code still produces a valid AST that is equivalent to the
@@ -131,13 +133,13 @@ brackets and put that in a separate indented line.
 ```py3
 # in:
 
-l = [[n for n in list_bosses()], [n for n in list_employees()]]
+TracebackException.from_exception(exc, limit, lookup_lines, capture_locals)
 
 # out:
 
-l = [
-    [n for n in list_bosses()], [n for n in list_employees()]
-]
+TracebackException.from_exception(
+    exc, limit, lookup_lines, capture_locals
+)
 ```
 
 If that still doesn't fit the bill, it will decompose the internal
@@ -176,13 +178,13 @@ between two distinct sections of the code that otherwise share the same
 indentation level (like the arguments list and the docstring in the
 example above).
 
-If a line of "from" imports cannot fit in the allotted length, it's always split
-into one per line.  Imports tend to change often and this minimizes diffs, as well
-as enables readers of code to easily find which commit introduced a particular
-import.  This exception also makes *Black* compatible with
-[isort](https://pypi.org/p/isort/).  Use `multi_line_output=3`,
-`include_trailing_comma=True`, `force_grid_wrap=0`, and `line_length=88` in your
-isort config.
+If a data structure literal (tuple, list, set, dict) or a line of "from"
+imports cannot fit in the allotted length, it's always split into one
+element per line.  This minimizes diffs as well as enables readers of
+code to find which commit introduced a particular entry.  This also
+makes *Black* compatible with [isort](https://pypi.org/p/isort/).  Use
+`multi_line_output=3`, `include_trailing_comma=True`,
+`force_grid_wrap=0`, and `line_length=88` in your isort config.
 
 
 ### Line length
@@ -268,6 +270,7 @@ 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 `"""`) over single quotes (`'`
@@ -297,6 +300,7 @@ 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
@@ -308,6 +312,7 @@ 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.
 
+
 ### Slices
 
 PEP 8 [recommends](https://www.python.org/dev/peps/pep-0008/#whitespace-in-expressions-and-statements)
@@ -321,6 +326,7 @@ This behaviour may raise ``E203 whitespace before ':'`` warnings in style guide
 enforcement tools like Flake8. Since ``E203`` 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
@@ -354,13 +360,14 @@ return not (this or that)
 decision = (maybe.this() and values > 0) or (maybe.that() and values < 0)
 ```
 
+
 ### Call chains
 
 Some popular APIs, like ORMs, use call chaining.  This API style is known
 as a [fluent interface](https://en.wikipedia.org/wiki/Fluent_interface).
 *Black* formats those treating dots that follow a call or an indexing
 operation like a very low priority delimiter.  It's easier to show the
-behavior than to explain it.  Look at the example::
+behavior than to explain it.  Look at the example:
 ```py3
 def example(session):
     result = (
@@ -374,6 +381,7 @@ def example(session):
     )
 ```
 
+
 ### Typing stub files
 
 PEP 484 describes the syntax for type hints in Python.  One of the
@@ -504,14 +512,17 @@ to do this.
 
 Use [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode).
 
+
 ### SublimeText 3
 
 Use [sublack plugin](https://github.com/jgirardet/sublack).
 
+
 ### IPython Notebook Magic
 
 Use [blackcellmagic](https://github.com/csurfer/blackcellmagic).
 
+
 ### Other editors
 
 Atom/Nuclide integration is planned by the author, others will
@@ -619,9 +630,15 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Change Log
 
-### 18.5a0 (unreleased)
+### 18.5b0
+
+* call chains are now formatted according to the
+  [fluent interfaces](https://en.wikipedia.org/wiki/Fluent_interface)
+  style (#67)
 
-* call chains are now formatted according to the [fluent interfaces](https://en.wikipedia.org/wiki/Fluent_interface) style (#67)
+* data structure literals (tuples, lists, dictionaries, and sets) are
+  now also always exploded like imports when they don't fit in a single
+  line (#152)
 
 * slices are now formatted according to PEP 8 (#178)