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

projects / etc / vim.git / blobdiff
? search:
summary | shortlog | log | commit | commitdiff | tree
raw | inline | side by side
Silence expected stderr (#621)
[etc/vim.git] / README.md
diff --git a/README.md b/README.md
index 244f60d776c06df92ac15f02bc3dc4ecf43471f6..b6218cf2a2bfc7cd846e9a20376d92d5ebe14dd9 100644 (file)
--- a/README.md
+++ b/README.md
@@ -81,6 +81,8 @@ Options:
                               source on standard input).
   -S, --skip-string-normalization
                               Don't normalize string quotes or prefixes.
                               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 would be
   --check                     Don't write the files back, just return the
                               status.  Return code 0 means nothing would
                               change.  Return code 1 means some files would be
@@ -99,7 +101,7 @@ Options:
                               recursive searches. On Windows, use forward
                               slashes for directories.  [default:
                               build/|buck-out/|dist/|_build/|\.git/|\.hg/|
                               recursive searches. On Windows, use forward
                               slashes for directories.  [default:
                               build/|buck-out/|dist/|_build/|\.git/|\.hg/|
-                              \.mypy_cache/|\.tox/|\.venv/]
+                              \.mypy_cache/|\.nox/|\.tox/|\.venv/]
   -q, --quiet                 Don't emit non-error messages to stderr. Errors
                               are still emitted, silence those with
                               2>/dev/null.
   -q, --quiet                 Don't emit non-error messages to stderr. Errors
                               are still emitted, silence those with
                               2>/dev/null.
@@ -141,7 +143,8 @@ original.  This slows it down.  If you're feeling confident, use
 
 *Black* reformats entire files in place.  It is not configurable.  It
 doesn't take previous formatting into account.  It doesn't reformat
 
 *Black* reformats entire files in place.  It is not configurable.  It
 doesn't take previous formatting into account.  It doesn't reformat
-blocks that start with `# fmt: off` and end with `# fmt: on`.  It also
+blocks that start with `# fmt: off` and end with `# fmt: on`. `# fmt: on/off`
+have to be on the same level of indentation. It also
 recognizes [YAPF](https://github.com/google/yapf)'s block comments to
 the same effect, as a courtesy for straddling code.
 
 recognizes [YAPF](https://github.com/google/yapf)'s block comments to
 the same effect, as a courtesy for straddling code.
 
@@ -235,13 +238,13 @@ the following configuration.
 multi_line_output=3
 include_trailing_comma=True
 force_grid_wrap=0
 multi_line_output=3
 include_trailing_comma=True
 force_grid_wrap=0
-combine_as_imports=True
+use_parentheses=True
 line_length=88
 ```
 
 The equivalent command line is:
 ```
 line_length=88
 ```
 
 The equivalent command line is:
 ```
-$ isort --multi-line=3 --trailing-comma --force-grid-wrap=0 --combine-as --line-width=88 [ file.py ]
+$ isort --multi-line=3 --trailing-comma --force-grid-wrap=0 --use-parentheses --line-width=88 [ file.py ]
 ```
 </details>
 
 ```
 </details>
 
@@ -277,7 +280,8 @@ ignore = E501
 ```
 
 You'll find *Black*'s own .flake8 config file is configured like this.
 ```
 
 You'll find *Black*'s own .flake8 config file is configured like this.
-If you're curious about the reasoning behind B950, Bugbear's documentation
+If you're curious about the reasoning behind B950, 
+[Bugbear's documentation](https://github.com/PyCQA/flake8-bugbear#opinionated-warnings)
 explains it.  The tl;dr is "it's like highway speed limits, we won't
 bother you if you overdo it by a few km/h".
 
 explains it.  The tl;dr is "it's like highway speed limits, we won't
 bother you if you overdo it by a few km/h".
 
@@ -355,8 +359,8 @@ string literals that ended up on the same line (see
 [#26](https://github.com/ambv/black/issues/26) for details).
 
 Why settle on double quotes?  They anticipate apostrophes in English
 [#26](https://github.com/ambv/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.  An
-empty string in double quotes (`""`) is impossible to confuse with
+text.  They match the docstring standard described in [PEP 257](https://www.python.org/dev/peps/pep-0257/#what-is-a-docstring).
+An empty string in double quotes (`""`) is impossible to confuse with
 a one double-quote regardless of fonts and syntax highlighting used.
 On top of this, double quotes for strings are consistent with C which
 Python interacts a lot with.
 a one double-quote regardless of fonts and syntax highlighting used.
 On top of this, double quotes for strings are consistent with C which
 Python interacts a lot with.
@@ -374,12 +378,18 @@ an adoption helper, avoid using this for new projects.
 
 ### Numeric literals
 
 
 ### Numeric literals
 
-*Black* standardizes most numeric literals to use lowercase letters: `0xab`
+*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`.
 
 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`.
 
+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
 
 *Black* will break a line before a binary operator when splitting a block
 ### Line breaks & binary operators
 
 *Black* will break a line before a binary operator when splitting a block
@@ -538,6 +548,8 @@ other file.
 If you're running with `--verbose`, you will see a blue message if
 a file was found and used.
 
 If you're running with `--verbose`, you will see a blue message if
 a file was found and used.
 
+Please note `blackd` will not use `pyproject.toml` configuration.
+
 
 ### Configuration format
 
 
 ### Configuration format
 
@@ -663,7 +675,7 @@ 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 'ambv/black'
 ```
 
 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
 ```
 
 or with [Vundle](https://github.com/VundleVim/Vundle.vim):
@@ -714,7 +726,7 @@ Use the [Python extension](https://marketplace.visualstudio.com/items?itemName=m
 Use [sublack plugin](https://github.com/jgirardet/sublack).
 
 
 Use [sublack plugin](https://github.com/jgirardet/sublack).
 
 
-### IPython Notebook Magic
+### Jupyter Notebook Magic
 
 Use [blackcellmagic](https://github.com/csurfer/blackcellmagic).
 
 
 Use [blackcellmagic](https://github.com/csurfer/blackcellmagic).
 
@@ -780,14 +792,14 @@ Options:
 ### Protocol
 
 `blackd` only accepts `POST` requests at the `/` path. The body of the request
 ### Protocol
 
 `blackd` only accepts `POST` requests at the `/` path. The body of the request
-should contain the python source code to be formatted, encoded 
+should contain the python source code to be formatted, encoded
 according to the `charset` field in the `Content-Type` request header. If no
 `charset` is specified, `blackd` assumes `UTF-8`.
 
 There are a few HTTP headers that control how the source is formatted. These
 correspond to command line flags for *Black*. There is one exception to this:
 `X-Protocol-Version` which if present, should have the value `1`, otherwise the
 according to the `charset` field in the `Content-Type` request header. If no
 `charset` is specified, `blackd` assumes `UTF-8`.
 
 There are a few HTTP headers that control how the source is formatted. These
 correspond to command line flags for *Black*. There is one exception to this:
 `X-Protocol-Version` which if present, should have the value `1`, otherwise the
-request is rejected with `HTTP 501` (Not Implemented). 
+request is rejected with `HTTP 501` (Not Implemented).
 
 The headers controlling how code is formatted are:
 
 
 The headers controlling how code is formatted are:
 
@@ -795,6 +807,8 @@ 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-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
  - `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
@@ -925,18 +939,28 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
 
   * numeric literals are normalized to include `_` separators on Python 3.6+ code
 
 
   * numeric literals are normalized to include `_` separators on Python 3.6+ code
 
+  * added `--skip-numeric-underscore-normalization` to disable the above behavior and
+    leave numeric underscores as they were in the input
+
   * code with `_` in numeric literals is recognized as Python 3.6+
 
   * code with `_` in numeric literals is recognized as Python 3.6+
 
-  * most letters in numeric literals are lowercased (e.g., in `1e10` or `0xab`)
+  * most letters in numeric literals are lowercased (e.g., in `1e10`, `0x01`)
+
+  * hexadecimal digits are always uppercased (e.g. `0xBADC0DE`)
 
 * added `blackd`, see [its documentation](#blackd) for more info (#349)
 
 * adjacent string literals are now correctly split into multiple lines (#463)
 
 
 * added `blackd`, see [its documentation](#blackd) for more info (#349)
 
 * adjacent string literals are now correctly split into multiple lines (#463)
 
+* trailing comma is now added to single imports that don't fit on a line (#250)
+
 * cache is now populated when `--check` is successful for a file which speeds up
   consecutive checks of properly formatted unmodified files (#448)
 
 * cache is now populated when `--check` is successful for a file which speeds up
   consecutive checks of properly formatted unmodified files (#448)
 
-* code with `_` in numeric literals is recognized as Python 3.6+ (#461)
+* whitespace at the beginning of the file is now removed (#399)
+
+* fixed mangling [pweave](http://mpastell.com/pweave/) and
+  [Spyder IDE](https://pythonhosted.org/spyder/) special comments (#532)
 
 * fixed unstable formatting when unpacking big tuples (#267)
 
 
 * fixed unstable formatting when unpacking big tuples (#267)
 
@@ -953,7 +977,6 @@ More details can be found in [CONTRIBUTING](CONTRIBUTING.md).
   to be a bad idea (#415)
 
 
   to be a bad idea (#415)
 
 
-
 ### 18.6b4
 
 * hotfix: don't freeze when multiple comments directly precede `# fmt: off` (#371)
 ### 18.6b4
 
 * hotfix: don't freeze when multiple comments directly precede `# fmt: off` (#371)
@@ -1328,3 +1351,4 @@ Multiple contributions by:
 * [Stavros Korokithakis](mailto:hi@stavros.io)
 * [Sunil Kapil](mailto:snlkapil@gmail.com)
 * [Vishwas B Sharma](mailto:sharma.vishwas88@gmail.com)
 * [Stavros Korokithakis](mailto:hi@stavros.io)
 * [Sunil Kapil](mailto:snlkapil@gmail.com)
 * [Vishwas B Sharma](mailto:sharma.vishwas88@gmail.com)
+* [Chuck Wooters](mailto:chuck.wooters@microsoft.com)
vim configuration

Legalese

All content available in this repository is copyright © martin f. krafft, unless otherwise noted.

All files and their content are released under the terms of the Artistic Licence 2.0, unless otherwise noted.

The operator of this repository shall not be held liable for offending content in pages linking to or linked from these page, nor does he endorse their content unless stated otherwise.