fix(gazelle): Do not resolve absolute imports to sibling modules #3106

amartani · 2025-07-19T01:49:10Z

Currently, gazelle allows absolute imports to be resolved to sibling modules: an import foo statement will resolve to a foo.py file in the same folder if such file exists. This seems to be a Python 2 behavior (ie. pre-from __future__ import absolute_import), and doesn't work on the current rules_python setup.

This behavior is explicitly tested in the siblings_import test case. However, recreating the exact same repository layout from this test case and running bazel test //pkg:unit_test, the test fails with the import failing.

This PR adds a new directive, gazelle:python_resolve_sibling_imports, to allow disabling such behavior.

The actual changes are in 3 places:

In gazelle/python/target.go, the directive is added to if t.siblingSrcs.Contains(fileName) && fileName != filepath.Base(dep.Filepath), which is where the import is converted to a full absolute import if it matches a sibling file;
In gazelle/python/generate.go, the handling of conftest.py was dependent on this behavior (ie. it added a dependency on the module conftest, assuming that it would be resolved to the relative module). That was modified to compute the full absolute module path instead.
In gazelle/python/resolve.go, resolve relative imports even when using file generation mode.

I also explicitly added gazelle:python_resolve_sibling_imports true to any test that breaks if the default value of this directive is changed to false.

converting the import to an appropriate absolute import)

aignas · 2025-07-24T02:40:18Z

Thanks for the PR. Since the current gazelle code would result in un-runnable code, is there a good reason to not default to the correct behaviour and have the flag in case some user wants to do this step-wise?

amartani · 2025-07-24T18:18:35Z

Thanks for the PR. Since the current gazelle code would result in un-runnable code, is there a good reason to not default to the correct behaviour and have the flag in case some user wants to do this step-wise?

Honestly, my main reason is a feeling of "I must be missing something" about it. The sibling import behavior is not accidental: there's code added that only exists for resolving sibling imports, a test that explicitly tests for this behavior, and multiple other tests that implicitly depend on it. And, as far as I know, it was all written much after python2 was unsupported, which is the only reason that I can think of for why this would be desired. That said, I'd be happy to switch the default if you believe that would be ok.

aignas · 2025-07-25T01:09:28Z

I'll wait for other to chime in on here. @arrdem, your insight from the Aspect.dev point of view would be valuable here as well.

dougthor42

I ran this branch against our QuantumIA code base with the directive set to true and false.

When false, there were some changes made. I checked them all and they were indeed because the original behavior was incorrect - foo.py importing math but Gazelle thinks its the sibling math.py.

This is super nice and caught some issues for us, thank you!

is there a good reason to not default to the correct behaviour and have the flag in case some user wants to do this step-wise?

I think one argument against is just subverting expectations. People are probably used to the current behavior and adjusting the current behavior would be disruptive.

The current behavior is not necessarily broken in that it always causes bazel build to fail, but it does mean that targets have more dependencies than strictly required. Those additional deps can cause circular dependencies, especially in file generation mode.

Thus my vote is to adjust the default to the correct behavior: python_resolve_sibling_imports false.

CHANGELOG.md

gazelle/python/testdata/sibling_imports_disabled/README.md

aignas · 2025-07-26T04:29:00Z

I'm +1 for keeping the default and creating a ticket to switch the behaviour when we release 2.0.

amartani · 2025-07-26T18:40:20Z

Changes since the initial PR request:

Switched default to python_resolve_sibling_imports false;
Re-worded PR title and CHANGELOG entry as a fix instead of feat / added since we are changing the default behavior;
Adjusted behavior of relative imports when using gazelle:experimental_allow_relative_imports true and gazelle:python_generation_mode file to also resolve relative imports properly.

dougthor42 · 2025-07-26T22:10:08Z

I'm +1 for keeping the default and creating a ticket to switch the behaviour when we release 2.0.

Oooo sounds like we're about to fight!

Nah I'm kidding of course. I definitely do not feel strongly about adjusting the default to the correct behavior. I'm at like a 3 out of 10. So it'll be pretty easy to convince me otherwise.

amartani · 2025-07-27T00:34:01Z

I'm +1 for keeping the default and creating a ticket to switch the behaviour when we release 2.0.

Oooo sounds like we're about to fight!

Nah I'm kidding of course. I definitely do not feel strongly about adjusting the default to the correct behavior. I'm at like a 3 out of 10. So it'll be pretty easy to convince me otherwise.

My understanding of the documented policy is that, if this is considered a breaking change but "is not too disruptive" (which I think this would fit), then we want to:

Merge this with gazelle: python_resolve_sibling_imports true (preserve existing behavior);
After the next minor version (ie. after 1.6 is "cut"), switch default to false;
On 2.0, remove the directive (if we believe there is no reasonable use case for the previous behavior).

aignas · 2025-07-27T14:36:21Z

Ah sorry... :D I misunderstood/misread/did-not-read properly:

Thus my vote is to adjust the default to the correct behavior: python_resolve_sibling_imports false.

+1 to go with your suggestion. Gazelle does not have the same stability guarantees as rules_python core. This breaking change should not be too disruptive the way I see it.

dougthor42

Thanks, new tests LGTM.

I verified the most recent commit a00ec81 on our repo. All 👍 🎉

gazelle/python/testdata/sibling_imports_disabled/README.md

amartani added 4 commits July 18, 2025 18:37

feat(gazelle) Allow disabling sibling module resolution

dc1dbf1

Add overrides for existing tests that break when directive value flips

4484c85

Fix conftest target inclusion when disabling relative imports (by always

259a5a2

converting the import to an appropriate absolute import)

Add changelog entry

f5d00d3

amartani marked this pull request as ready for review July 19, 2025 01:58

amartani requested review from dougthor42, aignas and rickeylev as code owners July 19, 2025 01:58

Update comments

e66010b

amartani mentioned this pull request Jul 24, 2025

Gazelle will confuse stdlib packages/modules with sibling modules #3097

Open

dougthor42 reviewed Jul 25, 2025

View reviewed changes

CHANGELOG.md Outdated Show resolved Hide resolved

gazelle/python/testdata/sibling_imports_disabled/README.md Show resolved Hide resolved

amartani added 4 commits July 25, 2025 17:18

Merge branch 'main' into martani/no-sibling-import

0e49623

Flip default to false

9f69c62

Add more test cases to sibling_imports_disabled

29e815a

Add new test case for siblings imports disabled in file mode

a00ec81

amartani changed the title ~~feat(gazelle): Allow disabling sibling module resolution~~ fix(gazelle): Do not resolve absolute imports to sibling modules Jul 26, 2025

amartani requested a review from dougthor42 July 26, 2025 18:40

dougthor42 approved these changes Jul 27, 2025

View reviewed changes

gazelle/python/testdata/sibling_imports_disabled/README.md Show resolved Hide resolved

dougthor42 added this pull request to the merge queue Jul 29, 2025

Merged via the queue into bazel-contrib:main with commit ab3e3f7 Jul 29, 2025
3 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(gazelle): Do not resolve absolute imports to sibling modules #3106

fix(gazelle): Do not resolve absolute imports to sibling modules #3106

Uh oh!

amartani commented Jul 19, 2025 •

edited

Loading

Uh oh!

aignas commented Jul 24, 2025

Uh oh!

amartani commented Jul 24, 2025

Uh oh!

aignas commented Jul 25, 2025

Uh oh!

dougthor42 left a comment

Uh oh!

Uh oh!

Uh oh!

aignas commented Jul 26, 2025

Uh oh!

amartani commented Jul 26, 2025

Uh oh!

dougthor42 commented Jul 26, 2025

Uh oh!

amartani commented Jul 27, 2025

Uh oh!

aignas commented Jul 27, 2025

Uh oh!

dougthor42 left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Uh oh!

fix(gazelle): Do not resolve absolute imports to sibling modules #3106

fix(gazelle): Do not resolve absolute imports to sibling modules #3106

Uh oh!

Conversation

amartani commented Jul 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

aignas commented Jul 24, 2025

Uh oh!

amartani commented Jul 24, 2025

Uh oh!

aignas commented Jul 25, 2025

Uh oh!

dougthor42 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

aignas commented Jul 26, 2025

Uh oh!

amartani commented Jul 26, 2025

Uh oh!

dougthor42 commented Jul 26, 2025

Uh oh!

amartani commented Jul 27, 2025

Uh oh!

aignas commented Jul 27, 2025

Uh oh!

dougthor42 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

amartani commented Jul 19, 2025 •

edited

Loading