]> git.madduck.net Git - etc/vim.git/blobdiff - README.md

madduck's git repository

Every one of the projects in this repository is available at the canonical URL git://git.madduck.net/madduck/pub/<projectpath> — see each project's metadata for the exact URL.

All patches and comments are welcome. Please squash your changes to logical commits before using git-format-patch and git-send-email to patches@git.madduck.net. If you'd read over the Git project's submission guidelines and adhered to them, I'd be especially grateful.

SSH access, as well as push access can be individually arranged.

If you use my repositories frequently, consider adding the following snippet to ~/.gitconfig and using the third clone URL listed for each project:

[url "git://git.madduck.net/madduck/"]
  insteadOf = madduck:

blib2to3: Never put prefixes on INDENT leaves either
[etc/vim.git] / README.md
index 0978887264ba57f898cbb6cd1fe60f4fefbdc30e..5d3b11850418d970ee389de2a875ee3cc0c9c823 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # black
 
-[![Build Status](https://travis-ci.org/ambv/black.svg?branch=master)](https://travis-ci.org/ambv/black)
+[![Build Status](https://travis-ci.org/ambv/black.svg?branch=master)](https://travis-ci.org/ambv/black) ![License: MIT](https://img.shields.io/github/license/ambv/black.svg) ![PyPI](https://img.shields.io/pypi/v/black.svg) [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 
 > Any color you like.
 
@@ -44,16 +44,24 @@ black [OPTIONS] [SRC]...
 Options:
   -l, --line-length INTEGER   Where to wrap around.  [default: 88]
   --check                     Don't write back the files, just return the
-                              status.  Return code 0 means nothing changed.
-                              Return code 1 means some files were 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.
   --fast / --safe             If --fast given, skip temporary sanity checks.
                               [default: --safe]
   --version                   Show the version and exit.
   --help                      Show this message and exit.
 ```
 
+`Black` is a well-behaved Unix-style command-line tool:
+* it does nothing if no sources are passed to it;
+* 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
+  used).
+
 
 ## The philosophy behind *Black*
 
@@ -76,12 +84,14 @@ or simple statement per line.  If this fits the allotted line length,
 great.
 ```py3
 # in:
+
 l = [1,
      2,
      3,
 ]
 
 # out:
+
 l = [1, 2, 3]
 ```
 
@@ -89,9 +99,11 @@ If not, *Black* will look at the contents of the first outer matching
 brackets and put that in a separate indented line.
 ```py3
 # in:
+
 l = [[n for n in list_bosses()], [n for n in list_employees()]]
 
 # out:
+
 l = [
     [n for n in list_bosses()], [n for n in list_employees()]
 ]
@@ -106,12 +118,14 @@ matching brackets.  If that doesn't work, it will put all of them in
 separate lines.
 ```py3
 # in:
+
 def very_important_function(template: str, *variables, file: os.PathLike, debug: bool = False):
     """Applies `variables` to the `template` and writes to `file`."""
     with open(file, 'w') as f:
         ...
 
 # out:
+
 def very_important_function(
     template: str,
     *variables,
@@ -203,6 +217,12 @@ body.
 
 * Visual Studio Code: [joslarson.black-vscode](https://marketplace.visualstudio.com/items?itemName=joslarson.black-vscode)
 
+Any tool that can pipe code through *Black* using its stdio mode (just
+[use `-` as the file name](http://www.tldp.org/LDP/abs/html/special-chars.html#DASHREF2)).
+The formatted code will be returned on stdout (unless `--check` was
+passed).  *Black* will still emit messages on stderr but that shouldn't
+affect your use case.
+
 There is currently no integration with any other text editors. Vim and
 Atom/Nuclide integration is planned by the author, others will require
 external contributions.
@@ -231,6 +251,18 @@ and [`pipenv`](https://docs.pipenv.org/):
 > This vastly improves the formatting of our code. Thanks a ton!
 
 
+## Show your style
+
+Use the badge in your project's README.md:
+
+```markdown
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
+```
+
+Looks like this: [![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
+
+
+
 ## Tests
 
 Just run:
@@ -243,8 +275,7 @@ python setup.py test
 
 But you can reformat Python 2 code with it, too.  *Black* is able to parse
 all of the new syntax supported on Python 3.6 but also *effectively all*
-the Python 2 syntax at the same time, as long as you're not using print
-statements.
+the Python 2 syntax at the same time.
 
 By making the code exclusively Python 3.6+, I'm able to focus on the
 quality of the formatting and re-use all the nice features of the new
@@ -275,6 +306,28 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Change Log
 
+### 18.3a4 (unreleased)
+
+* automatic detection of deprecated Python 2 forms of print statements
+  and exec statements in the formatted file (#49)
+
+* use proper spaces for complex expressions in default values of typed
+  function arguments (#60)
+
+* only return exit code 1 when --check is used (#50)
+
+* don't remove single trailing commas from square bracket indexing
+  (#59)
+
+* don't omit whitespace if the previous factor leaf wasn't a math
+  operator (#55)
+
+* omit extra space in kwarg unpacking if it's the first argument (#46)
+
+* omit extra space in [Sphinx auto-attribute comments](http://www.sphinx-doc.org/en/stable/ext/autodoc.html#directive-autoattribute)
+  (#68)
+
+
 ### 18.3a3
 
 * don't remove single empty lines outside of bracketed expressions