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.
  25
  26 ## How stable is Black's style?
  27
  28 Quite stable. _Black_ aims to enforce one style and one style only, with some room for
  29 pragmatism. However, _Black_ is still in beta so style changes are both planned and
  30 still proposed on the issue tracker. See
  31 [The Black Code Style](the_black_code_style/index.rst) for more details.
  32
  33 ## Why is my file not formatted?
  34
  35 Most likely because it is ignored in `.gitignore` or excluded with configuration. See
  36 [file collection and discovery](usage_and_configuration/file_collection_and_discovery.md)
  37 for details.
  38
  39 ## Why are Flake8's E203 and W503 violated?
  40
  41 Because they go against PEP 8. E203 falsely triggers on list
  42 [slices](the_black_code_style/current_style.md#slices), and adhering to W503 hinders
  43 readability because operators are misaligned. Disable W503 and enable the
  44 disabled-by-default counterpart W504. E203 should be disabled while changes are still
  45 [discussed](https://github.com/PyCQA/pycodestyle/issues/373).
  46
  47 ## Does Black support Python 2?
  48
  49 For formatting, yes! [Install](getting_started.md#installation) with the `python2` extra
  50 to format Python 2 files too! There are no current plans to drop support, but most
  51 likely it is bound to happen. Sometime. Eventually. In terms of running _Black_ though,
  52 Python 3.6 or newer is required.