Package: pyink
Pyink, pronounced pī-ˈiŋk, is a Python formatter, forked fromBlackwith a few different formatting
behaviors. We intend to keep rebasing on top ofBlack's latest changes.WhyPyink?We would love to adoptBlack, 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 toBlackas a
medium-term solution, and release them as a separate tool calledPyink.Pyinkis intended to be an adoption helper, and we wish to remove as many
patches as possible in the future.What are the main differences?Support two-space indentation, using thepyink-indentationoption.Support inferring preferred quote style by calculating the majority in a
file, using thepyink-use-majority-quotesoption.Do not wrap trailing pragma comments if the line exceeds the length only
because of the pragma (seepsf/black#2843). Example# 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-accessDo not wrap imports in parentheses and move them to separate lines (seepsf/black#3324). Example:# Pyink:fromvery_long_top_level_package_name.sub_package.another_levelimporta_long_module# Black:fromvery_long_top_level_package_name.sub_package.another_levelimport(a_long_module,)Add an empty line between class statements without docstrings, and the first
method. We expect we will simply remove this difference fromPyinkat some
point. Example:# Pyink:classMyTest(unittest.TestCase):deftest_magic(self):...# Black:classMyTest(unittest.TestCase):deftest_magic(self):...Module docstrings are formatted same as other docstrings (seepsf/black#3493).Existing parentheses around strings are kept if the content does not fit on
a single line. This is related tohttps://github.com/psf/black/pull/3640where we still want to keep the parentheses around the implicitly
concatenated strings if the code already uses them, making it more obvious
it's a single function argument. Example:# 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",)Temporarily disabled the followingBlackfuture style changes:https://github.com/psf/black/pull/2916https://github.com/psf/black/pull/2278Historical differencesThese are differences that existed in the past. We have upstreamed them toBlackso they are now identical.Wrap concatenated strings in parens for function arguments (seepsf/black#3292). Example:# 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",)Prefer splitting right hand side of assignment statements
(seepsf/black#1498). Example:# New:some_dictionary["some_key"]=(some_long_expression_causing_long_line)# Old:some_dictionary["some_key"]=some_long_expression_causing_long_linePrefer not breaking lines between immediately nested brackets (seepsf/black#1811). Example:# Pyink:secrets=frozenset({1001,1002,1003,1004,1005,1006,1007,1008,1009,})# Black:secrets=frozenset({1001,1002,1003,1004,1005,1006,1007,1008,1009,})Support only formatting selected line ranges, using the--pyink-lines=argument (seepsf/black#830).How do I usePyink?Same asblack, except you'll usepyink. Allblackcommand line options are
supported bypyink. To configure the options in thepyproject.tomlfile, you
need to put them in the[tool.pyink]section instead of[tool.black].There are also a fewPyinkonly 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 forPyink?No, but with a bit workaround, you can use theBlack Formatterextension. After installingPyinkand the extension, you can set these in VS
Code'ssettings.json:{"[python]":{"editor.defaultFormatter":"ms-python.black-formatter"},"black-formatter.path":["path/to/pyink"]}Can I usePyinkwith thepre-commitframework?Yes! You can put the following in your.pre-commit-config.yamlfile:repos:-repo:https://github.com/google/pyinkrev:23.3.0hooks:-id:pyink# It is recommended to specify the latest version of Python# supported by your project here, or alternatively use# pre-commit's default_language_version, see# https://pre-commit.com/#top_level-default_language_versionlanguage_version:python3.9Why the name?We want a name with the same number of characters asBlack, to make patching
easier. And squid ink is black.LicenseMITContributingSee thecontribution guide.ChangelogSeeCHANGES.md.DisclaimerThis is not an officially supported Google product.