GitHub - google/pyink: Pyink, pronounced pī-ˈiŋk, is a Python formatter, forked from Black with a few different formatting behaviors. (original) (raw)

Pyink, pronounced pī-ˈiŋk, is a Python formatter, forked from_Black_ with a few different formatting behaviors. We intend to keep rebasing on top of Black's latest changes.

Why Pyink?

We would love to adopt Black, but adopting it overnight is too disruptive to the thousands of developers working in our monorepo. We also have other Python tooling that assumes certain formatting, it would be a too big task to update them all at once. We decided to maintain a few local patches to Black as a medium-term solution, and release them as a separate tool called Pyink.

Pyink is intended to be an adoption helper, and we wish to remove as many patches as possible in the future.

What are the main differences?

Pyink:

result = some_other_module._private_function(arg="value") # pylint: disable=protected-access

Black:

result = some_other_module._private_function(
arg="value"
) # pylint: disable=protected-access

Pyink:

from very_long_top_level_package_name.sub_package.another_level import a_long_module

Black:

from very_long_top_level_package_name.sub_package.another_level import (
a_long_module,
)

Pyink:

class MyTest(unittest.TestCase):
def test_magic(self):
...

Black:

class MyTest(unittest.TestCase):
def test_magic(self):
...

Original code:

func1(
(
" lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor"
" incididunt ut labore et dolore magna aliqua Ut enim ad minim"
),
" lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor",
)
func2(
" lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor"
" incididunt ut labore et dolore magna aliqua Ut enim ad minim",
" lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor",
)

Pyink:

func1(
(
" lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor"
" incididunt ut labore et dolore magna aliqua Ut enim ad minim"
),
" lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor",
)
func2(
" lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor"
" incididunt ut labore et dolore magna aliqua Ut enim ad minim",
" lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor",
)

Black:

func1(
" lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor"
" incididunt ut labore et dolore magna aliqua Ut enim ad minim",
" lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor",
)
func2(
" lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor"
" incididunt ut labore et dolore magna aliqua Ut enim ad minim",
" lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor",
)

Historical differences

These are differences that existed in the past. We have upstreamed them to_Black_ so they are now identical.

New:

function_call(
(
" lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor"
" incididunt ut labore et dolore magna aliqua Ut enim ad minim"
),
" veniam quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo",
)

Old:

function_call(
" lorem ipsum dolor sit amet consectetur adipiscing elit sed do eiusmod tempor"
" incididunt ut labore et dolore magna aliqua Ut enim ad minim",
" veniam quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo",
)

New:

some_dictionary["some_key"] = (
some_long_expression_causing_long_line
)

Old:

some_dictionary[
"some_key"
] = some_long_expression_causing_long_line

Pyink:

secrets = frozenset({
1001,
1002,
1003,
1004,
1005,
1006,
1007,
1008,
1009,
})

Black:

secrets = frozenset(
{
1001,
1002,
1003,
1004,
1005,
1006,
1007,
1008,
1009,
}
)

How do I use Pyink?

Same as black, except you'll use pyink. All black command line options are supported by pyink. To configure the options in the pyproject.toml file, you need to put them in the [tool.pyink] section instead of [tool.black].

There are also a few Pyink only options:

  --pyink / --no-pyink            Enable the Pyink formatting mode. Disabling
                                  it should behave the same as Black.
                                  [default: pyink]
  --pyink-indentation [2|4]       The number of spaces used for indentation.
                                  [default: 4]
  --pyink-use-majority-quotes     When normalizing string quotes, infer
                                  preferred quote style by calculating the
                                  majority in the file. Multi-line strings and
                                  docstrings are excluded from this as they
                                  always use double quotes.

Is there a VS Code extension for Pyink?

No, but with a bit workaround, you can use theBlack Formatterextension. After installing Pyink and the extension, you can set these in VS Code's settings.json:

{ "[python]": { "editor.defaultFormatter": "ms-python.black-formatter" }, "black-formatter.path": [ "path/to/pyink" ] }

Can I use Pyink with the pre-commit framework?

Yes! You can put the following in your .pre-commit-config.yaml file:

repos:

Why the name?

We want a name with the same number of characters as Black, to make patching easier. And squid ink is black.

License

MIT

Contributing

See the contribution guide.

Changelog

See CHANGES.md.

Disclaimer

This is not an officially supported Google product.