Two blank lines after an import should be reduced to one

[kastkeepitjumpinlikekangaroos]

Description

Hey! Trying to contribute for the first time to the project so let me know if I'm missing anything :)

I've implemented changes to address this issue #2020 where there's some inconsistency around how many lines are added after an import. I've added 2 test cases showing that if there is more than 1 blank line between the import and the next line that it is now being reduced to one. One test case was failing because it had in its expected outout 2 lines between the import and following statement, so I think modifying the test case now that it should always be one makes sense.

Checklist - did you ...

• Add an entry in CHANGES.md if necessary?
• Add / update tests if necessary?
• Add new / update outdated documentation?

[kastkeepitjumpinlikekangaroos]

I got an email about this job failure but looks like all the checks are passing on the PR https://github.com/psf/black/actions/runs/11377698063/job/31652281800 is this something that needs to be addressed?

[JelleZijlstra]

Interesting, I suspect some change to how GitHub handles artifacts. Not sure why it doesn't show up here.

[kastkeepitjumpinlikekangaroos]

I got an email about this job failure but looks like all the checks are passing on the PR https://github.com/psf/black/actions/runs/11377698063/job/31652281800 is this something that needs to be addressed?

I got this same error again on the rerun of the workflows https://github.com/psf/black/actions/runs/11483099904/job/31957735676 and seems to be because there's no artifact in this workflow https://github.com/psf/black/actions/runs/11412528080 with the file name .pr-comment.json. If I'm understanding correctly it looks like this is because these tasks which call comment-body (which produces .pr-comment.json https://github.com/psf/black/blob/main/scripts/diff_shades_gha_helper.py#L167) only executes when the matrix mode is preview-changes and the above diff-shades workflow has a matrix mode of analysis

https://github.com/psf/black/blob/main/.github/workflows/diff_shades.yml#L130:

      - name: Generate summary file (PR only)
        if: github.event_name == 'pull_request' && matrix.mode == 'preview-changes'
        run: >
          python helper.py comment-body
          ${{ matrix.baseline-analysis }} ${{ matrix.target-analysis }}
          ${{ matrix.baseline-sha }} ${{ matrix.target-sha }}
          ${{ github.event.pull_request.number }}

      - name: Upload summary file (PR only)
        if: github.event_name == 'pull_request' && matrix.mode == 'preview-changes'
        uses: actions/upload-artifact@v3
        with:
          name: .pr-comment.json
          path: .pr-comment.json

[kastkeepitjumpinlikekangaroos]

hey @JelleZijlstra ! :) just bumping this PR - do the changes look good or are there other modifications you'd like to see?

[hauntsaninja]

Thanks, this looks reasonable

One nit: could you move the logic down next to

black/src/black/lines.py

Lines 674 to 680 in c98fc0c

	if (
	self.previous_line.is_import
	and not current_line.is_import
	and not current_line.is_fmt_pass_converted(first_leaf_matches=is_import)
	and depth == self.previous_line.depth
	):
	return (before or 1), 0

and also add a test case for when imports are within a function?

[kastkeepitjumpinlikekangaroos]

Thanks, this looks reasonable

One nit: could you move the logic down next to

black/src/black/lines.py

Lines 674 to 680 in c98fc0c

	if (
	self.previous_line.is_import
	and not current_line.is_import
	and not current_line.is_fmt_pass_converted(first_leaf_matches=is_import)
	and depth == self.previous_line.depth
	):
	return (before or 1), 0

and also add a test case for when imports are within a function?

@hauntsaninja for sure, let me know if where I moved the logic is what you were thinking!

also moved all the case cases to a single file, added a test case for imports inside a function, and expanded some existing test cases

[JelleZijlstra]

Thanks, just some wordsmithing

[CristinaBotez-Ipsos]

Well this sucks! Ever since I started working in Python (so around 2013) the recommendation was to use 2 blank lines after imports.

[steve-mavens]

@CristinaBotez-Ipsos : it's not as bad as it sounds, because this rule won't violate the higher-priority rule from PEP8, "Surround top-level function and class definitions with two blank lines.". This is a change if you had assignments after your imports, with two blank lines between the imports and the assignments (which means that if you were using isort, you would already have been setting --lines-after-imports=2 to avoid the default behaviour of that tool).

[CristinaBotez-Ipsos]

@steve-mavens: Still feels wrong and inconsistent to have some files that have 1 line of code after imports and others that have 2 lines of code just because functions or classes are defined after imports. Besides this, since one blank line is used to separate the groups of imports, it would be more readable to separate the imports from the rest of the code with 2 blank lines.

[steve-mavens]

@CristinaBotez-Ipsos: sure. One of the minor ways in which black violates PEP8 is that PEP8 explicitly advises prioritising readability over consistency. Whereas black both by nature of an automated tool and by ideology, prioritises consistency over readability. Its axiom in effect is that "familiar but a little bit bad" in the long term across many projects is more readable than "idiosyncratic but marginally better". I still use it, but every January I review that decision when I see the diffs ;-) In this case I personally don't see the diff you get, because I'm already using isort and I ate that change years ago. So, black's position is that it (not you or I) should decide whether the import section deserves 2 blank lines after them in the same way that functions do. Decision apparently is no, it doesn't.

This is all preamble to saying: if you check the original bug report, the intolerable situation was that black just left it alone as either 1 or 2 at the author's preference, instead of expressing an opinion one way or the other. By its nature once that situation is detected, black must either change your code or change mine, because it must not tolerate that inconsistency between your code and mine. I exaggerate because there are exceptions, but this is the principle.

[cobaltt7]

Thanks for your feedback here! I don't think we ever had a proper discussion on whether 1 or 2 lines after the last import was better, and we just went with one of the options. From the arguments made here, I do personally think 2 lines is better.

However, moving forward, I'm not sure what the best course of action would be. Since this has already been released, we can't change it to 2 lines until next January. Plus, while I do think 2 lines are better, this change is small and has minimal effect on readability, while affecting a wide range of code and projects, so I don't know that making any further change would be worth it. Theoretically, our stability policy would allow us to remove the normalization all together in a patch release (back to how v25 was) for the sake of anyone who hasn't yet updated, then change it to normalize to two lines next year, but still that's the same noise two years in a row for everyone who already changed, which is a bit less than half of GitHub repos (open prs closed prs).

It's also worth noting that this feature has been in the preview style since 25.1.0 and was moved to preview in 26.1a1, and we never received any feedback on it before now, which would've allowed us to change it to 2 lines before reaching stable. Again, according to Black's stability policy, the behavior of Black with most settings will never change except in the first release of the year. Since these formatting changes can be anticipated even if you don't follow the issue tracker, we strongly recommend trying out the --preview style sometime around November or December, as well as the beta version we often release around that time, and giving this feedback when it can still have an impact.

[CristinaBotez-Ipsos]

Thank you for your response. Curiously, even though I did not pin the version of this dependency, the new version only got picked up today in both our local environments and the CI/CD. I must admit I was not aware of the way changes are rolled out and the --preview option. I'll know better next time.
If I may ask a possibly stupid question for those more familiar with Black: does always_one_newline_after_import behave like a flag that can be set to true or false?

[cobaltt7]

When this feature was added, it was added under the --preview flag. always_one_newline_after_import behaves more as a label for which code corresponds to which preview style, so it's easy for us to pick and chose come time to move things to stable. Black doesn't allow enabling specific preview styles one by one.
The --preview flag exists for users to opt-in to testing Black's proposed styles. Although --preview can be expected to be mostly bug-free, it does change with every Black version, probably causing you to reformat your code every release.
Now that this feature has been stabilized, always_one_newline_after_import no longer exists. Its functionality was moved into stable and it's not possible to disable it, similarly to how you can only enable or disable the preview style as a whole and not specific styles.

[webartifex]

I am a big fan of black from the first days onward.

Unfortunately, we'll have to drop black now in favor of just ruff (we had both in CI) because of this new rule.

Personally, I would support a style where there is always 2 empty lines after the import section. But that is just taste.

The main problem now with v26.1 is that it applies 1 empty line if the code following the import section is not a class or function def, in which case we get 2 empty lines.

Both ruff and isort offer the option to choose the number of lines and then apply this consistently, which IMO is the more thorough decision.

Anyways, we'll add black back into our project once this is:

• 1 line always (but that would contradict PEP8, so not a real option long-term),
• 2 lines always (that would be in the spirit of black to take style decisions away from teams), or
• give an option to configure this as done by ruff and isort

I feel a bit bad that I did not run black with the --preview flag all year in 2025; otherwise, I would have brought it up.

I also hope this does not lead to some sort of "religious" war :)

Thanks to the black dev team anyways!

[steve-mavens]

"Both ruff and isort offer the option to choose the number of lines and then apply this consistently" - there's a conflict there. black consistently surrounds functions and classes (including any comments and decorators attached to them) with 2 blank lines. You're talking about putting a fixed number of lines after imports, which if set to 1 would violate the rule on surrounding functions and classes. I'm not sure this is explicit, but black's model in effect is that there's padding in various places, and padding can overlap but can't be reduced. So I think of the options you list, the only one that wouldn't be a huge disturbance to black's peace of mind, is "2 always". That is, set the padding after imports to 2 instead of the new-in-2026 value of 1. cobaltt7 discusses that above.

[steve-mavens]

@webartifex: another thing that could happen is ruff format updates to match 2026 black style, including this change. It would then be in conflict with certain options you can set for styling imports, but then it's nothing new in ruff that some options and rules can conflict, and it's up to you to pick.

[webartifex]

@steve-mavens I am not that familiar with the internals in black, just a happy user.

I tried to make it work for our code base by adapting isort and ruff but could'nt make it.

"another thing that could happen is ruff format updates to match 2026 black style"

I would also vote for this!

[AdmiralNemo]

we strongly recommend trying out the --preview style sometime around November or December

...

I feel a bit bad that I did not run black with the --preview flag all year in 2025; otherwise, I would have brought it up.

To me and my team, the point of black is that we can stop worrying about formatting. Everyone just runs black before committing, and it takes away an entire class of discussion points in code reviews. We were completely taken by surprise when CI checks started failing because of code that didn't even change. It seems a bit disingenuous to request that we now have to spend time every year, during one of the busiest times for software engineering professionals, to pay attention to something we specifically adopted so we could stop paying attention to it. I do not feel bad, I feel betrayed.

[steve-mavens]

@AdmiralNemo : Unfortunately, the point of black = * is not to stop worrying about formatting, it's to let black rewrite your code once a year. You are opting in to a process that tinkers around with what it considers to be optimal Python style. This is not the first time it has happened, so you must have just got lucky last year that none of the changes modified your code. As a practical workaround, if you pin a specific version of black then that should be good for about 4-5 years (longer if you continue using obsolete Python versions). Then you can move the dependency at your leisure.

[cobaltt7]

Black's stability policy has always meant that we will introduce new styles in January. As with any open-source project, Black's style will continue to evolve and change. If you wish to avoid sudden changes in your CI runs, then pin Black and review updates periodically using a tool such as Dependabot or Renovate.
Your issue sounds like it has a wider scope than just always_one_newline_after_import, and is a misunderstanding of the promises Black makes. Someday, Black is probably going to make a formatting change that requires you to reformat your code, whether it is this one or a different one. We have the stability policy to minimize the frequency of these changes, not to eliminate them altogether. If you're unable to apply the new changes right away, then don't update Black right away.

[Wulfson]

It's annoying, but I accept that it should remain stable for this year. The question is, can we get it fixed for next year? The perceived inconsistency of "sometimes it's 1, sometimes it's 2" is really bad.