X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/262230a13b5ff18a433222a046725d2f3423bd81..642f240253324b7f342529b429979abc5227e66d:/README.md

diff --git a/README.md b/README.md
index 0571a97..57f3ac2 100644
--- a/README.md
+++ b/README.md
@@ -74,18 +74,20 @@ Options:
 * it will read from standard input and write to standard output if `-`
   is used as the filename;
 * it only outputs messages to users on standard error;
-* exits with code 0 unless an internal error occured (or `--check` was
+* exits with code 0 unless an internal error occurred (or `--check` was
   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
@@ -340,7 +346,78 @@ interesting cases:
 
 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.
+further split on.  If there is only a single delimiter and the expression
+starts or ends with a bracket, the parenthesis can also be successfully
+omitted since the existing bracket pair will organize the expression
+neatly anyway.  Otherwise, the parentheses are added.
+
+Please note that *Black* does not add or remove any additional nested
+parentheses that you might want to have for clarity or further
+code organization.  For example those parentheses are not going to be
+removed:
+```py3
+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:
+```py3
+def example(session):
+    result = (
+        session.query(models.Customer.id)
+        .filter(
+            models.Customer.account_id == account_id,
+            models.Customer.email == email_address,
+        )
+        .order_by(models.Customer.id.asc())
+        .all()
+    )
+```
+
+
+### Typing stub files
+
+PEP 484 describes the syntax for type hints in Python.  One of the
+use cases for typing is providing type annotations for modules which
+cannot contain them directly (they might be written in C, or they might
+be third-party, or their implementation may be overly dynamic, and so on).
+
+To solve this, [stub files with the `.pyi` file
+extension](https://www.python.org/dev/peps/pep-0484/#stub-files) can be
+used to describe typing information for an external module.  Those stub
+files omit the implementation of classes and functions they
+describe, instead they only contain the structure of the file (listing
+globals, functions, and classes with their members).  The recommended
+code style for those files is more terse than PEP 8:
+
+* prefer `...` on the same line as the class/function signature;
+* avoid vertical whitespace between consecutive module-level functions,
+  names, or methods and fields within a single class;
+* use a single blank line between top-level class definitions, or none
+  if the classes are very small.
+
+*Black* enforces the above rules.  There are additional guidelines for
+formatting `.pyi` file that are not enforced yet but might be in
+a future version of the formatter:
+
+* all function bodies should be empty (contain `...` instead of the body);
+* do not use docstrings;
+* prefer `...` over `pass`;
+* for arguments with a default, use `...` instead of the actual default;
+* avoid using string literals in type annotations, stub files support
+  forward references natively (like Python 3.7 code with `from __future__
+  import annotations`);
+* use variable annotations instead of type comments, even for stubs that
+  target older versions of Python;
+* for arguments that default to `None`, use `Optional[]` explicitly;
+* use `float` instead of `Union[int, float]`.
 
 
 ## Editor integration
@@ -435,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
@@ -550,7 +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)
+
+* 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)
 
@@ -560,17 +648,31 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 * math operators now use their respective priorities for delimiting multiline
   expressions (#148)
 
+* optional parentheses are now omitted on expressions that start or end
+  with a bracket and only contain a single operator (#177)
+
 * empty parentheses in a class definition are now removed (#145, #180)
 
 * string prefixes are now standardized to lowercase and `u` is removed
   on Python 3.6+ only code and Python 2.7+ code with the `unicode_literals`
   future import (#188, #198, #199)
 
+* typing stub files (`.pyi`) are now formatted in a style that is consistent
+  with PEP 484 (#207, #210)
+
+* progress when reformatting many files is now reported incrementally
+
+* fixed trailers (content with brackets) being unnecessarily exploded
+  into their own lines after a dedented closing bracket (#119)
+
 * fixed an invalid trailing comma sometimes left in imports (#185)
 
 * fixed non-deterministic formatting when multiple pairs of removable parentheses
   were used (#183)
 
+* fixed multiline strings being unnecessarily wrapped in optional
+  parentheses in long assignments (#215)
+
 * fixed not splitting long from-imports with only a single name
 
 * fixed Python 3.6+ file discovery by also looking at function calls with
@@ -578,6 +680,13 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
   where used both in function signatures with stars and function calls
   with stars but the former would be reformatted to a single line.
 
+* fixed crash on dealing with optional parentheses (#193)
+
+* fixed "is", "is not", "in", and "not in" not considered operators for
+  splitting purposes
+
+* fixed crash when dead symlinks where encountered
+
 
 ### 18.4a4
 
@@ -776,7 +885,9 @@ Multiple contributions by:
 * [Eli Treuherz](mailto:eli.treuherz@cgi.com)
 * Hugo van Kemenade
 * [Ivan Katanić](mailto:ivan.katanic@gmail.com)
+* [Jelle Zijlstra](mailto:jelle.zijlstra@gmail.com)
 * [Jonas Obrist](mailto:ojiidotch@gmail.com)
+* [Miguel Gaiowski](mailto:miggaiowski@gmail.com)
 * [Osaetin Daniel](mailto:osaetindaniel@gmail.com)
 * [Sunil Kapil](mailto:snlkapil@gmail.com)
 * [Vishwas B Sharma](mailto:sharma.vishwas88@gmail.com)