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>
9.4 KiB
The Uncompromising Code Formatter
“Any color you like.”
Black is the uncompromising Python code formatter. By using it, you agree to cede
control over minutiae of hand-formatting. In return, Black gives you speed,
determinism, and freedom from pycodestyle nagging about formatting. You will save time
and mental energy for more important matters.
Blackened code looks the same regardless of the project you're reading. Formatting becomes transparent after a while and you can focus on the content instead.
Black makes code review faster by producing the smallest diffs possible.
Try it out now using the Black Playground. Watch the PyCon 2019 talk to learn more.
Read the documentation on ReadTheDocs!
Installation and usage
Installation
Black can be installed by running pip install black. It requires Python 3.6.2+ to
run. If you want to format Python 2 code as well, install with
pip install black[python2]. If you want to format Jupyter Notebooks, install with
pip install black[jupyter].
If you can't wait for the latest hotness and want to install from GitHub, use:
pip install git+git://github.com/psf/black
Usage
To get started right away with sensible defaults:
black {source_file_or_directory}
You can run Black as a package if running it as a script doesn't work:
python -m black {source_file_or_directory}
Further information can be found in our docs:
NOTE: This is a beta product
Black is already successfully used by many projects, small and big. Black has a comprehensive test suite, with efficient parallel tests, and our own auto formatting and parallel Continuous Integration runner. However, Black is still beta. Things will probably be wonky for a while. This is made explicit by the "Beta" trove classifier, as well as by the "b" in the version number. What this means for you is that until the formatter becomes stable, you should expect some formatting to change in the future. That being said, no drastic stylistic changes are planned, mostly responses to bug reports.
Also, as a safety measure which slows down processing, Black will check that the
reformatted code still produces a valid AST that is effectively equivalent to the
original (see the
Pragmatism
section for details). If you're feeling confident, use --fast.
The Black code style
Black is a PEP 8 compliant opinionated formatter. Black reformats entire files in place. Style configuration options are deliberately limited and rarely added. It doesn't take previous formatting into account (see Pragmatism for exceptions).
Our documentation covers the current Black code style, but planned changes to it are also documented. They're both worth taking a look:
Please refer to this document before submitting an issue. What seems like a bug might be intended behaviour.
Pragmatism
Early versions of Black used to be absolutist in some respects. They took after its initial author. This was fine at the time as it made the implementation simpler and there were not many users anyway. Not many edge cases were reported. As a mature tool, Black does make some exceptions to rules it otherwise holds.
Please refer to this document before submitting an issue just like with the document above. What seems like a bug might be intended behaviour.
Configuration
Black is able to read project-specific default values for its command line options
from a pyproject.toml file. This is especially useful for specifying custom
--include and --exclude/--force-exclude/--extend-exclude patterns for your
project.
You can find more details in our documentation:
And if you're looking for more general configuration documentation:
Pro-tip: If you're asking yourself "Do I need to configure anything?" the answer is "No". Black is all about sensible defaults. Applying those defaults will have your code in compliance with many other Black formatted projects.
Used by
The following notable open-source projects trust Black with enforcing a consistent code style: pytest, tox, Pyramid, Django Channels, Hypothesis, attrs, SQLAlchemy, Poetry, PyPA applications (Warehouse, Bandersnatch, Pipenv, virtualenv), pandas, Pillow, Twisted, LocalStack, every Datadog Agent Integration, Home Assistant, Zulip, and many more.
The following organizations use Black: Facebook, Dropbox, Mozilla, Quora, Duolingo.
Are we missing anyone? Let us know.
Testimonials
Mike Bayer, author of SQLAlchemy:
I can't think of any single tool in my entire programming career that has given me a bigger productivity increase by its introduction. I can now do refactorings in about 1% of the keystrokes that it would have taken me previously when we had no way for code to format itself.
Dusty Phillips, writer:
Black is opinionated so you don't have to be.
Hynek Schlawack, creator of attrs, core developer of
Twisted and CPython:
An auto-formatter that doesn't suck is all I want for Xmas!
Carl Meyer, Django core developer:
At least the name is good.
Kenneth Reitz, creator of requests and
pipenv:
This vastly improves the formatting of our code. Thanks a ton!
Show your style
Use the badge in your project's README.md:
[](https://github.com/psf/black)
Using the badge in README.rst:
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:target: https://github.com/psf/black
Looks like this:
License
MIT
Contributing
Welcome! Happy to see you willing to make the project better. You can get started by reading this:
You can also take a look at the rest of the contributing docs or talk with the developers:
Change log
The log has become rather long. It moved to its own file.
See CHANGES.
Authors
The author list is quite long nowadays, so it lives in its own file.
See AUTHORS.md
Code of Conduct
Everyone participating in the Black project, and in particular in the issue tracker, pull requests, and social media activity, is expected to treat other people with respect and more generally to follow the guidelines articulated in the Python Community Code of Conduct.
At the same time, humor is encouraged. In fact, basic familiarity with Monty Python's Flying Circus is expected. We are not savages.
And if you really need to slap somebody, do it with a fish while dancing.