<p align="center">
<a href="https://travis-ci.org/ambv/black"><img alt="Build Status" src="https://travis-ci.org/ambv/black.svg?branch=master"></a>
-<a href="http://black.readthedocs.io/en/latest/?badge=latest"><img alt="Documentation Status" src="http://readthedocs.org/projects/black/badge/?version=latest"></a>
+<a href="http://black.readthedocs.io/en/stable/?badge=stable"><img alt="Documentation Status" src="http://readthedocs.org/projects/black/badge/?version=stable"></a>
<a href="https://coveralls.io/github/ambv/black?branch=master"><img alt="Coverage Status" src="https://coveralls.io/repos/github/ambv/black/badge.svg?branch=master"></a>
-<a href="https://github.com/ambv/black/blob/master/LICENSE"><img alt="License: MIT" src="http://black.readthedocs.io/en/latest/_static/license.svg"></a>
-<a href="https://pypi.python.org/pypi/black"><img alt="PyPI" src="http://black.readthedocs.io/en/latest/_static/pypi.svg"></a>
+<a href="https://github.com/ambv/black/blob/master/LICENSE"><img alt="License: MIT" src="http://black.readthedocs.io/en/stable/_static/license.svg"></a>
+<a href="https://pypi.python.org/pypi/black"><img alt="PyPI" src="http://black.readthedocs.io/en/stable/_static/pypi.svg"></a>
<a href="https://github.com/ambv/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
</p>
* 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).
and `'''`). It will replace the latter with the former as long as it
does not result in more backslash escapes than before.
+*Black* also standardizes string prefixes, making them always lowercase.
+On top of that, if your code is already Python 3.6+ only or it's using
+the `unicode_literals` future import, *Black* will remove `u` from the
+string prefix as it is meaningless in those scenarios.
+
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
in one line, or if the inner expression doesn't have any delimiters to
further split on. Otherwise, the parentheses are always added.
+### 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
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
* 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)
+
+* 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
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 crash when dead symlinks where encountered
+
### 18.4a4
* [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)
projects / etc / vim.git / blobdiff