]> 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:

264141e3f39c61b014ee6322e26ec59b4abebbf4
[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 :class: this-will-duplicate-information-and-it-is-still-useful-here
9 ```
10
11 ## Does Black have an API?
12
13 Not yet. _Black_ is fundamentally a command line tool. Many
14 [integrations](integrations/index.rst) are provided, but a Python interface is not one
15 of them. A simple API is being [planned](https://github.com/psf/black/issues/779)
16 though.
17
18 ## Is Black safe to use?
19
20 Yes. _Black_ is strictly about formatting, nothing else. Black strives to ensure that
21 after formatting the AST 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 Stable. _Black_ aims to enforce one style and one style only, with some room for
30 pragmatism. See [The Black Code Style](the_black_code_style/index.rst) for more details.
31
32 Starting in 2022, the formatting output will be stable for the releases made in the same
33 year (other than unintentional bugs). It is possible to opt-in to the latest formatting
34 styles, using the `--preview` flag.
35
36 ## Why is my file not formatted?
37
38 Most likely because it is ignored in `.gitignore` or excluded with configuration. See
39 [file collection and discovery](usage_and_configuration/file_collection_and_discovery.md)
40 for details.
41
42 ## Why is my Jupyter Notebook cell not formatted?
43
44 _Black_ is timid about formatting Jupyter Notebooks. Cells containing any of the
45 following will not be formatted:
46
47 - automagics (e.g. `pip install black`)
48 - non-Python cell magics (e.g. `%%writeline`)
49 - multiline magics, e.g.:
50
51   ```python
52   %timeit f(1, \
53           2, \
54           3)
55   ```
56
57 - code which `IPython`'s `TransformerManager` would transform magics into, e.g.:
58
59   ```python
60   get_ipython().system('ls')
61   ```
62
63 - invalid syntax, as it can't be safely distinguished from automagics in the absence of
64   a running `IPython` kernel.
65
66 ## Why are Flake8's E203 and W503 violated?
67
68 Because they go against PEP 8. E203 falsely triggers on list
69 [slices](the_black_code_style/current_style.md#slices), and adhering to W503 hinders
70 readability because operators are misaligned. Disable W503 and enable the
71 disabled-by-default counterpart W504. E203 should be disabled while changes are still
72 [discussed](https://github.com/PyCQA/pycodestyle/issues/373).
73
74 ## Which Python versions does Black support?
75
76 Currently the runtime requires Python 3.6-3.10. Formatting is supported for files
77 containing syntax from Python 3.3 to 3.10. We promise to support at least all Python
78 versions that have not reached their end of life. This is the case for both running
79 _Black_ and formatting code.
80
81 Support for formatting Python 2 code was removed in version 22.0. While we've made no
82 plans to stop supporting older Python 3 minor versions immediately, their support might
83 also be removed some time in the future without a deprecation period.
84
85 ## Why does my linter or typechecker complain after I format my code?
86
87 Some linters and other tools use magical comments (e.g., `# noqa`, `# type: ignore`) to
88 influence their behavior. While Black does its best to recognize such comments and leave
89 them in the right place, this detection is not and cannot be perfect. Therefore, you'll
90 sometimes have to manually move these comments to the right place after you format your
91 codebase with _Black_.
92
93 ## Can I run Black with PyPy?
94
95 Yes, there is support for PyPy 3.7 and higher.
96
97 ## Why does Black not detect syntax errors in my code?
98
99 _Black_ is an autoformatter, not a Python linter or interpreter. Detecting all syntax
100 errors is not a goal. It can format all code accepted by CPython (if you find an example
101 where that doesn't hold, please report a bug!), but it may also format some code that
102 CPython doesn't accept.