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 ```
   9
  10 ## Does Black have an API?
  11
  12 Not yet. _Black_ is fundamentally a command line tool. Many
  13 [integrations](integrations/index.rst) are provided, but a Python interface is not one
  14 of them. A simple API is being [planned](https://github.com/psf/black/issues/779)
  15 though.
  16
  17 ## Is Black safe to use?
  18
  19 Yes, for the most part. _Black_ is strictly about formatting, nothing else. But because
  20 _Black_ is still in [beta](index.rst), some edges are still a bit rough. To combat
  21 issues, the equivalence of code after formatting is
  22 [checked](the_black_code_style/current_style.md#ast-before-and-after-formatting) with
  23 limited special cases where the code is allowed to differ. If issues are found, an error
  24 is raised and the file is left untouched. Magical comments that influence linters and
  25 other tools, such as `# noqa`, may be moved by _Black_. See below for more details.
  26
  27 ## How stable is Black's style?
  28
  29 Quite stable. _Black_ aims to enforce one style and one style only, with some room for
  30 pragmatism. However, _Black_ is still in beta so style changes are both planned and
  31 still proposed on the issue tracker. See
  32 [The Black Code Style](the_black_code_style/index.rst) for more details.
  33
  34 Starting in 2022, the formatting output will be stable for the releases made in the same
  35 year (other than unintentional bugs). It is possible to opt-in to the latest formatting
  36 styles, using the `--future` flag.
  37
  38 ## Why is my file not formatted?
  39
  40 Most likely because it is ignored in `.gitignore` or excluded with configuration. See
  41 [file collection and discovery](usage_and_configuration/file_collection_and_discovery.md)
  42 for details.
  43
  44 ## Why is my Jupyter Notebook cell not formatted?
  45
  46 _Black_ is timid about formatting Jupyter Notebooks. Cells containing any of the
  47 following will not be formatted:
  48
  49 - automagics (e.g. `pip install black`)
  50 - non-Python cell magics (e.g. `%%writeline`)
  51 - multiline magics, e.g.:
  52
  53   ```python
  54   %timeit f(1, \
  55           2, \
  56           3)
  57   ```
  58
  59 - code which `IPython`'s `TransformerManager` would transform magics into, e.g.:
  60
  61   ```python
  62   get_ipython().system('ls')
  63   ```
  64
  65 - invalid syntax, as it can't be safely distinguished from automagics in the absence of
  66   a running `IPython` kernel.
  67
  68 ## Why are Flake8's E203 and W503 violated?
  69
  70 Because they go against PEP 8. E203 falsely triggers on list
  71 [slices](the_black_code_style/current_style.md#slices), and adhering to W503 hinders
  72 readability because operators are misaligned. Disable W503 and enable the
  73 disabled-by-default counterpart W504. E203 should be disabled while changes are still
  74 [discussed](https://github.com/PyCQA/pycodestyle/issues/373).
  75
  76 ## Does Black support Python 2?
  77
  78 ```{warning}
  79 Python 2 support has been deprecated since 21.10b0.
  80
  81 This support will be dropped in the first stable release, expected for January 2022.
  82 See [The Black Code Style](the_black_code_style/index.rst) for details.
  83 ```
  84
  85 For formatting, yes! [Install](getting_started.md#installation) with the `python2` extra
  86 to format Python 2 files too! In terms of running _Black_ though, Python 3.6 or newer is
  87 required.
  88
  89 ## Why does my linter or typechecker complain after I format my code?
  90
  91 Some linters and other tools use magical comments (e.g., `# noqa`, `# type: ignore`) to
  92 influence their behavior. While Black does its best to recognize such comments and leave
  93 them in the right place, this detection is not and cannot be perfect. Therefore, you'll
  94 sometimes have to manually move these comments to the right place after you format your
  95 codebase with _Black_.
  96
  97 ## Can I run Black with PyPy?
  98
  99 Yes, there is support for PyPy 3.7 and higher. You cannot format Python 2 files under
 100 PyPy, because PyPy's inbuilt ast module does not support this.
 101
 102 ## Why does Black not detect syntax errors in my code?
 103
 104 _Black_ is an autoformatter, not a Python linter or interpreter. Detecting all syntax
 105 errors is not a goal. It can format all code accepted by CPython (if you find an example
 106 where that doesn't hold, please report a bug!), but it may also format some code that
 107 CPython doesn't accept.