]> 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:

Remove spurious prints
[etc/vim.git] / README.md
index f454e5a2fd00fe4183aa6a529ca9543454d985d5..96e3958fabb045e9fa9feef8ec33b4c1eea41311 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,14 +1,14 @@
-![Black Logo](https://raw.githubusercontent.com/ambv/black/master/docs/_static/logo2-readme.png)
+![Black Logo](https://raw.githubusercontent.com/python/black/master/docs/_static/logo2-readme.png)
 <h2 align="center">The Uncompromising Code Formatter</h2>
 
 <p align="center">
 <h2 align="center">The Uncompromising Code Formatter</h2>
 
 <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="https://travis-ci.org/python/black"><img alt="Build Status" src="https://travis-ci.org/python/black.svg?branch=master"></a>
 <a href="https://black.readthedocs.io/en/stable/?badge=stable"><img alt="Documentation Status" src="https://readthedocs.org/projects/black/badge/?version=stable"></a>
 <a href="https://black.readthedocs.io/en/stable/?badge=stable"><img alt="Documentation Status" src="https://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="https://black.readthedocs.io/en/stable/_static/license.svg"></a>
+<a href="https://coveralls.io/github/python/black?branch=master"><img alt="Coverage Status" src="https://coveralls.io/repos/github/python/black/badge.svg?branch=master"></a>
+<a href="https://github.com/python/black/blob/master/LICENSE"><img alt="License: MIT" src="https://black.readthedocs.io/en/stable/_static/license.svg"></a>
 <a href="https://pypi.org/project/black/"><img alt="PyPI" src="https://black.readthedocs.io/en/stable/_static/pypi.svg"></a>
 <a href="https://pepy.tech/project/black"><img alt="Downloads" src="https://pepy.tech/badge/black"></a>
 <a href="https://pypi.org/project/black/"><img alt="PyPI" src="https://black.readthedocs.io/en/stable/_static/pypi.svg"></a>
 <a href="https://pepy.tech/project/black"><img alt="Downloads" src="https://pepy.tech/badge/black"></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>
+<a href="https://github.com/python/black"><img alt="Code style: black" src="https://img.shields.io/badge/code%20style-black-000000.svg"></a>
 </p>
 
 > “Any color you like.”
 </p>
 
 > “Any color you like.”
@@ -28,6 +28,7 @@ content instead.
 possible.
 
 Try it out now using the [Black Playground](https://black.now.sh).
 possible.
 
 Try it out now using the [Black Playground](https://black.now.sh).
+Watch the [PyCon 2019 talk](https://youtu.be/esZLCuWs_2Y) to learn more.
 
 ---
 
 
 ---
 
@@ -38,6 +39,7 @@ Try it out now using the [Black Playground](https://black.now.sh).
 **[blackd](#blackd)** |
 **[Version control integration](#version-control-integration)** |
 **[Ignoring unmodified files](#ignoring-unmodified-files)** |
 **[blackd](#blackd)** |
 **[Version control integration](#version-control-integration)** |
 **[Ignoring unmodified files](#ignoring-unmodified-files)** |
+**[Used by](#used-by)** |
 **[Testimonials](#testimonials)** |
 **[Show your style](#show-your-style)** |
 **[Contributing](#contributing-to-black)** |
 **[Testimonials](#testimonials)** |
 **[Show your style](#show-your-style)** |
 **[Contributing](#contributing-to-black)** |
@@ -71,12 +73,19 @@ black {source_file_or_directory}
 black [OPTIONS] [SRC]...
 
 Options:
 black [OPTIONS] [SRC]...
 
 Options:
+  -c, --code TEXT                 Format the code passed in as a string.
   -l, --line-length INTEGER       How many characters per line to allow.
                                   [default: 88]
   -t, --target-version [py27|py33|py34|py35|py36|py37|py38]
                                   Python versions that should be supported by
                                   Black's output. [default: per-file auto-
                                   detection]
   -l, --line-length INTEGER       How many characters per line to allow.
                                   [default: 88]
   -t, --target-version [py27|py33|py34|py35|py36|py37|py38]
                                   Python versions that should be supported by
                                   Black's output. [default: per-file auto-
                                   detection]
+  --py36                          Allow using Python 3.6-only syntax on all
+                                  input files.  This will put trailing commas
+                                  in function signatures and calls also after
+                                  *args and **kwargs. Deprecated; use
+                                  --target-version instead. [default: per-file
+                                  auto-detection]
   --pyi                           Format all input files like typing stubs
                                   regardless of file extension (useful when
                                   piping source on standard input).
   --pyi                           Format all input files like typing stubs
                                   regardless of file extension (useful when
                                   piping source on standard input).
@@ -130,7 +139,7 @@ Options:
 
 ### NOTE: This is a beta product
 
 
 ### NOTE: This is a beta product
 
-*Black* is already successfully used by several projects, small and big.
+*Black* is already [successfully used](#used-by) by many 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
 "Beta" trove classifier, as well as by the "b" in the version number.
 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
 "Beta" trove classifier, as well as by the "b" in the version number.
@@ -364,7 +373,7 @@ 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
 string literals that ended up on the same line (see
 Having one kind of quotes everywhere reduces reader distraction.
 It will also enable a future version of *Black* to merge consecutive
 string literals that ended up on the same line (see
-[#26](https://github.com/ambv/black/issues/26) for details).
+[#26](https://github.com/python/black/issues/26) for details).
 
 Why settle on double quotes?  They anticipate apostrophes in English
 text.  They match the docstring standard described in [PEP 257](https://www.python.org/dev/peps/pep-0257/#what-is-a-docstring).
 
 Why settle on double quotes?  They anticipate apostrophes in English
 text.  They match the docstring standard described in [PEP 257](https://www.python.org/dev/peps/pep-0257/#what-is-a-docstring).
@@ -571,7 +580,7 @@ to denote a significant space character.
 ```toml
 [tool.black]
 line-length = 88
 ```toml
 [tool.black]
 line-length = 88
-target_version = ['py37']
+target-version = ['py37']
 include = '\.pyi?$'
 exclude = '''
 
 include = '\.pyi?$'
 exclude = '''
 
@@ -611,10 +620,11 @@ configuration from different levels of the file hierarchy.
 
 ### Emacs
 
 
 ### Emacs
 
-Use [proofit404/blacken](https://github.com/proofit404/blacken).
+Use [proofit404/blacken](https://github.com/proofit404/blacken) or
+[Elpy](https://github.com/jorgenschaefer/elpy).
 
 
 
 
-### PyCharm
+### PyCharm/IntelliJ IDEA
 
 1. Install `black`.
 
 
 1. Install `black`.
 
@@ -638,21 +648,29 @@ $ where black
 %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
 ```
 
 %LocalAppData%\Programs\Python\Python36-32\Scripts\black.exe  # possible location
 ```
 
-3. Open External tools in PyCharm with `File -> Settings -> Tools -> External Tools`.
+3. Open External tools in PyCharm/IntelliJ IDEA
+
+  On macOS:
+
+```PyCharm -> Preferences -> Tools -> External Tools```
+
+  On Windows / Linux / BSD:
+
+```File -> Settings -> Tools -> External Tools```
 
 4. Click the + icon to add a new external tool with the following values:
     - Name: Black
     - Description: Black is the uncompromising Python code formatter.
     - Program: <install_location_from_step_2>
 
 4. Click the + icon to add a new external tool with the following values:
     - Name: Black
     - Description: Black is the uncompromising Python code formatter.
     - Program: <install_location_from_step_2>
-    - Arguments: `$FilePath$`
+    - Arguments: `"$FilePath$"`
 
 5. Format the currently opened file by selecting `Tools -> External Tools -> black`.
 
 5. Format the currently opened file by selecting `Tools -> External Tools -> black`.
-    - Alternatively, you can set a keyboard shortcut by navigating to `Preferences -> Keymap -> External Tools -> External Tools - Black`.
+    - Alternatively, you can set a keyboard shortcut by navigating to `Preferences or Settings -> Keymap -> External Tools -> External Tools - Black`.
 
 
-6. Optionally, run Black on every file save:
+6. Optionally, run *Black* on every file save:
 
     1. Make sure you have the [File Watcher](https://plugins.jetbrains.com/plugin/7177-file-watchers) plugin installed.
 
     1. Make sure you have the [File Watcher](https://plugins.jetbrains.com/plugin/7177-file-watchers) plugin installed.
-    2. Go to `Preferences -> Tools -> File Watchers` and click `+` to add a new watcher:
+    2. Go to `Preferences or Settings -> Tools -> File Watchers` and click `+` to add a new watcher:
         - Name: Black
         - File type: Python
         - Scope: Project Files
         - Name: Black
         - File type: Python
         - Scope: Project Files
@@ -662,6 +680,38 @@ $ where black
         - Working directory: `$ProjectFileDir$`
        - Uncheck "Auto-save edited files to trigger the watcher"
 
         - Working directory: `$ProjectFileDir$`
        - Uncheck "Auto-save edited files to trigger the watcher"
 
+
+
+### Wing IDE 
+
+Wing supports black via the OS Commands tool, as explained in the Wing documentation on [pep8 formatting](https://wingware.com/doc/edit/pep8). The detailed procedure is:
+
+1. Install `black`.
+
+```console
+$ pip install black
+```
+
+2. Make sure it runs from the command line, e.g.
+
+```console
+$ black --help
+```
+
+3. In Wing IDE, activate the **OS Commands** panel  and define the command  **black** to execute black on the currently selected file:
+
+- Use the Tools -> OS Commands menu selection
+- click on **+** in **OS Commands** -> New: Command line..
+  - Title: black
+  - Command Line: black %s
+  - I/O Encoding: Use Default 
+  - Key Binding: F1
+  - [x] Raise OS Commands when executed
+  - [x] Auto-save files before execution
+  - [x] Line mode
+
+4. Select a file in the editor and press **F1** , or whatever key binding you selected in step 3, to reformat the file.
+
 ### Vim
 
 Commands and shortcuts:
 ### Vim
 
 Commands and shortcuts:
@@ -680,16 +730,16 @@ Configuration:
 To install with [vim-plug](https://github.com/junegunn/vim-plug):
 
 ```
 To install with [vim-plug](https://github.com/junegunn/vim-plug):
 
 ```
-Plug 'ambv/black'
+Plug 'python/black'
 ```
 
 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
 
 ```
 ```
 
 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
 
 ```
-Plugin 'ambv/black'
+Plugin 'python/black'
 ```
 
 ```
 
-or you can copy the plugin from [plugin/black.vim](https://github.com/ambv/black/tree/master/plugin/black.vim).
+or you can copy the plugin from [plugin/black.vim](https://github.com/python/black/tree/master/plugin/black.vim).
 Let me know if this requires any changes to work with Vim 8's builtin
 `packadd`, or Pathogen, and so on.
 
 Let me know if this requires any changes to work with Vim 8's builtin
 `packadd`, or Pathogen, and so on.
 
@@ -761,7 +811,7 @@ 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.
 
 passed).  *Black* will still emit messages on stderr but that shouldn't
 affect your use case.
 
-This can be used for example with PyCharm's [File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).
+This can be used for example with PyCharm's or IntelliJ's [File Watchers](https://www.jetbrains.com/help/pycharm/file-watchers.html).
 
 ## blackd
 
 
 ## blackd
 
@@ -842,7 +892,7 @@ installed](https://pre-commit.com/#install), add this to the
 `.pre-commit-config.yaml` in your repository:
 ```yaml
 repos:
 `.pre-commit-config.yaml` in your repository:
 ```yaml
 repos:
--   repo: https://github.com/ambv/black
+-   repo: https://github.com/python/black
     rev: stable
     hooks:
     - id: black
     rev: stable
     hooks:
     - id: black
@@ -876,6 +926,15 @@ is:
 as .pyi, and whether string normalization was omitted.
 
 
 as .pyi, and whether string normalization was omitted.
 
 
+## Used by
+
+The following notable open-source projects trust *Black* with enforcing
+a consistent code style: pytest, tox, Pyramid, Django Channels, Hypothesis,
+attrs, SQLAlchemy, Poetry, PyPA applications (Warehouse, Pipenv, virtualenv).
+
+Are we missing anyone?  Let us know.
+
+
 ## Testimonials
 
 **Dusty Phillips**, [writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips):
 ## Testimonials
 
 **Dusty Phillips**, [writer](https://smile.amazon.com/s/ref=nb_sb_noss?url=search-alias%3Daps&field-keywords=dusty+phillips):
@@ -902,16 +961,16 @@ and [`pipenv`](https://docs.pipenv.org/):
 Use the badge in your project's README.md:
 
 ```markdown
 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)
+[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/python/black)
 ```
 
 Using the badge in README.rst:
 ```
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
 ```
 
 Using the badge in README.rst:
 ```
 .. image:: https://img.shields.io/badge/code%20style-black-000000.svg
-    :target: https://github.com/ambv/black
+    :target: https://github.com/python/black
 ```
 
 ```
 
-Looks like this: [![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/python/black)
 
 
 ## License
 
 
 ## License
@@ -937,12 +996,33 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Change Log
 
 
 ## Change Log
 
+### 19.5b0
+
+* don't crash when run on a Windows machine with more than 61 cores (#838)
+
+* remove unnecessary parentheses around `yield` expressions (#834)
+
+* add parentheses around long tuples in unpacking assignments (#832)
+
+* don't produce invalid code for `from` ... `import` blocks with comments
+  (#829)
+
+* fix grammar selection (#765)
+
+* fix feature detection for trailing commas in function definitions and
+  call sites (#763)
+
+* add `black -c` as a way to format code passed from the command line (#761)
+
+* fix bug that led *Black* format some code with a line length target of 1
+  (#762)
+
 ### 19.3b0
 
 * new option `--target-version` to control which Python versions
   *Black*-formatted code should target (#618)
 
 ### 19.3b0
 
 * new option `--target-version` to control which Python versions
   *Black*-formatted code should target (#618)
 
-* removed `--py36` (use `--target-version=py36` instead) (#724)
+* deprecated `--py36` (use `--target-version=py36` instead) (#724)
 
 * *Black* no longer normalizes numeric literals to include `_` separators (#696)
 
 
 * *Black* no longer normalizes numeric literals to include `_` separators (#696)
 
@@ -955,6 +1035,12 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 * *Black* now properly formats multiple files in parallel on
   Windows (#632)
 
 * *Black* now properly formats multiple files in parallel on
   Windows (#632)
 
+* *Black* now creates cache files atomically which allows it to be used
+  in parallel pipelines (like `xargs -P8`) (#673)
+
+* *Black* now correctly indents comments in files that were previously
+  formatted with tabs (#262)
+
 * `blackd` now supports CORS (#622)
 
 ### 18.9b0
 * `blackd` now supports CORS (#622)
 
 ### 18.9b0