X-Git-Url: https://git.madduck.net/etc/vim.git/blobdiff_plain/5db5697eb14984cb8cf778648ce2563e01567f82..e94bda11c366818d24f864ae03abf076e8f5a297:/README.md diff --git a/README.md b/README.md index 3297f87..e192826 100644 --- a/README.md +++ b/README.md @@ -340,7 +340,76 @@ 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 @@ -552,6 +621,8 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md). ### 18.5a0 (unreleased) +* call chains are now formatted according to the [fluent interfaces](https://en.wikipedia.org/wiki/Fluent_interface) style (#67) + * slices are now formatted according to PEP 8 (#178) * parentheses are now also managed automatically on the right-hand side @@ -560,17 +631,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 +663,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 @@ -778,6 +870,7 @@ Multiple contributions by: * [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)