Black: Provide a way for editor integrations to show warnings on lines Black would change

[shacker]

In the Editor Integration section of the readme, it would be helpful to clarify that black is run in the editor as a formatter, not as a linter. It can "blindly" reformat your whole document, but it does not provide live inline suggestions.

But that raises a question: If we still want live linting, we have to keep e.g. flake8 enabled in the editor. But if we're going to format with black later anyway, what is the point of linting with another tool? Could black be utilized by editor plugins as a live linter so we don't have to use one tool for linting and black for formatting (which is going to change what we did at the linter's suggestion, and lead to discrepancy between what you're writing and what you end up with).

Some clarification here would be helpful. And would love to hear your thoughts on whether black could be both a linter _and_ a formatter.

[shacker]

As a co-worker asked, "Does this mean we can now write crap code and just trust the formatter?"

[ambv]

"Does this mean we can now write crap code and just trust the formatter?

@shacker, yes, exactly, that is a built-in feature. Just write without worry and let the formatter care about making it look decent.

[shacker]

OK thanks. I think that most people think "Editor Integration" means "linting" so it would still be helpful to clarify the difference in that section of the readme.

[shacker]

And could a clever editor plugin author use black to provide inline suggestions?

[ambv]

Black cannot be a linter. It doesn't work by finding issues with current formatting. It works by reformatting the entire file consistently without paying attention to the previous formatting.

Keep flake8, just disable some of the pycodestyle rules. Flake8 contains a lot non-styling related warnings that are very valuable. It's sort of a shame that those always drowned in stupid nits about missing spaces.

[shacker]

Thanks for the clarification! Still think it might be handy to note the difference plainly in the readme. Loving black, thanks for all the work on this.

[ambv]

And could a clever editor plugin author use black to provide inline suggestions?

Yes, with black --diff an editor plugin can show you exactly on which line Black would make changes. So far I didn't prioritize this for any plugins but our internal Nuclide integration at Facebook works like this (via arc lint integration).

[holmboe]

@ambv would you care to show how this integrate with arc lint? I assume you have a custom ArcanistExternalLinter to do this?

For anyone else reading this and curious of the Arcanist integration, here are some links:

• https://secure.phabricator.com/diffusion/ARC/browse/master/src/lint/linter/
• https://secure.phabricator.com/book/phabricator/article/arcanist_lint/

[joelruns]

Both tasks would be much easier to finish (ie: solvable with regex) if the --diff output had line numbers (ie: the non-unified diff format). The increase in annoyance (needing to relearn basic PHP and vim script) for writing both an ArcanistExternalLinter (over just a script-and-regex lint blob in .arclint) and a more complicated ale_linter made me abandon.

Eventually someone will write a flake8 plugin for black and I think the urgency of this task will drop significantly. This seems to be the common lint usage for prettier in eslint as well.

[ambv]

Sorry @joelruns, @holmboe, I meant to share our integration but never did! Here's how you do it: https://gist.github.com/ambv/af475051961126765e35d31bd054e61c

[ambv]

The interesting part is using the built-in ArcanistDiffParser.

[joelruns]

@ambv Thanks for sharing the Arcanist linter! Could you also share a .arclint stub for using this class? For example, I'm not sure what to put for "type" in .arclint.

Currently I'm having trouble setting it up... or should we just use this class as a starting point to set up an ArcanistExternalLinter?

[ambv]

Currently I'm having trouble setting it up... or should we just use this class as a starting point to set up an ArcanistExternalLinter?

I don't understand. "ArcanistExternalLinter" is just a different subtype of "ArcanistLinter". I chose "ArcanistFutureLinter" because that enables up to X concurrent invocations (set to 8 in the Gist I shared).

Could you also share a .arclint stub for using this class?

Use arc linters to see what type you should use in your file. There's more information on https://secure.phabricator.com/book/phabricator/article/arcanist_lint/#configuring-lint.

[joelruns]

Here's a guide to how I got PythonFormatLinter to work with updated (at least as of today) arc.

1. Set up a library for arc to load via this tutorial but add PythonFormatLinter instead of a unit test engine to the source folder
2. You don't need to add lint.engine to .arcconfig since apparently this doesn't work unless your class extends ArcanistLintEngine, which PythonFormatLinter does not
3. Remove getFuturesLimit() from PythonFormatLinter since this is apparently final in parent
4. Remove the line $vcs_root = $this->getVCSRoot(); from PythonFormatLinter since it doesn't work or seem to do anything?
5. Add the following function that returns a string for whatever key you want to use for type in .arclint

public function getLinterConfigurationName() {
  return 'black_or_whatever_you_want_the_key_to_be`
}

1. Add the following stub to your .arclint

"linters": {
  ...,
  "[whatever you want to call this maybe black]": {
    "type": "[whatever string you returned in previous step]",
    "include": "(\\.py$)",
    ...
  }
}

Hope this helps and @ambv please correct if anything I said above is wrong especially step 3. Thanks!