docs/faq.md

   1 # Frequently Asked Questions
   2
   3 The most common questions and issues users face are aggregated to this FAQ.
   4
   5 ```{contents}
   6 :local:
   7 :backlinks: none
   8 :class: this-will-duplicate-information-and-it-is-still-useful-here
   9 ```
  10
  11 ## Why spaces? I prefer tabs
  12
  13 PEP 8 recommends spaces over tabs, and they are used by most of the Python community.
  14 _Black_ provides no options to configure the indentation style, and requests for such
  15 options will not be considered.
  16
  17 However, we recognise that using tabs is an accessibility issue as well. While the
  18 option will never be added to _Black_, visually impaired developers may find conversion
  19 tools such as `expand/unexpand` (for Linux) useful when contributing to Python projects.
  20 A workflow might consist of e.g. setting up appropriate pre-commit and post-merge git
  21 hooks, and scripting `unexpand` to run after applying _Black_.
  22
  23 ## Does Black have an API?
  24
  25 Not yet. _Black_ is fundamentally a command line tool. Many
  26 [integrations](integrations/index.rst) are provided, but a Python interface is not one
  27 of them. A simple API is being [planned](https://github.com/psf/black/issues/779)
  28 though.
  29
  30 ## Is Black safe to use?
  31
  32 Yes. _Black_ is strictly about formatting, nothing else. Black strives to ensure that
  33 after formatting the AST is
  34 [checked](the_black_code_style/current_style.md#ast-before-and-after-formatting) with
  35 limited special cases where the code is allowed to differ. If issues are found, an error
  36 is raised and the file is left untouched. Magical comments that influence linters and
  37 other tools, such as `# noqa`, may be moved by _Black_. See below for more details.
  38
  39 ## How stable is Black's style?
  40
  41 Stable. _Black_ aims to enforce one style and one style only, with some room for
  42 pragmatism. See [The Black Code Style](the_black_code_style/index.rst) for more details.
  43
  44 Starting in 2022, the formatting output will be stable for the releases made in the same
  45 year (other than unintentional bugs). It is possible to opt-in to the latest formatting
  46 styles, using the `--preview` flag.
  47
  48 ## Why is my file not formatted?
  49
  50 Most likely because it is ignored in `.gitignore` or excluded with configuration. See
  51 [file collection and discovery](usage_and_configuration/file_collection_and_discovery.md)
  52 for details.
  53
  54 ## Why is my Jupyter Notebook cell not formatted?
  55
  56 _Black_ is timid about formatting Jupyter Notebooks. Cells containing any of the
  57 following will not be formatted:
  58
  59 - automagics (e.g. `pip install black`)
  60 - non-Python cell magics (e.g. `%%writeline`). These can be added with the flag
  61   `--python-cell-magics`, e.g. `black --python-cell-magics writeline hello.ipynb`.
  62 - multiline magics, e.g.:
  63
  64   ```python
  65   %timeit f(1, \
  66           2, \
  67           3)
  68   ```
  69
  70 - code which `IPython`'s `TransformerManager` would transform magics into, e.g.:
  71
  72   ```python
  73   get_ipython().system('ls')
  74   ```
  75
  76 - invalid syntax, as it can't be safely distinguished from automagics in the absence of
  77   a running `IPython` kernel.
  78
  79 ## Why are Flake8's E203 and W503 violated?
  80
  81 Because they go against PEP 8. E203 falsely triggers on list
  82 [slices](the_black_code_style/current_style.md#slices), and adhering to W503 hinders
  83 readability because operators are misaligned. Disable W503 and enable the
  84 disabled-by-default counterpart W504. E203 should be disabled while changes are still
  85 [discussed](https://github.com/PyCQA/pycodestyle/issues/373).
  86
  87 ## Which Python versions does Black support?
  88
  89 Currently the runtime requires Python 3.6-3.10. Formatting is supported for files
  90 containing syntax from Python 3.3 to 3.10. We promise to support at least all Python
  91 versions that have not reached their end of life. This is the case for both running
  92 _Black_ and formatting code.
  93
  94 Support for formatting Python 2 code was removed in version 22.0. While we've made no
  95 plans to stop supporting older Python 3 minor versions immediately, their support might
  96 also be removed some time in the future without a deprecation period.
  97
  98 ## Why does my linter or typechecker complain after I format my code?
  99
 100 Some linters and other tools use magical comments (e.g., `# noqa`, `# type: ignore`) to
 101 influence their behavior. While Black does its best to recognize such comments and leave
 102 them in the right place, this detection is not and cannot be perfect. Therefore, you'll
 103 sometimes have to manually move these comments to the right place after you format your
 104 codebase with _Black_.
 105
 106 ## Can I run Black with PyPy?
 107
 108 Yes, there is support for PyPy 3.7 and higher.
 109
 110 ## Why does Black not detect syntax errors in my code?
 111
 112 _Black_ is an autoformatter, not a Python linter or interpreter. Detecting all syntax
 113 errors is not a goal. It can format all code accepted by CPython (if you find an example
 114 where that doesn't hold, please report a bug!), but it may also format some code that
 115 CPython doesn't accept.
 116
 117 (labels/mypyc-support)=
 118
 119 ## What is `compiled: yes/no` all about in the version output?
 120
 121 While _Black_ is indeed a pure Python project, we use [mypyc] to compile _Black_ into a
 122 C Python extension, usually doubling performance. These compiled wheels are available
 123 for 64-bit versions of Windows, Linux (via the manylinux standard), and macOS across all
 124 supported CPython versions.
 125
 126 Platforms including musl-based and/or ARM Linux distributions, and ARM Windows are
 127 currently **not** supported. These platforms will fall back to the slower pure Python
 128 wheel available on PyPI.
 129
 130 If you are experiencing exceptionally weird issues or even segfaults, you can try
 131 passing `--no-binary black` to your pip install invocation. This flag excludes all
 132 wheels (including the pure Python wheel), so this command will use the [sdist].
 133
 134 [mypyc]: https://mypyc.readthedocs.io/en/latest/
 135 [sdist]:
 136   https://packaging.python.org/en/latest/glossary/#term-Source-Distribution-or-sdist