Unexpected incompatibility with reorder-python-imports

[maxwell-k]

Describe the bug

It is impossible to use Black 24.1.0 alongside reorder-python-imports. Using the example from #1872 , reorder-python-imports produces:

"""Module docstring."""
import typing 

While formatting with black and default arguments produces the following:

"""Module docstring."""

import typing

This new behaviour makes the two tools incompatible. The author of reorder-python-imports suggests this is an issue with Black.

Is it possible to change Black to work better with reorder-python-imports please? I have used both tools together for a long time.

Environment

black, 24.1.0 (compiled: yes)
Python (CPython) 3.12.1

Also checked on the online formatter.

Additional context

A little bit of context from the Black changelog is that Black 24 and above will:

Enforce newline after module docstrings (#3932, #4028)

1872 was the original Black issue, and changes were implemented in 3932; 4028 doesn't relate to imports.

[JelleZijlstra]

It's unfortunate that nobody reported this while the feature was in the preview style and in the alphas. Our guarantee is that we'll keep the style the same for the rest of the year, so we can't change it now.

I think it should be Black's job to decide on whitespace outside the import block, not reorder-python-imports's. Unfortunately that means I don't have a good resolution for you.

[cooperlees]

I'll second Jelle here and state that an import re-ordering tool should respect the syntax it was given when it started it's run.

Here, if there is white space between an import and a docstring, it should be maintained. It's not a formatting tool, the white space has nothing to do with fixing your imports, so I feel this tool is going outside it's scope.

[maxwell-k]

I agree this is unfortunate. I really like the other changes in the current style that was adopted with 24.1.0. I didn't know about the guarantee - I do now . I hadn't thought to test the preview style or alphas; probably because I didn't realise this is an uncommon combination of tools. Again I've learnt something, thank you.

I'm sorry if this issue is not the right place for this conversation; the original report is closed, locked as resolved and I'm unable to comment.

For the code I'm working with today # fmt: skip after the closing """ on the problem docstrings is an acceptable workaround.

Reading using black with other tools again; I suggest a simple solution might be to document that these two tools are not compatible, that what I'm trying to do is unsupported.

I think it should be Black's job to decide on whitespace outside the import block, not reorder-python-imports's. Unfortunately that means I don't have a good resolution for you.

Here, if there is white space between an import and a docstring, it should be maintained. It's not a formatting tool, the white space has nothing to do with fixing your imports, so I feel this tool is going outside it's scope.

To get to an important point, now I have seen:

1. the maintainer of the import reordering tool explain that the issue is with the code formatting tool and
2. the maintainers of the code formatting tool explain that the problem is with the import reordering tool

I don't want to comment either way. Today, the two tools are incompatible. If future versions are to be compatible one or both must change. The import reordering tool appears to have ruled out changes. Are changes a possibility for this code formatting tool?

Thank you for you help! Black is a great piece of software.

[JelleZijlstra]

I realize you're in an unfortunate situation where two opinionated tools disagree in an incompatible way, and I wish we'd have known about it during the preview period. I won't rule out changing our style here in the future if there's a good reason to do so, but I think that's unlikely. It's definitely within Black's purview to control whitespace after the module docstring.

Possible workarounds:

• In your CI, ensure that your code is clean if you use reorder-python-imports then Black (or the other way around), instead of running only one of the tools.
• Use a different tool for import sorting, e.g. isort, usort, or Ruff's equivalent of isort.

[maxwell-k]

The only reason to change that I am aware of is to make Black compatible with reorder-python-imports again. Is that a good reason or not? I'll let you decide.

I agree both are opinionated tools with a specific style. I should perhaps make it explicit here that the style implemented by reorder-python-imports has "a single aim: reduce merge conflicts" with a documented rationale. A short example is:

-from typing import Dict, List
+from typing import Dict
+from typing import List

The other functionality in reorder-python-imports is also available in other import sorting tools. I looked at isort and ruff; usort is new to me, thank you for mentioning it. I am not aware of a tool other than reorder-python-imports that implements this "reduce merge conflicts" import style.

isort is the only documented compatible import ordering tool for black. Does that imply anything about future compatibilty?

The ignore comments ( # fmt: skip after the closing """ ) I mentioned above are OK for a short term workaround. Longer term, if neither tool is going to change, you're right I'll need to carefully reconsider my tool choices.

Edited to add: thanks again for dealing with this unfortunate incompatibility carefully. I appreciate your help.

[JelleZijlstra]

Might be worth asking Ruff to implement the one-import-per-line style as an option. (I searched their issue tracker but didn't find an existing issue asking for it.)

[zachborboacryptofi]

maybe just use isort with something like:

[tool.isort]
profile = "black"
force_single_line = "true"