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

Use new github token for appveyor release
[etc/vim.git] / README.md
index bd6ebcd01a4ef2e9c1a56ded3a06eb22590b231c..dbb7922d066b24c360ea65764a943d133022ac86 100644 (file)
--- a/README.md
+++ b/README.md
@@ -73,23 +73,21 @@ black [OPTIONS] [SRC]...
 Options:
   -l, --line-length INTEGER       How many characters per line to allow.
                                   [default: 88]
-  -t, --target-version [pypy35|cpy27|cpy33|cpy34|cpy35|cpy36|cpy37|cpy38]
+  -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.  [default: per-file
+                                  *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).
   -S, --skip-string-normalization
                                   Don't normalize string quotes or prefixes.
-  -N, --skip-numeric-underscore-normalization
-                                  Don't normalize underscores in numeric
-                                  literals.
   --check                         Don't write the files back, just return the
                                   status.  Return code 0 means nothing would
                                   change.  Return code 1 means some files
@@ -192,12 +190,12 @@ brackets and put that in a separate indented line.
 ```py3
 # in:
 
-TracebackException.from_exception(exc, limit, lookup_lines, capture_locals)
+ImportantClass.important_method(exc, limit, lookup_lines, capture_locals, extra_argument)
 
 # out:
 
-TracebackException.from_exception(
-    exc, limit, lookup_lines, capture_locals
+ImportantClass.important_method(
+    exc, limit, lookup_lines, capture_locals, extra_argument
 )
 ```
 
@@ -211,7 +209,7 @@ separate lines.
 ```py3
 # in:
 
-def very_important_function(template: str, *variables, file: os.PathLike, debug: bool = False):
+def very_important_function(template: str, *variables, file: os.PathLike, engine: str, header: bool = True, debug: bool = False):
     """Applies `variables` to the `template` and writes to `file`."""
     with open(file, 'w') as f:
         ...
@@ -222,6 +220,8 @@ def very_important_function(
     template: str,
     *variables,
     file: os.PathLike,
+    engine: str,
+    header: bool = True,
     debug: bool = False,
 ):
     """Applies `variables` to the `template` and writes to `file`."""
@@ -395,14 +395,8 @@ an adoption helper, avoid using this for new projects.
 *Black* standardizes most numeric literals to use lowercase letters for the
 syntactic parts and uppercase letters for the digits themselves: `0xAB`
 instead of `0XAB` and `1e10` instead of `1E10`. Python 2 long literals are
-styled as `2L` instead of `2l` to avoid confusion between `l` and `1`. In
-Python 3.6+, *Black* adds underscores to long numeric literals to aid
-readability: `100000000` becomes `100_000_000`.
+styled as `2L` instead of `2l` to avoid confusion between `l` and `1`.
 
-For regions where numerals are grouped differently (like [India](https://en.wikipedia.org/wiki/Indian_numbering_system)
-and [China](https://en.wikipedia.org/wiki/Chinese_numerals#Whole_numbers)),
-the `-N` or `--skip-numeric-underscore-normalization` command line option
-makes *Black* preserve underscores in numeric literals.
 
 ### Line breaks & binary operators
 
@@ -583,7 +577,7 @@ to denote a significant space character.
 ```toml
 [tool.black]
 line-length = 88
-py36 = true
+target_version = ['py37']
 include = '\.pyi?$'
 exclude = '''
 
@@ -626,7 +620,7 @@ configuration from different levels of the file hierarchy.
 Use [proofit404/blacken](https://github.com/proofit404/blacken).
 
 
-### PyCharm
+### PyCharm/IntelliJ IDEA
 
 1. Install `black`.
 
@@ -650,28 +644,37 @@ $ where black
 %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>
-    - Arguments: `$FilePath$`
+    - Arguments: `"$FilePath$"`
 
 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:
 
     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
         - Program: <install_location_from_step_2>
         - Arguments: `$FilePath$`
-        - Output paths to refresh: `$FilePathRelativeToProjectRoot$`
+        - Output paths to refresh: `$FilePath$`
         - Working directory: `$ProjectFileDir$`
+       - Uncheck "Auto-save edited files to trigger the watcher"
 
 ### Vim
 
@@ -772,7 +775,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.
 
-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
 
@@ -823,15 +826,13 @@ The headers controlling how code is formatted are:
  - `X-Skip-String-Normalization`: corresponds to the `--skip-string-normalization`
     command line flag. If present and its value is not the empty string, no string
     normalization will be performed.
- - `X-Skip-Numeric-Underscore-Normalization`: corresponds to the
-    `--skip-numeric-underscore-normalization` command line flag.
  - `X-Fast-Or-Safe`: if set to `fast`, `blackd` will act as *Black* does when
     passed the `--fast` command line flag.
  - `X-Python-Variant`: if set to `pyi`, `blackd` will act as *Black* does when
     passed the `--pyi` command line flag. Otherwise, its value must correspond to
     a Python version or a set of comma-separated Python versions, optionally
-    prefixed with `cpy` or `pypy`. For example, to request code that is compatible
-    with PyPy 3.5 and CPython 3.5, set the header to `pypy3.5,cpy3.5`.
+    prefixed with `py`. For example, to request code that is compatible
+    with Python 3.5 and 3.6, set the header to `py3.5,py3.6`.
 
 If any of these headers are set to invalid values, `blackd` returns a `HTTP 400`
 error response, mentioning the name of the problematic header in the message body.
@@ -950,10 +951,36 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
 ## Change Log
 
-### 18.11b0
+### 19.3b1
+
+* 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
+  *Black*-formatted code should target (#618)
+
+* deprecated `--py36` (use `--target-version=py36` instead) (#724)
+
+* *Black* no longer normalizes numeric literals to include `_` separators (#696)
+
+* long `del` statements are now split into multiple lines (#698)
+
+* type comments are no longer mangled in function signatures
+
+* improved performance of formatting deeply nested data structures (#509)
+
+* *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
 
@@ -1361,6 +1388,7 @@ Multiple contributions by:
 * [Christian Heimes](mailto:christian@python.org)
 * [Daniel M. Capella](mailto:polycitizen@gmail.com)
 * [Eli Treuherz](mailto:eli@treuherz.com)
+* hauntsaninja
 * Hugo van Kemenade
 * [Ivan Katanić](mailto:ivan.katanic@gmail.com)
 * [Jonas Obrist](mailto:ojiidotch@gmail.com)
@@ -1372,5 +1400,6 @@ Multiple contributions by:
 * [Peter Bengtsson](mailto:mail@peterbe.com)
 * [Stavros Korokithakis](mailto:hi@stavros.io)
 * [Sunil Kapil](mailto:snlkapil@gmail.com)
+* [Utsav Shah](mailto:ukshah2@illinois.edu)
 * [Vishwas B Sharma](mailto:sharma.vishwas88@gmail.com)
 * [Chuck Wooters](mailto:chuck.wooters@microsoft.com)