Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Contrary to documentation, relative imports cannot pass through the top level #75023

Closed
mhsmith mannequin opened this issue Jul 3, 2017 · 7 comments
Closed

Contrary to documentation, relative imports cannot pass through the top level #75023

mhsmith mannequin opened this issue Jul 3, 2017 · 7 comments
Labels
3.7 only security fixes 3.8 only security fixes docs Documentation in the Doc dir interpreter-core (Objects, Python, Grammar, and Parser dirs) type-feature A feature request or enhancement

Comments

@b5f929de-c21c-4343-aebd-756fd1343a4c
Copy link
Mannequin

mhsmith mannequin commented Jul 3, 2017

BPO 30840
Nosy @brettcannon, @ncoghlan, @ericsnowcurrently, @mhsmith, @nanjekyejoannah
PRs
  • bpo-30840: Document relative imports #12831
  • [3.7] bpo-30840: Document relative imports (GH-12831) #12938
  • Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = None
    closed_at = <Date 2019-04-24.15:45:18.225>
    created_at = <Date 2017-07-03.19:14:52.007>
    labels = ['interpreter-core', '3.8', 'type-feature', '3.7', 'docs']
    title = 'Contrary to documentation, relative imports cannot pass through the top level'
    updated_at = <Date 2019-04-24.15:45:18.206>
    user = 'https://github.com/mhsmith'

    bugs.python.org fields:

    activity = <Date 2019-04-24.15:45:18.206>
    actor = 'ncoghlan'
    assignee = 'docs@python'
    closed = True
    closed_date = <Date 2019-04-24.15:45:18.225>
    closer = 'ncoghlan'
    components = ['Documentation', 'Interpreter Core']
    creation = <Date 2017-07-03.19:14:52.007>
    creator = 'Malcolm Smith'
    dependencies = []
    files = []
    hgrepos = []
    issue_num = 30840
    keywords = ['patch']
    message_count = 7.0
    messages = ['297608', '297796', '340288', '340299', '340303', '340780', '340787']
    nosy_count = 6.0
    nosy_names = ['brett.cannon', 'ncoghlan', 'docs@python', 'eric.snow', 'Malcolm Smith', 'nanjekyejoannah']
    pr_nums = ['12831', '12938']
    priority = 'normal'
    resolution = 'fixed'
    stage = 'resolved'
    status = 'closed'
    superseder = None
    type = 'enhancement'
    url = 'https://bugs.python.org/issue30840'
    versions = ['Python 3.7', 'Python 3.8']

    @b5f929de-c21c-4343-aebd-756fd1343a4c
    Copy link
    Mannequin Author

    mhsmith mannequin commented Jul 3, 2017

    https://docs.python.org/3/reference/simple_stmts.html#the-import-statement defers the full specification of relative imports to PEP-328. PEP-328 gives the example "from ...sys import path" in a second-level package, and notes "while that last case is legal, it is certainly discouraged".

    However, in the current implementation it actually isn't legal. Using a stdlib second-level package to test:

    Python 3.5.3 (default, Apr 10 2017, 07:53:16)  [GCC 6.3.0 64 bit (AMD64)] on win32
    Type "help", "copyright", "credits" or "license" for more information.
    >>> import xml.dom
    >>> __package__ = "xml.dom"
    >>> from . import minidom  # Works fine
    >>> from ...sys import path
    Traceback (most recent call last):
      File "<stdin>", line 1, in <module>
    ValueError: attempted relative import beyond top-level package

    Either the documentation or the implementation should be fixed.

    @b5f929de-c21c-4343-aebd-756fd1343a4c mhsmith mannequin added type-bug An unexpected behavior, bug, or error interpreter-core (Objects, Python, Grammar, and Parser dirs) labels Jul 3, 2017
    @bitdancer bitdancer added docs Documentation in the Doc dir 3.7 only security fixes labels Jul 6, 2017
    @ncoghlan
    Copy link
    Contributor

    ncoghlan commented Jul 6, 2017

    That part of the PEP was never implemented - relative imports have never been allowed to cross package boundaries in practice (which is also why "from . import sys" doesn't work as an equivalent to "import sys" at the interactive prompt or in a top level module).

    Rather than amending the PEP, my inclination is to drop that cross-reference from the documentation, and instead add a new subsection to https://docs.python.org/3/reference/import.html covering "Package relative imports"

    The key section that needs to be extracted is https://www.python.org/dev/peps/pep-0328/#guido-s-decision (minus the part about cross-package relative imports being permitted).

    The following section about __name__ is also worth including but needs to be updated to account for __package__ (added by PEP-366), and __spec__ (added by PEP-451).

    @nanjekyejoannah
    Copy link
    Member

    I actually opened a PR with the relevant documentation suggested by @ncoghlan but what am wondering is.

    when @ncoghlan says That part of the PEP was never implemented - relative imports have never been allowed to cross package boundaries in practice, does it mean we dont need this to work anymore as was earlier put in the PEP? In which case this issue will be closed if my PR is merged or we should actually implement it to complete everything the PEP specified?

    @brettcannon
    Copy link
    Member

    RE: "does it mean we dont need this to work anymore as was earlier put in the PEP?"

    Correct, we aren't going to implement that part of the PEP ever.

    @nanjekyejoannah
    Copy link
    Member

    Great, thanks for clarity.

    @ncoghlan
    Copy link
    Contributor

    New changeset 70bf713 by Nick Coghlan (Joannah Nanjekye) in branch 'master':
    bpo-30840: Document relative imports (bpo-12831)
    70bf713

    @ncoghlan
    Copy link
    Contributor

    New changeset 4d0233e by Nick Coghlan (Miss Islington (bot)) in branch '3.7':
    bpo-30840: Document relative imports (GH-12831) (GH-12938)
    4d0233e

    @ncoghlan ncoghlan added the 3.8 only security fixes label Apr 24, 2019
    @ncoghlan ncoghlan added type-feature A feature request or enhancement and removed type-bug An unexpected behavior, bug, or error labels Apr 24, 2019
    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    3.7 only security fixes 3.8 only security fixes docs Documentation in the Doc dir interpreter-core (Objects, Python, Grammar, and Parser dirs) type-feature A feature request or enhancement
    Projects
    None yet
    Development

    No branches or pull requests

    4 participants