Add Black PyCharm 2023.2 integration instructions (#3839)

[etc/vim.git] / docs / faq.md

diff --git a/docs/faq.md b/docs/faq.md
index 88bf35b1e6a40d744c60e152ca2456a90054dc85..8941ca3fe4de9940c153741f3a3a6289d4b3c7a7 100644 (file)
--- a/docs/faq.md
+++ b/docs/faq.md
@@ -5,20 +5,32 @@ The most common questions and issues users face are aggregated to this FAQ.
 ```{contents}
 :local:
 :backlinks: none
 ```{contents}
 :local:
 :backlinks: none

+:class: this-will-duplicate-information-and-it-is-still-useful-here

 ```
 
 ```
 

+## Why spaces? I prefer tabs
+
+PEP 8 recommends spaces over tabs, and they are used by most of the Python community.
+_Black_ provides no options to configure the indentation style, and requests for such
+options will not be considered.
+
+However, we recognise that using tabs is an accessibility issue as well. While the
+option will never be added to _Black_, visually impaired developers may find conversion
+tools such as `expand/unexpand` (for Linux) useful when contributing to Python projects.
+A workflow might consist of e.g. setting up appropriate pre-commit and post-merge git
+hooks, and scripting `unexpand` to run after applying _Black_.
+

 ## Does Black have an API?
 
 Not yet. _Black_ is fundamentally a command line tool. Many
 ## Does Black have an API?
 
 Not yet. _Black_ is fundamentally a command line tool. Many

-[integrations](integrations/index.rst) are provided, but a Python interface is not one
+[integrations](/integrations/index.md) are provided, but a Python interface is not one

 of them. A simple API is being [planned](https://github.com/psf/black/issues/779)
 though.
 
 ## Is Black safe to use?
 
 of them. A simple API is being [planned](https://github.com/psf/black/issues/779)
 though.
 
 ## Is Black safe to use?
 

-Yes, for the most part. _Black_ is strictly about formatting, nothing else. But because
-_Black_ is still in [beta](index.rst), some edges are still a bit rough. To combat
-issues, the equivalence of code after formatting is
+Yes. _Black_ is strictly about formatting, nothing else. Black strives to ensure that
+after formatting the AST is

 [checked](the_black_code_style/current_style.md#ast-before-and-after-formatting) with
 limited special cases where the code is allowed to differ. If issues are found, an error
 is raised and the file is left untouched. Magical comments that influence linters and
 [checked](the_black_code_style/current_style.md#ast-before-and-after-formatting) with
 limited special cases where the code is allowed to differ. If issues are found, an error
 is raised and the file is left untouched. Magical comments that influence linters and


@@ -26,14 +38,12 @@ other tools, such as `# noqa`, may be moved by _Black_. See below for more detai
 
 ## How stable is Black's style?
 
 
 ## How stable is Black's style?
 

-Quite stable. _Black_ aims to enforce one style and one style only, with some room for
-pragmatism. However, _Black_ is still in beta so style changes are both planned and
-still proposed on the issue tracker. See
-[The Black Code Style](the_black_code_style/index.rst) for more details.
+Stable. _Black_ aims to enforce one style and one style only, with some room for
+pragmatism. See [The Black Code Style](the_black_code_style/index.md) for more details.

 
 Starting in 2022, the formatting output will be stable for the releases made in the same
 year (other than unintentional bugs). It is possible to opt-in to the latest formatting
 
 Starting in 2022, the formatting output will be stable for the releases made in the same
 year (other than unintentional bugs). It is possible to opt-in to the latest formatting

-styles, using the `--future` flag.
+styles, using the `--preview` flag.

 
 ## Why is my file not formatted?
 
 
 ## Why is my file not formatted?
 


@@ -47,7 +57,8 @@ _Black_ is timid about formatting Jupyter Notebooks. Cells containing any of the
 following will not be formatted:
 
 - automagics (e.g. `pip install black`)
 following will not be formatted:
 
 - automagics (e.g. `pip install black`)

-- non-Python cell magics (e.g. `%%writeline`)
+- non-Python cell magics (e.g. `%%writefile`). These can be added with the flag
+  `--python-cell-magics`, e.g. `black --python-cell-magics writefile hello.ipynb`.

 - multiline magics, e.g.:
 
   ```python
 - multiline magics, e.g.:
 
   ```python


@@ -73,18 +84,18 @@ readability because operators are misaligned. Disable W503 and enable the
 disabled-by-default counterpart W504. E203 should be disabled while changes are still
 [discussed](https://github.com/PyCQA/pycodestyle/issues/373).
 
 disabled-by-default counterpart W504. E203 should be disabled while changes are still
 [discussed](https://github.com/PyCQA/pycodestyle/issues/373).
 

-## Does Black support Python 2?
+## Which Python versions does Black support?

 
 

-```{warning}
-Python 2 support has been deprecated since 21.10b0.
+Currently the runtime requires Python 3.7-3.11. Formatting is supported for files
+containing syntax from Python 3.3 to 3.11. We promise to support at least all Python
+versions that have not reached their end of life. This is the case for both running
+_Black_ and formatting code.

 
 

-This support will be dropped in the first stable release, expected for January 2022.
-See [The Black Code Style](the_black_code_style/index.rst) for details.
-```
+Support for formatting Python 2 code was removed in version 22.0. While we've made no
+plans to stop supporting older Python 3 minor versions immediately, their support might
+also be removed some time in the future without a deprecation period.

 
 

-For formatting, yes! [Install](getting_started.md#installation) with the `python2` extra
-to format Python 2 files too! In terms of running _Black_ though, Python 3.6 or newer is
-required.
+Runtime support for 3.6 was removed in version 22.10.0.

 
 ## Why does my linter or typechecker complain after I format my code?
 
 
 ## Why does my linter or typechecker complain after I format my code?
 


@@ -94,7 +105,34 @@ them in the right place, this detection is not and cannot be perfect. Therefore,
 sometimes have to manually move these comments to the right place after you format your
 codebase with _Black_.
 
 sometimes have to manually move these comments to the right place after you format your
 codebase with _Black_.
 

-## Can I run black with PyPy?
+## Can I run Black with PyPy?
+
+Yes, there is support for PyPy 3.7 and higher.
+
+## Why does Black not detect syntax errors in my code?
+
+_Black_ is an autoformatter, not a Python linter or interpreter. Detecting all syntax
+errors is not a goal. It can format all code accepted by CPython (if you find an example
+where that doesn't hold, please report a bug!), but it may also format some code that
+CPython doesn't accept.
+
+(labels/mypyc-support)=
+
+## What is `compiled: yes/no` all about in the version output?
+
+While _Black_ is indeed a pure Python project, we use [mypyc] to compile _Black_ into a
+C Python extension, usually doubling performance. These compiled wheels are available
+for 64-bit versions of Windows, Linux (via the manylinux standard), and macOS across all
+supported CPython versions.
+
+Platforms including musl-based and/or ARM Linux distributions, and ARM Windows are
+currently **not** supported. These platforms will fall back to the slower pure Python
+wheel available on PyPI.
+
+If you are experiencing exceptionally weird issues or even segfaults, you can try
+passing `--no-binary black` to your pip install invocation. This flag excludes all
+wheels (including the pure Python wheel), so this command will use the [sdist].

 
 

-Yes, there is support for PyPy 3.7 and higher. You cannot format Python 2 files under
-PyPy, because PyPy's inbuilt ast module does not support this.
+[mypyc]: https://mypyc.readthedocs.io/en/latest/
+[sdist]:
+  https://packaging.python.org/en/latest/glossary/#term-Source-Distribution-or-sdist