black-macchiato

February 16, 2021 · View on GitHub

=============== black-macchiato

.. image:: https://circleci.com/gh/wbolster/black-macchiato.svg?style=svg :target: https://circleci.com/gh/wbolster/black-macchiato

| I see some Python and I want it painted black | — Mick Jagger (The Rolling Stones)

What?

This is a small utility built on top of the black__ Python code formatter to enable formatting of partial files.

__ https://github.com/python/black

Why?

Python code should be black, just like coffee. However, sometimes other people insist on adding milk for unexplicable reasons. Since caffè latte__ is undrinkable, you eventually settle for caffè macchiato__ as a compromise.

__ https://en.wikipedia.org/wiki/Latte __ https://en.wikipedia.org/wiki/Caff%C3%A8_macchiato

In other words, you want to use black for the code you write, but for some reason you cannot convert whole files, e.g. when contributing to upstream codebases that are not under your complete control.

However, partial formatting is not supported by black itself, for various good reasons, and it won't be implemented either (134, 142, 245, 370, 511__).

__ https://github.com/python/black/issues/134 __ https://github.com/python/black/issues/142 __ https://github.com/python/black/issues/245 __ https://github.com/python/black/issues/370 __ https://github.com/python/black/issues/511

This is where black-macchiato enters the stage. This tool is for those who want to do partial formatting anyway. It also accepts indented blocks, which means that you can format an indented method inside a class, or a small block of code.

Note that this tool is a stopgap measure, and you should avoid using it if you can.

How?

To install, use::

pip install black-macchiato

The black-macchiato command reads from standard input, and writes to standard output. Any command line flags are forwarded to black.

Alternatively, you can invoke the module directly through the python executable, which may be preferable depending on your setup. Use python -m macchiato instead of black-macchiato in that case.

Example::

$ echo " if True: print('hi')" | black-macchiato if True: print("hi")

Integrating this piping of input and output with your editor is left as an exercise to the reader. For instance, Vim users can use vim-black-macchiato, and Emacs users can use python-black.el.

__ https://github.com/smbl64/vim-black-macchiato __ https://github.com/wbolster/emacs-python-black

History

License

BSD. See LICENSE.rst.