-
Notifications
You must be signed in to change notification settings - Fork 21
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Fill out the README and add the PyPI labels
- Loading branch information
1 parent
01d25ae
commit 898534c
Showing
2 changed files
with
85 additions
and
1 deletion.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,4 +1,83 @@ | ||
==== | ||
Blue | ||
==== | ||
|
||
Some folks like black but I prefer blue. | ||
Some folks like `black <https://black.readthedocs.io/en/stable/>`_ but I | ||
prefer `blue <https://blue.readthedocs.io/en/latest/>`_. | ||
|
||
|
||
What is blue? | ||
============= | ||
|
||
``blue`` is a somewhat less uncompromising code formatter than ``black``, the | ||
OG of Python formatters. We love the idea of automatically formatting Python | ||
code, for the same reasons that inspired ``black``, however we take issue with | ||
some of the decisions ``black`` makes. Kudos to ``black`` for pioneering code | ||
formatting for Python, and for its excellent implementation. | ||
|
||
Where the ``blue`` maintainers disagree with the stylistic (and | ||
unconfigurable) choices made by ``black``, we monkeypatch to change these | ||
decisions to our own liking. We intend for these differences to be minimal; | ||
even in cases where we'd prefer something different, there's a lot we can live | ||
with for the sake of consistency. | ||
|
||
We'd prefer not to fork or monkeypatch. Instead, our hope is that eventually | ||
we'll be able to work with the ``black`` maintainers to add just a little bit | ||
of configuration and merge back into the ``black`` project. We'd be ecstatic | ||
if ``blue`` eventually were retired. Until then, we'll maintain our small set | ||
of hacks on top of ``black`` and carefully consider what other deviations are | ||
needed to assuage our sensitive, but experienced, eye. | ||
|
||
|
||
How do I use blue? | ||
================== | ||
|
||
Exactly the same as you would use ``black``. Invoke and configure ``blue`` as | ||
you would ``black`` -- just replace the ``black`` command with ``blue``, sit | ||
back, and enjoy even betterly formatted Python code! You can refer to | ||
`black's <https://black.readthedocs.io/en/stable/>`_ documentation for | ||
anything not listed here. | ||
|
||
|
||
So what's different? | ||
==================== | ||
|
||
Here is a brief list of differences between ``blue`` and ``black``: | ||
|
||
* ``blue`` defaults to single-quoted strings. This is probably the most | ||
painful ``black`` choice to our eyes, and the thing that inspired ``blue``. | ||
We strongly prefer using single quoted strings over double quoted strings | ||
for everything *except* docstrings. Don't ask us why we prefer double | ||
quoted strings for docstrings; it just looks better to us! For all other | ||
strings, ``blue`` defaults to single quoted strings. | ||
|
||
We are `accumulating <https://github.com/grantjenks/blue/issues/2>`_ a list of | ||
other deviations we are considering. As we decide to implement any particular | ||
suggestion, we'll turn those into individual issues and tackle them | ||
one-by-one. If you have suggestions for other deviations from ``black``'s | ||
choices, please open a separate ticket on our tracker, and we'll see how it | ||
goes! | ||
|
||
|
||
Why "blue"? | ||
=========== | ||
|
||
Several reasons! If your formatter is going to beat up your code, it'll leave | ||
it black and blue, or maybe in this case, black *or* blue. Blue is better! | ||
|
||
We also thought about "tan" because, yum! But that project name was already | ||
taken. Frankly, "blue" was also taken, but largely unused. Our thanks to | ||
Nick Ficano for donating the project namespace to us! | ||
|
||
Blue is also the color of `LinkedIn <https://www.linkedin.com/>`_, the | ||
authors' gracious employer, and we intend to socialize its use within our | ||
company code base. | ||
|
||
|
||
Project details | ||
=============== | ||
|
||
* Project home: https://github.com/grantjenks/blue | ||
* Report bugs and suggestions at: https://github.com/grantjenks/blue/issues | ||
* Code hosting: https://github.com/grantjenks/blue.git | ||
* Documentation: https://blue.readthedocs.io/en/latest |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters