]> git.madduck.net Git - etc/vim.git/blob - docs/faq.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:

Create FAQ documentation (GH-2247)
[etc/vim.git] / 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.