b1d0601016
To summarise, based on what was discussed in that issue: due to not being able to parse automagics (e.g. pip install black) without a running IPython kernel, cells with syntax which is parseable by neither ast.parse nor IPython will be skipped cells with multiline magics will be skipped trailing semicolons will be preserved, as they are often put there intentionally in Jupyter Notebooks to suppress unnecessary output Commit history before merge (excluding merge commits): * wip * fixup tests * skip tests if no IPython * install test requirements in ipynb tests * if --ipynb format all as ipynb * wip * add some whole-notebook tests * docstrings * skip multiline magics * add test for nested cell magic * remove ipynb_test.yml, put ipynb tests in tox.ini * add changelog entry * typo * make token same length as magic it replaces * only include .ipynb by default if jupyter dependencies are found * remove logic from const * fixup * fixup * re.compile * noop * clear up * new_src -> dst * early exit for non-python notebooks * add non-python test notebook * add repo with many notebooks to black-primer * install extra dependencies for black-primer * fix planetary computer examples url * dont run on ipynb files by default * add scikit-lego (Expected to change) to black-primer * add ipynb-specific diff * fixup * run on all (including ipynb) by default * remove --include .ipynb from scikit-lego black-primer * use tokenize so as to mirror the exact logic in IPython.core.displayhooks quiet * fixup * 🎨 * clarify docstring * add test for when comment is after trailing semicolon * enumerate(reversed) instead of [::-1] * clarify docstrings * wip * use jupyter and no_jupyter marks * use THIS_DIR * windows fixup * perform safe check cell-by-cell for ipynb * only perform safe check in ipynb if not fast * remove redundant Optional * 🎨 * use typeguard * dont process cell containing transformed magic * require typing extensions before 3.10 so as to have TypeGuard * use dataclasses * mention black[jupyter] in docs as well as in README * add faq * add message to assertion error * add test for indented quieted cell * use tokenize_rt else we cant roundtrip * fmake fronzet set for tokens to ignore when looking for trailing semicolon * remove planetary code examples as recent commits result in changes * use dataclasses which inherit from ast.NodeVisitor * bump typing-extensions so that TypeGuard is available * bump typing-extensions in Pipfile * add test with notebook with empty metadata * pipenv lock * deprivative validate_cell * Update README.md * Update docs/getting_started.md * dont cache notebooks if jupyter dependencies arent found * dont write to cache if jupyter deps are not installed * add notebook which cant be parsed * use clirunner * remove other subprocess calls * add docstring * make verbose and quiet keyword only * 🎨 * run second many test on directory, not on file * test for warning message when running on directory * early return from non-python cell magics * move NothingChanged to report to avoid circular import * remove circular import * reinstate --ipynb flag Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
3.2 KiB
Frequently Asked Questions
The most common questions and issues users face are aggregated to this FAQ.
:local:
:backlinks: none
Does Black have an API?
Not yet. Black is fundamentally a command line tool. Many integrations are provided, but a Python interface is not one of them. A simple API is being planned though.
Is Black safe to use?
Yes, for the most part. Black is strictly about formatting, nothing else. But because
Black is still in beta, some edges are still a bit rough. To combat
issues, the equivalence of code after formatting is
checked with
limited special cases where the code is allowed to differ. If issues are found, an error
is raised and the file is left untouched. Magical comments that influence linters and
other tools, such as # noqa, may be moved by Black. See below for more details.
How stable is Black's style?
Quite stable. Black aims to enforce one style and one style only, with some room for pragmatism. However, Black is still in beta so style changes are both planned and still proposed on the issue tracker. See The Black Code Style for more details.
Why is my file not formatted?
Most likely because it is ignored in .gitignore or excluded with configuration. See
file collection and discovery
for details.
Why is my Jupyter Notebook cell not formatted?
Black is timid about formatting Jupyter Notebooks. Cells containing any of the following will not be formatted:
-
automagics (e.g.
pip install black) -
multiline magics, e.g.:
%timeit f(1, \ 2, \ 3) -
code which
IPython'sTransformerManagerwould transform magics into, e.g.:get_ipython().system('ls') -
invalid syntax, as it can't be safely distinguished from automagics in the absense of a running
IPythonkernel.
Why are Flake8's E203 and W503 violated?
Because they go against PEP 8. E203 falsely triggers on list slices, and adhering to W503 hinders readability because operators are misaligned. Disable W503 and enable the disabled-by-default counterpart W504. E203 should be disabled while changes are still discussed.
Does Black support Python 2?
For formatting, yes! Install with the python2 extra
to format Python 2 files too! There are no current plans to drop support, but most
likely it is bound to happen. Sometime. Eventually. In terms of running Black though,
Python 3.6 or newer is required.
Why does my linter or typechecker complain after I format my code?
Some linters and other tools use magical comments (e.g., # noqa, # type: ignore) to
influence their behavior. While Black does its best to recognize such comments and leave
them in the right place, this detection is not and cannot be perfect. Therefore, you'll
sometimes have to manually move these comments to the right place after you format your
codebase with Black.