python / python/cpython

Allow relative imports in the `__main__` module

Open
#126,926 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

type-feature
Dominant language
Python
Stars
77.2k
Forks
35.9k
PR merge metrics
PR metrics pending

Description

Feature or enhancement

Proposal:

Expanding on https://github.com/python/cpython/issues/109853#issuecomment-2076845977

@zooba, were you envisioning to do this for all scenarios where a __main__ module is exists? I think that makes sense for consistency, but we may want to consider all scenarios to make sure the UX makes sense.

AFAICT, these should be all of them:

(this refers to relative imports in the same directory, it does not cover relative imports to the parent directory)

  1. Running a package module via python -m <module>
    • Relative imports already work here, no changes needed.
  2. Running a source or extension module via python -m <module>
    • Relative imports don't work here.
    • Allowing relative imports here feels a bit weird, especially if we were to enable -P by default. For it to run, the module would have to be in sys.path, meaning it probably installed rather than being provided by the user, so there isn't much necessity for relative imports.
  3. Running a package module directly (python <module.zip>)
    • Relative imports already work here, no changes needed.
  4. Running a file directly (python <script.py>)
    • Relative imports don't work here.
  5. Running a command string via python -c <command>
    • Relative imports don't work here.
    • There's no canonical base directory to use as a reference, should we use the current directory?
  6. Running a command string via the stdin
    • Relative imports don't work here.
    • There's no canonical base directory to use as a reference, should we use the current directory?
  7. Running the repl
    • Relative imports don't work here.
    • There's no canonical base directory to use as a reference, should we use the current directory?

I think 4), 5), 6), and 7) are the only use-cases that call for relative imports to work. 2) feels a bit weird, but it may be worth supporting for consistency.

I played a bit with the code, and the implementing this doesn't seem much difficult. I was able to write a working PoC targeting only 4) with much difficulty, so I don't think that's a worry.

Considering this, do we think it makes sense to make this change?
If so, should it cover all scenarios, or do we want to keep some of them as-is?

For further reflection, how much of an actual improvement would this actually be over the current behavior of adding the current directory to sys.path?
I can't help but feel a bit like we are trading one weird behavior for another.

Has this already been discussed elsewhere?

No response given

Links to previous discussion of this feature:

No response

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reading the linked discussion in issue 109853 and compare the seven main execution scenarios listed here, especially direct files, -c, stdin, and the REPL. Determine which cases should support relative imports, what directory should serve as the reference where no canonical base exists, and whether the behavior improves on adding the current directory to sys.path. Done means the supported scope and resulting user experience are agreed before implementation.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
backend
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.